Phone numbers · Ready Docs

#Phone numbers

List, buy and release your numbers. Each is $5 a month: first month up front, no setup fee.

Details

Buying needs a card on file (Settings → Billing).

Buy a number in 3 calls

Optionally check the area code, pay at checkout, then buy with the payment id.

Details

Optional: GET /v1/numbers/available?area_code=415 to see whether Ready can offer the area code.
POST /v1/numbers/checkout with { "area_code": "415" } pays the first month and returns data.payment_intent_id.
POST /v1/numbers with { "area_code": "415", "payment_intent_id": "…" }. Often the number is ready at once; otherwise poll GET /v1/numbers/:id until it's active, usually about 2 minutes.

Store phone_number_id from step 3, and send from the number with from. Rarely, the carrier rejects a number; the status table says what to do.

Number status

Only active can send. provider_rejected and payment_declined never will.

Details

status	Meaning
`active`	Can send.
`pending_provisioning`, `requested`, `submitted`	Being set up. `phone_number` is a placeholder like `"Pending (415)"`, not a phone number.
`provider_rejected`, `payment_declined`	Failed and won't become active. Stop polling, sort out the payment with support if needed, and buy again.
`billing_suspended`, `suspended`	Paused for billing or review.
`released`, `inactive`, `retired`	No longer in use.
`deleted`	Released. Hidden from the list; `GET /v1/numbers/:id` can still return it.

#List numbers

GET/v1/numbers

Every number on the account, newest first. Not paginated.

Cost Free

Returns

data[]object[]: id, phone_number, status, created_at. Includes pending and failed numbers, so check status.

Errors

HTTP	Code	When
500	`internal_error`	Read failed. Safe to retry.

GET /v1/numbers

curl "https://api.tryready.com/v1/numbers" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/numbers', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/numbers",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": [
    {
      "id": 2648,
      "phone_number": "Pending (415)",
      "status": "pending_provisioning",
      "created_at": "2026-10-01T19:02:44.310Z"
    },
    {
      "id": 2647,
      "phone_number": "+14155550100",
      "status": "active",
      "created_at": "2026-07-29T00:12:04.512Z"
    }
  ]
}

#Get a number

GET/v1/numbers/:id

One number. Poll this after a purchase until it's ready.

Cost Free

Path parameters

idintegerRequired: The phone_number_id from the purchase.

Returns

dataobject: Same shape as one item of List numbers.

Poll every 10 to 30 seconds until status is active (usually about 2 minutes).

Details

Stop if it becomes provider_rejected or payment_declined. After you release a number this returns status: "deleted" or a 404.

Errors

HTTP	Code	When
404	no code	Not on this account. Body: `{"success": false, "error": "Number not found"}`.

GET /v1/numbers/:id

curl "https://api.tryready.com/v1/numbers/2647" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/numbers/2647', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/numbers/2647",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "id": 2647,
    "phone_number": "+14155550100",
    "status": "active",
    "created_at": "2026-07-29T00:12:04.512Z"
  }
}

{
  "success": false,
  "error": "Number not found"
}

#Check an area code

GET/v1/numbers/available

Whether you can buy a number in an area code.

Cost Free

Query parameters

area_codestringRequired: A 3-digit US or Canada area code. Only the format is checked.

Returns

Fields are at the top level, not under data, and there's no success.

availableboolean: available: true means Ready will try to get a number there.
Details
It doesn't check that the area code exists: 000, 911 and 999 answer true, so validate the area code yourself.
numbers[]object[]: Format examples only. You can't pick one; the carrier assigns your number when you buy.
alternatives[]object[]: When out of stock: up to 5 nearby area codes, each { area_code, state, ready }.
Details
ready: true means a number there can be ready right away.

Errors

HTTP	Code	When
400	`area_code_invalid`	Missing or not 3 digits (in `code`).

GET /v1/numbers/available

curl "https://api.tryready.com/v1/numbers/available?area_code=415" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/numbers/available?area_code=415', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/numbers/available",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    params={
        "area_code": "415"
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "available": true,
  "numbers": [
    {
      "phone_number": "+14152001000"
    },
    {
      "phone_number": "+14152011111"
    }
  ]
}

{
  "available": false,
  "area_code": "415",
  "alternatives": [
    {
      "area_code": "628",
      "state": "CA",
      "ready": true
    }
  ],
  "numbers": []
}

{
  "success": false,
  "code": "area_code_invalid",
  "error": "Enter a 3-digit area code."
}

#Start a number purchase

POST/v1/numbers/checkout

Pays the first month ($5) on your saved card and returns the payment to buy with.

Idempotent Yes, with Idempotency-Key
Rate limit 120/min (700/min shared ceiling)
Cost $5, the first month

Note. POST /phone-numbers/checkout is an older alias; use this path.

Details

The alias is limited to 20 a minute and doesn't accept X-Sub-Account-Id, so use this path for client accounts.

Headers

Idempotency-KeystringRecommended: Retry safely without paying twice. A key is tied to its first body.

Body parameters

area_codestringRequired: The 3-digit area code to buy in. Also accepted, for the dashboard: replaces_phone_id, checkout_id.

Returns

data.payment_intent_idstring: Pass it to Buy a number.
data.charged, data.authorizedboolean: Checkout either charges or holds the first month.
Details
If the number can't be provisioned, the hold is released or the charge refunded.
data.card_brand, data.card_last4string: The card used.
data.client_secret, data.has_cardstring, boolean: Instead of the above when there's no card on file.
Details
The API can't finish that payment: add a card in Settings → Billing and call again.

Errors

