Skip to content

Register a number with the voice platform

POST
/voice/numbers/provision

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.

Authorizations

Parameters

Header Parameters

X-Target-Org-Id
Any of:
string

Request Body required

Register an already-owned number with the voice platform.

Mirrors graph8_livekit.schemas.numbers.Number field-for-field EXCEPT org_id, which is taken from the API key and can never be sent - see the router docstring.

number, not phone_number: this is voice’s field name, and the proxy sends voice’s own wire shape rather than inventing a translation layer that would have to be kept in step with it.

object
assigned_to
Any of:
string
dialer

Provision as a dialer number (no LiveKit).

boolean
inbound_type
Any of:
string
Allowed values: ai sdr dialer work
number
required

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

string
provider

Which carrier holds the number.

string
default: twilio
Allowed values: twilio telnyx
work

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

boolean

Responses

200

Successful Response

object
data
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.

object
key
additional properties
any
pagination
Any of:
object
has_next
required

Whether there are more pages

boolean
limit
required

Items per page

integer
next_cursor
Any of:
string
notes
Any of:
Array<string>
page
required

Current page number (1-indexed)

integer
total
required

Total number of items

integer
total_available
Any of:
integer
total_is_lower_bound
Any of:
boolean

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string