Skip to main content

New Numbers

Search live carrier inventory and order new phone numbers onto an account. Use this flow when you need a fresh number (new location, new line, overflow capacity). To bring an existing number in from another carrier, use Number Porting instead.

Overview​

Ordering a new number is a three-step flow:

  1. Search — find available numbers using filters (area code, state, city + state, ZIP, or the six-digit prefix).
  2. Order — submit one or more numbers from the search results.
  3. Track — the order typically completes within seconds; poll the order ID or wait for a terminal status.
search → order (pending) → complete
                         → partial   (some numbers unavailable — only with partial_allowed)
                         → failed    (no numbers acquired)

Step 1: Search Available Numbers​

curl "https://api.dialstack.ai/v1/available-phone-numbers?area_code=919&quantity=10" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41"

At least one filter is required. Supported filters:

Query paramFormatNotes
area_code3 digits
state2-letter uppercase (NC)
cityFree textRequires state
zip5 digits
npa_nxx6 digits (area code + prefix)
quantity1–100, default 10Caps the number of results

Filters may be combined to narrow results.

Response:

{
  "data": [
    {
      "phone_number": "+19195551234",
      "city": "RALEIGH",
      "state": "NC",
      "rate_center": "RALEIGH",
      "lata": "422"
    },
    {
      "phone_number": "+19195555678",
      "city": "RALEIGH",
      "state": "NC",
      "rate_center": "RALEIGH",
      "lata": "422"
    }
  ]
}

Search results come from live carrier inventory — they are not reserved. Another buyer can take the number between your search and your order, so place the order promptly and handle the 409 Conflict case if a number is no longer available at order time.

Step 2: Place the Order​

curl -X POST https://api.dialstack.ai/v1/phone-number-orders \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["+19195551234", "+19195555678"]
  }'

Up to 100 numbers per order. Numbers must be US non-toll-free; the API rejects toll-free numbers and non-US numbers at validation.

By default the entire order fails if any single number can't be acquired. Pass "partial_allowed": true to accept whatever subset the carrier is able to fill:

{
  "phone_numbers": ["+19195551234", "+19195555678"],
  "partial_allowed": true
}

Response (201 Created):

{
  "id": "YOUR_ORDER_ID",
  "order_type": "purchase",
  "status": "pending",
  "phone_numbers": ["+19195551234", "+19195555678"],
  "completed_numbers": [],
  "failed_numbers": [],
  "error_message": null,
  "created_at": "2026-04-21T14:00:00Z",
  "updated_at": "2026-04-21T14:00:00Z"
}

Step 3: Track the Order​

Orders typically reach a terminal status within seconds. Fetching a pending order refreshes its status from the upstream provider:

curl https://api.dialstack.ai/v1/phone-number-orders/YOUR_ORDER_ID \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41"

You can also list all orders on the account, optionally filtered by status or type (purchase / disconnect):

curl "https://api.dialstack.ai/v1/phone-number-orders?status=complete&order_type=purchase" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41"

Status Reference​

StatusDescription
pendingSubmitted; awaiting upstream confirmation
completeAll requested numbers were acquired and are active on the account
partialSome numbers acquired, others unavailable (only possible with partial_allowed: true)
failedNo numbers were acquired

On a terminal status, completed_numbers lists the E.164 numbers that were acquired and failed_numbers lists those that couldn't be. Numbers in completed_numbers appear under GET /v1/phone-numbers immediately and can be routed to an extension, dial plan, voice app, or ring group.