Skip to main content

​
Bulk Reserve: reserve, hold, and finalize up to 1000 DIDs

Bulk Reserve is the console workflow for provisioning a block of numbers when you know the shape of the block — a country, a number type, maybe an area code — but not the individual E.164s. You describe what you need, Orbit scans both inventory feeds and picks the cheapest matching numbers for you, and holds the block for 15 minutes. During the hold nothing is charged. You then finalize (purchase, bill, and wire inbound routing) or cancel (release the block). Creating a reservation never debits your wallet. The wallet is checked only when you finalize. The shorter endpoint sequence page is at Phone Numbers — Bulk Reserve; the single-purchase and pre-built-list flows are in Buy and provision numbers.

​
1. When Bulk Reserve fits

Pick the surface that matches what you already know: Bulk Reserve is the right tool when:
  • You need 50+ DIDs in one shot. Past the 50-item cap of a select-list order, a reservation is the only single-request path.
  • You’re building local presence across an area-code sweep — a dialer that wants numbers local to each calling region, or a support line per metro. Describe the sweep; don’t hand-assemble it.
  • You want the platform to pick. The reservation searches the union of both upstream inventory feeds and picks the cheapest matching numbers, so a block that would take a spreadsheet and an afternoon takes one filter.
The trade-off is control: you set the filter, Orbit picks the DIDs. If the exact numbers matter — a vanity pattern already chosen, a contiguous sequence — build the list yourself and use the select-list flow instead.

​
2. The two buy tabs

Open Numbers → Buy. The header of the page carries a tab strip:
  • Buy (/numbers/buy) — single purchase and the select-list bulk order.
  • Bulk (/numbers/buy/bulk) — the Bulk Reserve surface.
  • Orders (/numbers/buy/orders) — the audit trail for completed batches.
Switching tabs keeps your search state: the country, number type, and area-code filters you set on one surface carry into the other, so you can move from a single-DID browse to a block reservation without re-entering the shape. Completed reservations don’t route through the Orders tab — Orders lists finalized batches; a live reservation stays on the Bulk tab until it settles.

​
3. The filter panel

The Compose state of the Bulk tab is one filter form:
  • Country — the ISO country to search. Toll-free and mobile availability is country-dependent; local is the default.
  • Number type — local, mobile, or toll_free. Local ties the block to a geography; toll-free is national and never geographically anchored.
  • Capability — filter to numbers that carry voice + SMS, SMS-only, or voice-only. Pick the channels the block must serve; capability mismatches bought at scale are expensive to unwind.
  • Quantity — 1 to 1000. A slider sets the target count.
  • Pattern (optional) — a digits-only pattern the numbers must contain, start with, or end with.
As you adjust the filter, a live counter shows roughly how many numbers match — ”≈ 234 numbers available” — so you know whether the block can fill before you commit. It updates as you type or click; treat it as an estimate, because inventory rotates while you look.

​
4. The US area-code map

For US country + local type, the filter panel gains an area-code picker with two inputs that write the same field: The tile-grid map. Every US state renders as a tile inside a geographic grid, plus a separate row of regional tiles for DC and the US territories (PR, VI, GU, AS, MP). Tiles are uniform size — inventory density is encoded by color, not area, so the map is not a choropleth and screen readers get each tile as its own stop. Click a state:
  • One area code in the state → that code fills the filter immediately.
  • Several → a popover lists every code in the state; pick one.
The selected code’s state tile is outlined. States with no inventory are dimmed and not clickable. The free-text NPA box. Type the 3-digit area code directly when you know it — faster than hunting a tile, and the only path for codes the map groups away. The map’s regions mirror how the upstream inventory feeds group US stock: a state tile’s popover lists the codes those feeds actually report for that state. Region groupings update as the feeds do, so a dimmed tile means no current stock in that state, not a missing map entry. Either input fills the same area_code filter and re-runs the live counter. For multi-area-code blocks, run one reservation per area code — the worked example below does three.

​
5. The reservation: hold, don’t pay

Click Reserve. Orbit searches the upstream inventory feeds, picks the cheapest matching numbers (both feeds, unless you pin one provider), and creates the reservation. The page switches to the Held state:
  • A 15-minute countdown to the expiry time. The hold is server-side; closing the tab doesn’t release it. A reservation never finalized or cancelled releases automatically when the countdown ends.
  • The picked block, item by item — each DID with its monthly cost, the provider it came from, and its per-item status. This is where you read the provider mix: a large block will usually draw from both feeds, priced per item.
  • The summed cost for the whole block.
