Buy a phone number
POST /phone-numbers/purchase
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.
Authorizations
Parameters
Header Parameters
Request Body required
Buy ONE number from the provider. THIS SPENDS CREDITS AND REAL MONEY.
Mirrors phone_numbers.interfaces.fastapi.dtos.PurchasePhoneRequest
field-for-field. capabilities is deliberately absent from both: it was
dropped in the app on 2026-06-02 because the handler never read it and
sending it silently 422’d.
object
True provisions a dialer number; false provisions a voice-AI number.
The number to buy, E.164 (e.g. +14155550123). Search for one first.
Which carrier to buy it from.
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.
Responses
201
Successful Response
object
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
object
Whether there are more pages
Items per page
Current page number (1-indexed)
Total number of items
422
Validation Error