Phone Numbers

Register a number with the voice platform

Wire an already-owned number into the voice platform.

BUYS NOTHING. Voice calls this operation purchase and it is published here as provision deliberately: it creates SIP trunks and dispatch rules for a number you already hold, while POST /phone-numbers/purchase is the one that spends credits and buys a DID. Two operations both called "purchase", one of which takes money and one of which does not, is not a distinction to leave to a docstring.

IDEMPOTENT: a number already registered comes back as success rather than an error, and an unverified Telnyx number has its caller-ID verification re-queued on the way through.

Reach for this to repair a purchase whose voice half failed, or to adopt a number bought outside graph8. org_id is taken from the API key.

post/voice/numbers/provision

Request

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

Headers

Authorizationstring nullable
X-Target-Org-Idstring nullable

Request body

numberstring required

The number to register, E.164. You must already own it.

provider'twilio' | 'telnyx'

Which carrier holds the number.

inbound_type'ai' | 'sdr' | 'dialer' | 'work' nullable

How inbound calls are answered. Ignored when dialer or work is set - those paths provision no LiveKit trunks at all and the type is forced to dialer / work respectively.

dialerboolean

Provision as a dialer number (no LiveKit).

workboolean

Provision as someone's personal work phone. Implies dialer.

assigned_tostring nullable

Email of the person this number rings for. REQUIRED in practice for a work number: without it no phone-directory row is created, so the receptionist can never route to them by name.

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.