Phone Numbers

Release a phone number

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.

post/phone-numbers/release

Request

  • Base URL: https://be.graph8.com/api/v1
  • URL: https://be.graph8.com/api/v1/phone-numbers/release
  • Auth: HTTP bearer

Headers

Authorizationstring nullable
X-Target-Org-Idstring nullable

Request body

phone_numberstring required

The number to release, E.164.

provider'twilio' | 'telnyx' required

The carrier that holds it. It must match what the number was bought from - releasing a Telnyx number as twilio reaches the wrong provider.

Response

Successful Response

dataPhoneNumberPayload required

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.

Changes

No recorded changes to this operation across all 2 revisions of this API.