Buy and provision numbers

Buying a number on Orbit is a four-step loop: search → buy → audit the order → wire the number up. This guide walks the whole loop — single purchases, bulk orders of up to 50 DIDs, the pollable order record, and the provisioning steps that turn an owned DID into one that actually answers calls and messages. Reads (available, country-capabilities, orders) need the numbers:read scope; purchases and post-purchase wiring need numbers:write. The full endpoint surface is at Phone Numbers; the API reference is at Numbers. Outbound termination never touches a third-party carrier — buying a DID provisions inbound routing only, and outbound voice and SMS exit through Orbit’s own network.

1. Number basics

A phone number on Orbit is a DID identified in E.164 format — a leading +, country code, then digits, with no spaces or punctuation (+14155550100). Every endpoint in this guide accepts and returns E.164. Three number types cover different use cases:

Type	Best for	Notes
Local	A geographic presence — a local presence dialer, a city support line	Tied to a city or region. US local numbers can carry two-way SMS under a registered 10DLC campaign.
Toll-free	National inbound lines, high-volume outbound SMS	Callers pay nothing; you absorb the cost. Toll-free SMS is send-only — it is never two-way.
Mobile	Markets where locals expect a mobile-format sender	Availability is country-dependent.

Capabilities are per-number flags for the channels the DID supports. The search filter accepts sms, mms, voice, fax; the purchase-time request accepts sms, voice, whatsapp, rcs. The two enums are deliberately different — a purchase-time OTT registration (whatsapp, rcs) is an add-on requested at provisioning, not something inventory search filters on. Passing a value from the wrong enum returns 422.

2. Search inventory first

Never buy blind. Query live inventory before you construct an order:

curl "https://api.orbit.devotel.io/api/v1/numbers/available?country=US&type=local&capabilities=sms,voice" \
  -H "X-API-Key: dv_live_sk_..."

Each returned row carries an id you should forward into the purchase call (see below), plus monthly_cost and setup_cost as decimal strings, requires_registration, and expected_activation. A row flagged requires_registration: true lands in a regulatory hold unless you attach an approved compliance profile at purchase time. Two discovery helpers narrow the search before you run it:

# Which countries currently have searchable stock
curl "https://api.orbit.devotel.io/api/v1/numbers/available/countries" \
  -H "X-API-Key: dv_live_sk_..."

# Per-country line-type × capability counts (local/mobile/toll-free × SMS/voice)
curl "https://api.orbit.devotel.io/api/v1/numbers/country-capabilities?country=GB" \
  -H "X-API-Key: dv_live_sk_..."

After purchase, audit what you own with the Inventory & Export endpoints — page your inventory, export it to CSV/JSON for finance reconciliation, and subscribe to low-stock alerts. If the country you want is empty, see the Troubleshooting section — and for new inventory programs, the retro order of operations is: preview requirements, then search, then buy.

3. Buy a single DID

In the dashboard, go to Numbers → Buy, search, and check out — the wizard runs the same endpoints below. By API:

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/purchase \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155550100",
    "country_code": "US",
    "capabilities": ["sms", "voice"],
    "id": "did_8f2a91c4"
  }'

Field	Required	Description
`phone_number`	yes	E.164 number to buy.
`country_code`	no	ISO 3166-1 alpha-2. Defaults to `US`.
`capabilities`	no	Subset of `sms`, `voice`, `whatsapp`, `rcs` to provision. When omitted, Orbit provisions what the carrier advertises — pass an explicit set so a voice-only selection on a multi-capability DID does not write a phantom SMS flag onto the record.
`id`	no	The provider-issued row id from `GET /numbers/available`. Forward it: it lets Orbit pass the canonical row straight to the carrier instead of re-parsing the number, and it flags placeholder rows (a DID-group prefix rather than a concrete number) so a compliance gate applies before the carrier order.
`compliance_profile_id`	no	An approved compliance profile covering the target country. Attaching one lets a registration-required number activate immediately instead of entering a regulatory hold. Rejected with `422` if the profile is not approved or does not cover the country.

Pricing is resolved server-side against live inventory — a client-supplied price field is never honoured. The wallet is checked up front; insufficient balance returns 402 with the required and available amounts.

4. Bulk-provision up to 50 numbers

