Phone Numbers

Buy a phone number

Buy a number from Twilio or Telnyx. THIS SPENDS CREDITS AND REAL MONEY.

Charged on PURCHASE, not on first use: the handler holds credits, buys the number from the carrier, stores it, registers it with the voice platform and only then converts the hold to a charge. A number bought and never dialled has still cost.

Not idempotent by number - buy the same number twice and the second call is a 409 rather than a second charge, but a retry after a timeout you cannot see the outcome of may have already succeeded. Send an Idempotency-Key header; every POST on this API honours it.

402 means insufficient credits and is the one failure worth handling distinctly - the number was not bought and nothing was charged.

post/phone-numbers/purchase

Request

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

Headers

Authorizationstring nullable
X-Target-Org-Idstring nullable

Request body

phone_numberstring required

The number to buy, E.164 (e.g. +14155550123). Search for one first.

provider'twilio' | 'telnyx' required

Which carrier to buy it from.

assigneestring nullable

Who the number belongs to. Defaults to the identity behind the API key, matching the app - it is never taken from the body's organisation, because there is no organisation in the body.

dialerboolean

True provisions a dialer number; false provisions a voice-AI number.

workboolean

True makes this someone's personal work phone - provisioned like a dialer number but tagged work, and never part of the outbound caller-ID rotation pool.

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.