HTTP	Code	When
400	`area_code_invalid`	Missing or not 3 digits.
402	`card_declined`	Card refused. Also `card_authentication_required`.
402	`PURCHASE_BLOCKED`	Unpaid bill or account review (in `code`).
403	`permission_denied`	Key lacks `manage_phones`.
409	`area_code_unavailable`	No stock; see `alternatives`.
409	`purchase_in_progress`	Another purchase is running. Also `campaign_number_limit`.
502	`checkout_unconfirmed`	Don't retry: check `GET /v1/numbers` first.
503	`checkout_unavailable`	Nothing charged. Details Also `availability_check_unavailable`, `cap_check_unavailable`, `billing_check_unavailable`, `billing_account_unavailable`, `payments_unavailable`.

POST /v1/numbers/checkout

curl -X POST "https://api.tryready.com/v1/numbers/checkout" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "area_code": "415"
  }'

const res = await fetch('https://api.tryready.com/v1/numbers/checkout', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "area_code": "415"
  }),
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, uuid, requests

r = requests.post(
    "https://api.tryready.com/v1/numbers/checkout",
    headers={"X-API-Key": os.environ["READY_API_KEY"], "Idempotency-Key": str(uuid.uuid4())},
    json={
        "area_code": "415"
    },
    timeout=90,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "charged": true,
    "authorized": false,
    "card_brand": "visa",
    "card_last4": "4242",
    "payment_intent_id": "pi_3Q8aZx2eZvKYlo2C0a1b2c3d"
  }
}

{
  "success": true,
  "data": {
    "client_secret": "pi_3Q8aZx2eZvKYlo2C0a1b2c3d_secret_x8Y",
    "has_card": false
  }
}

#Buy a number

POST/v1/numbers

Provisions the number you paid for at checkout.

Idempotent Yes, with Idempotency-Key
Rate limit 120/min (140/min shared ceiling)
Cost Paid at checkout

Headers

Idempotency-KeystringRecommended: A new key for each new purchase.

Body parameters

area_codestringRequired: The area code you checked out with. The number comes from this one.
payment_intent_idstringRequired: data.payment_intent_id from checkout. Each one provisions exactly one number.

Returns

Fields are at the top level, not under data. Always read phone_number_id: id is only on the instant outcome.

phone_number_idinteger: The number's id. Poll it with GET /v1/numbers/:id.
instantboolean: true: the number is ready now and phone_number is real.
pending_provisioningboolean: true: being set up; poll until active.
pending_campaign_approvalboolean: true: can't send until your 10DLC campaign is approved (usually within 48 hours).
replaced_phone_id, noteinteger | null, string: The number replaced, if any, and a sentence on what happens next.

Errors

HTTP	Code	When
400	`area_code_invalid`	Missing or not 3 digits (in `code`).
400	`payment_intent_required`	Also `payment_not_confirmed`, `payment_not_for_number`, `payment_not_taken`.
400	`invalid_field`	A field has the wrong type.
400	`no_campaign`	No approved registration. Charge returned.
402	`PURCHASE_BLOCKED`	Unpaid bill or account review (in `code`).
403	`payment_not_owned`	Another account's payment.
403	`permission_denied`	Key lacks `manage_phones`.
409	`payment_intent_already_used`	This payment already bought one.
409	`campaign_number_limit`	Your campaign is full. Charge returned.
500	`buy_incomplete`	Not finished. Don't buy again: check `GET /v1/numbers`.
502	`infobip_submit_failed`	The carrier gave no number. Charge returned.
503	`billing_check_unavailable`	Retry. Also `payments_unavailable`.

POST /v1/numbers

curl -X POST "https://api.tryready.com/v1/numbers" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "area_code": "415",
    "payment_intent_id": "pi_3Q8aZx2eZvKYlo2C0a1b2c3d"
  }'

const res = await fetch('https://api.tryready.com/v1/numbers', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "area_code": "415",
    "payment_intent_id": "pi_3Q8aZx2eZvKYlo2C0a1b2c3d"
  }),
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, uuid, requests

r = requests.post(
    "https://api.tryready.com/v1/numbers",
    headers={"X-API-Key": os.environ["READY_API_KEY"], "Idempotency-Key": str(uuid.uuid4())},
    json={
        "area_code": "415",
        "payment_intent_id": "pi_3Q8aZx2eZvKYlo2C0a1b2c3d"
    },
    timeout=90,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "instant": true,
  "id": 2647,
  "phone_number_id": 2647,
  "phone_number": "+14155550100",
  "pending_provisioning": false,
  "pending_campaign_approval": false,
  "replaced_phone_id": null,
  "note": "Your number is ready now. You can start texting immediately."
}

{
  "success": true,
  "pending_provisioning": true,
  "phone_number_id": 2648,
  "pending_campaign_approval": false,
  "replaced_phone_id": null,
  "note": "Provisioning is async. …"
}

#Release a number

DEL/v1/numbers/:id

Permanent. The number goes back to the carrier and you can't get it back.

Cost Free

Important. Releasing stops the monthly fee. The current month isn't refunded.

Path parameters

idintegerRequired: The number id.

Errors

HTTP	Code	When
403	`permission_denied`	Key lacks `manage_phones`.
403	`test_key_not_allowed`	Called with a test key.
404	`NUMBER_NOT_FOUND`	Not yours, or already released (in `code`).
409	`NUMBER_RESERVED`	A protected number. Contact support.
500	`RELEASE_INCOMPLETE`	Didn't finish. Check `GET /v1/numbers/:id`.
502	`BILLING_CANCEL_FAILED`	Fee not stopped, so nothing released.

DEL /v1/numbers/:id

curl -X DELETE "https://api.tryready.com/v1/numbers/2647" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/numbers/2647', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.delete(
    "https://api.tryready.com/v1/numbers/2647",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true
}