Release a phone number
Release an assigned phone number. By default the number is recycled: its
routing (inbound_url, status_url, campaign_id) is cleared, it enters
a 30-day quarantine, and it then returns to availability. The number stops
receiving inbound webhooks and delivery receipts before the response
returns.
To permanently return the number to the carrier instead, pass
?return_to_carrier=true. This requires the platform:inventory:write
scope in addition to numbers:write; a key with only numbers:write
receives 403 FORBIDDEN and the number is left untouched.
After release, a GET /v1/phone-numbers/{id} for the same number returns
404 NOT_FOUND, because it no longer belongs to your organization.
Requires the numbers:write scope.
Authenticate by sending your API key as a bearer token:
Authorization: Bearer am_live_.... Every request is automatically
scoped to the organization that owns the key and to the scopes granted
to that key.
In: header
Path Parameters
uuidQuery Parameters
falseResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/v1/phone-numbers/497f6eca-6276-4993-bfeb-53cbbbba6f08"{
"success": true,
"data": {
"status": "released"
}
}{
"success": false,
"error": {
"code": "VALIDATION_FAILED",
"message": "validation failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
"details": {
"to": "must be E.164",
"body": "must be 1..1600 chars"
}
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "return_to_carrier is admin-only: forbidden",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "not found",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "VALIDATION_FAILED",
"message": "validation failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
"details": {
"to": "must be E.164",
"body": "must be 1..1600 chars"
}
}
}