Phone Numbers

Deregister a number from the voice platform

Tear down a number's SIP trunks, dispatch rules and carrier routing.

DOES NOT RELEASE THE NUMBER. The organisation still owns it and is still billed for it by the carrier - it simply stops being answerable. To give it back, use POST /phone-numbers/release, which does this and the carrier release and the local record.

Voice's own handler identifies the number by value with no tenant check, so this route first asserts the caller's organisation owns it. A number that exists in voice but was never recorded against this organisation is a 404.

delete/voice/numbers

Request

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

Headers

Authorizationstring nullable
X-Target-Org-Idstring nullable

Request body

numberstring required

The number to deregister, E.164.

provider'twilio' | 'telnyx'

The carrier to deregister from. Must match how the number was registered, or the provider-side cleanup silently does nothing while the local record still disappears.

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.