When you already have the exact E.164 list — from GET /numbers/available or your own selection — submit it in one call instead of fifty:

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/buy-bulk \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "phone_number": "+14155550100", "country_code": "US", "id": "did_8f2a91c4" },
      { "phone_number": "+14155550101", "country_code": "US" }
    ],
    "compliance_profile_id": "cmpl_abc123"
  }'

{
  "data": {
    "order_id": "numOrder_01J9Z8ABCDEF",
    "succeeded": [
      { "id": "num_abc123", "phone_number": "+14155550100", "status": "active" }
    ],
    "failed": [
      {
        "phone_number": "+14155550101",
        "error": { "code": "NUMBER_UNAVAILABLE", "message": "Number no longer available" }
      }
    ],
    "total_cost_cents": 300,
    "debited_cents": 150
  }
}

Read the response with partial success in mind:

200 even when every row fails. The status code tells you the request was processed, not the outcome — inspect succeeded.length to decide your UI state.
Failed rows are never charged. total_cost_cents sums every requested item; debited_cents is what was actually charged — only for succeeded. There is no partial-batch debit.
compliance_profile_id applies to every item in the batch — pick one profile per order. The wallet is checked up front against the summed per-number cost, and each item can carry the same provider hint enum as the single purchase.
Rate-limited to 2 requests/minute per tenant, because one call fans out to up to 50 upstream carrier calls.

Need more than 50, or want the platform to pick the block for you instead of posting a pre-built list? Use the bulk-reservation lifecycle — hold up to 1000 DIDs matching a country / area-code / capability filter for 15 minutes, then finalize (purchase, bill, and route) or cancel. It’s documented under Bulk Reserve.

5. Poll and audit the order

Every buy-bulk response carries an order_id — a stable, pollable record of the batch, persisted so partial fulfillment can be audited long after the request returned.

# List recent bulk orders (summaries)
curl "https://api.orbit.devotel.io/api/v1/numbers/orders?limit=20" \
  -H "X-API-Key: dv_live_sk_..."

# Fetch one order with per-line outcomes
curl "https://api.orbit.devotel.io/api/v1/numbers/orders/numOrder_01J9Z8ABCDEF" \
  -H "X-API-Key: dv_live_sk_..."

{
  "data": {
    "order_id": "numOrder_01J9Z8ABCDEF",
    "status": "partial",
    "requested_count": 2,
    "delivered_count": 1,
    "failed_count": 1,
    "total_cost_cents": 300,
    "debited_cents": 150,
    "created_at": "2026-08-24T12:00:00.000Z",
    "lines": [
      {
        "phone_number": "+14155550100",
        "line_status": "delivered",
        "provider": "devotel",
        "country_code": "US",
        "capabilities": ["sms", "voice"],
        "monthly_cost_cents": 150
      },
      {
        "phone_number": "+14155550101",
        "line_status": "failed",
        "error": { "code": "NUMBER_UNAVAILABLE", "message": "Number no longer available" }
      }
    ]
  }
}

The order status is the aggregate across its lines: delivered (all succeeded), partial (some succeeded), or failed (none succeeded). Per line you get the E.164, country, capabilities, monthly cost, and the carrier error for failures — enough to reconcile a bulk provisioning run against finance records without replaying the batch. Orders are org-scoped: an unknown or not-owned id returns 404, not an exists-but-not-yours leak.

6. Wire the number up after purchase

A purchased DID with no route answers with silence. Do these immediately after the buy:

Set the voice route

Pick where inbound calls terminate — an AI agent, IVR, queue, ring group, voicemail, SIP forward, or your own webhook — via the inbound-routing surface, keyed by the number in E.164 form:

curl -X PUT "https://api.orbit.devotel.io/api/v1/numbers/+14155550100/routing" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "queue",
    "config": { "queueId": "que_support" },
    "sms_route_type": "webhook",
    "sms_route_config": { "url": "https://yourapp.com/webhooks/inbound-sms" }
  }'

Voice type and SMS routing (webhook, agent, auto_reply, disabled) are configured independently — set both if the number carries both capabilities. The full route-type catalog is in Phone Numbers.

Register the emergency address

If the number’s users can place calls to emergency services, register a validated dispatchable address per number:

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/num_abc123/emergency-address" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "address_line1": "1 Market St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country_code": "US"
  }'

The address records and validates the dispatchable location for compliance — treat E911 as record-keeping, not a live emergency-calling guarantee. Full surface: Emergency Address.

