Skip to main content
POST
/
api
/
v1
/
phone-numbers
/
{phone_number_id}
/
request-release
curl -X POST "https://app.talkover.ai/api/v1/phone-numbers/phone-uuid-1/request-release" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "We migrated outbound calling to a new toll-free number and no longer need this DID."
  }'

{
  "success": true,
  "data": {
    "id": "request-uuid-1",
    "phone_number_id": "phone-uuid-1",
    "phone_number": "+15551234567",
    "reason": "We migrated outbound calling to a new toll-free number and no longer need this DID.",
    "status": "pending",
    "requested_at": "2024-01-15T12:00:00Z"
  }
}

​
Request Phone Number Release

Submit a release request for a phone number you no longer need. The request enters pending status and is reviewed before the number is actually released.

​
Endpoint

POST /api/v1/phone-numbers/{phone_number_id}/request-release

​
Path parameters

​
phone_number_id
string
required
UUID of the phone number to release.

​
Request headers

​
Authorization
string
required
Bearer token. Format: Bearer talq_your_environment_token_here
​
Content-Type
string
required
Must be set to application/json

​
Request body

​
reason
string
required
Reason for the release. Length: 10–500 characters. Helps support staff review the request faster.

​
Examples

curl -X POST "https://app.talkover.ai/api/v1/phone-numbers/phone-uuid-1/request-release" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "We migrated outbound calling to a new toll-free number and no longer need this DID."
  }'

​
Response

​
Success Response (201 Created)

{
  "success": true,
  "data": {
    "id": "request-uuid-1",
    "phone_number_id": "phone-uuid-1",
    "phone_number": "+15551234567",
    "reason": "We migrated outbound calling to a new toll-free number and no longer need this DID.",
    "status": "pending",
    "requested_at": "2024-01-15T12:00:00Z"
  }
}

​
Error responses

​
409 — Already Pending

{
  "success": false,
  "message": "A release request for this phone number is already pending",
  "code": "RELEASE_ALREADY_PENDING"
}

​
422 — Number In Use

{
  "success": false,
  "message": "Phone number is currently assigned to active agents and cannot be released",
  "code": "PHONE_NUMBER_IN_USE"
}

​
Notes

  • Detach the number from any agents (via Update Agent Calling) before requesting release.
  • A pending request can be cancelled with Cancel Release Request.
  • Once approved, the number is released and cannot be recovered.