Release a phone number
POST /phone-numbers/release
Give a number back to the carrier. IRREVERSIBLE.
The number returns to the provider’s pool and can be bought by anyone, including a competitor. Inbound calls and messages to it stop reaching this organisation immediately; there is no grace period and no undo.
Order matters and is not transactional: the carrier release happens first, then voice deregistration (best-effort), then the local record. A failure after the carrier release leaves the number gone but the record behind - which is why this returns the outcome rather than a bare 204.
Authorizations
Parameters
Header Parameters
Request Body required
Give a number back to the carrier. IRREVERSIBLE.
Mirrors phone_numbers.interfaces.fastapi.dtos.ReleasePhoneRequest.
object
The number to release, E.164.
The carrier that holds it. It must match what the number was bought from - releasing a Telnyx number as twilio reaches the wrong provider.
Responses
200
Successful Response
object
An open envelope for a purchase result, a release, or an A2P job.
Open on purpose. A purchase returns the stored row (whose capability and
provider-metadata keys differ per provider), a workflow start returns a
workflow_id, and the A2P reconcile returns per-number outcomes that grow
as carriers add statuses. Pinning it would silently drop whatever the
provider reported that this contract had not caught up on.
object
object
Whether there are more pages
Items per page
Current page number (1-indexed)
Total number of items
422
Validation Error