Set the caller name

Outbound callers see what the carrier CNAM database says. Register your brand per number:

curl -X PUT "https://api.orbit.devotel.io/api/v1/numbers/num_abc123/cnam" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "caller_name": "ACME SUPPORT" }'

Registrations are captured and dispatched on Orbit’s network; propagation to carrier CNAM databases is carrier-paced. Details and spam-label remediation: CNAM & Caller ID. Finally, enable auto-renew so the number never lapses: PATCH /api/v1/numbers/{id}/auto-renew with { "auto_renew": true }.

7. Trial numbers — and when to upgrade

A new organization can claim one free trial number from the shared pool, leased for 24 hours as a one-time lifetime claim — enough to test inbound calls and SMS before committing:

# Claim from the pool (no body)
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/claim-trial \
  -H "X-API-Key: dv_live_sk_..."

# Keep it permanently
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/purchase-trial \
  -H "X-API-Key: dv_live_sk_..."

# Or hand it back
curl -X DELETE https://api.orbit.devotel.io/api/v1/numbers/release-trial \
  -H "X-API-Key: dv_live_sk_..."

Claim returns 409 if your org already holds an active trial or already owns purchased numbers. Upgrade the moment you need the number to survive past 24 hours, want a specific area code, or need capabilities the shared pool doesn’t guarantee — convert with purchase-trial to keep the exact number, or release it and buy a DID that matches your requirements. The full trial lifecycle is in Number Lifecycle.

8. Troubleshooting

Symptom	Likely cause	Fix
`GET /numbers/available` returns no rows	Inventory is provider-driven and rotates; a filter may be too narrow, or the country has no current stock	Drop the capability filter and retry; check `GET /numbers/available/countries` for countries with live stock and `GET /numbers/country-capabilities` for per-type counts. For a block, use `POST /numbers/bulk-reserve` and let the platform find inventory for you.
Purchased number can’t receive calls	No route was set, or the DID was bought without the `voice` capability	Pull `GET /numbers/{id}` and check `capabilities` includes `voice`; then set an inbound route. If capability is genuinely missing, release the DID and rebuy with `capabilities: ["voice", ...]`.
SMS fails on a voice-only DID	Capability mismatch at purchase — an explicit `capabilities` request intersects with the carrier’s advertised set	Pass the full set you need at purchase. A toll-free number’s SMS is send-only — if you need two-way SMS, buy a local or mobile DID instead.
Bulk row failed with `NUMBER_UNAVAILABLE`	Inventory turnover — another buyer took the number between your search and checkout	Re-run the search and retry only the failed rows; failed rows are never charged, so retrying is safe.
Purchase blocked on a regulated country (`requires_registration`)	The country gates activation on identity/address documents	Preview exact requirements with Regulatory Preview, complete the compliance profile, and pass its id at purchase time so the number activates immediately instead of entering a hold.
`402 INSUFFICIENT_BALANCE` on buy	Wallet checked up front against the full (summed, for bulk) cost	Top up the wallet; the response names the required and available cents.

Most post-purchase oddities trace to one of: capability mismatch (bought without the channel you need), a missing inbound route, or a regulatory hold still pending a compliance profile.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Buy and provision numbers: single purchases, bulk orders, and post-purchase wiring

Buy and provision numbers

1. Number basics

2. Search inventory first

3. Buy a single DID

4. Bulk-provision up to 50 numbers

5. Poll and audit the order

6. Wire the number up after purchase

Set the voice route

Register the emergency address

Set the caller name

7. Trial numbers — and when to upgrade

8. Troubleshooting

See Also

​Buy and provision numbers

​1. Number basics

​2. Search inventory first

​3. Buy a single DID

​4. Bulk-provision up to 50 numbers

​5. Poll and audit the order

​6. Wire the number up after purchase

​Set the voice route

​Register the emergency address

​Set the caller name

​7. Trial numbers — and when to upgrade

​8. Troubleshooting

​See Also

Buy and provision numbers

1. Number basics

2. Search inventory first

3. Buy a single DID

4. Bulk-provision up to 50 numbers

5. Poll and audit the order

6. Wire the number up after purchase

Set the voice route

Register the emergency address

Set the caller name

7. Trial numbers — and when to upgrade

8. Troubleshooting

See Also