Three properties to internalize:
  1. A reservation never debits. Creation charges nothing; the wallet is touched only at finalize.
  2. Expiry is read-time. Once the hold lapses, the row reports itself expired the next time it’s read — there is no separate sweep that could leave a stale open hold.
  3. Partial fill is reported, not fatal. If the filter matched fewer numbers than you asked for, the reservation comes back marked partial with the count it could hold. You finalize what was found or cancel and widen the filter.

​
6. Finalize: wallet preflight, then per-item purchase

Click Finalize. This is the moment money moves, and the checks run in a fixed order:
  1. Wallet preflight. The summed per-item cost is checked against your balance before any purchase is attempted. Insufficient balance stops the finalize with the required and available amounts named — no purchases are attempted, and the reservation is not consumed, so you can top up and retry within the hold window.
  2. Per-item compliance gate. Each item runs the same checks a single purchase would — most visibly the regulatory-registration gate on restricted geographies. Attach a compliance profile to the reservation filter upfront so a registration-required block finalizes instead of gating item by item.
  3. Purchase + bill + route, per item. Every successful item is purchased, billed to the wallet, and given an inbound route.
Read the result for partial failures: the response and the settled page report succeeded and failed counts, and per-item error rows name what blocked each failure. Two guarantees:
  • No partial debit — only succeeded items are billed; the failed count costs nothing.
  • Every succeeded item lands with an inbound route — a finalized block is never a fleet of silent DIDs. The default route is created per number; re-point any subset afterward with the routing surface (see Buy and provision numbers — wire the number up).
After finalize, the page moves to the Settled state: the purchased numbers, the per-item errors, and a link back to Numbers where the new DIDs are listed.

​
7. Cancel: release the block

Click Cancel to walk away from a hold. Cancel:
  • makes no upstream carrier call — a reservation never placed an order, so there is nothing to unwind with the carrier;
  • releases every picked item back to inventory, making the block available to other buyers;
  • is terminal and idempotent on the row: a second cancel, a cancel after finalize, or a cancel after expiry is rejected with 409, because the reservation is already in a settled state.
Cancellation exists so an idle hold doesn’t sit on real inventory. If you won’t finalize, cancel rather than waiting out the clock — but if you do nothing, the automatic expiry releases the block anyway.

​
8. API equivalent

Every console action above is one API call, so automation can replace the console entirely. All four are under the numbers scope; POST calls need numbers:write. Reserving is rate-limited to 1 request/minute per tenant.
The full field table — pattern filters, capability filter, provider pinning, compliance profile — is in Phone Numbers — Bulk Reserve. Finalize returns the succeeded/failed counts and the debited cents; failed items are never billed.

​
9. Worked example: 200 DIDs across three area codes

Goal: local-presence DIDs for a dialer covering San Francisco (415), New York (212), and Chicago (312) — roughly 200 numbers, voice + SMS.
  1. Numbers → Buy → Bulk. Set country US, number type local, capability voice + SMS.
  2. First slice: click the California tile, pick 415 from the popover. Set quantity to 70. The counter confirms the stock covers it. Click Reserve.
  3. Review the hold. The Held page lists the 70 picked DIDs with per-item costs and the provider mix, plus the summed cost and the countdown. Note the reservation id (resv_...) if you’re driving the API alongside.
  4. Finalize. Click Finalize. The wallet preflight checks the summed cost; on sufficient balance the purchases run, each successful item bills, and an inbound route is created per DID. The settled page shows 70 succeeded, 0 failed.
  5. Repeat for 212 and 312. Two more reservations — New York tile → 212, Illinois tile → 312 — at 65 each, or resize to whatever the counter says each code can hold. Each reservation is independently held and finalized.
  6. Point the routes. Finalize created a default inbound route per number; re-point the block to your dialer’s queue or agent in bulk on the routing surface, or per number with PUT /numbers/{e164}/routing.
The whole block provisions in three console passes, and the wallet is debited only at the three finalize clicks — never at reserve time.

​
10. Troubleshooting

​
See Also