Area codes

Pick the area code before you buy a number: check it has stock, or let Ready suggest one.

#Check an area code

Whether you can buy a number in an area code.

Parameters

area_codestring · queryRequired: A 3-digit US or Canada area code. A code that isn’t 3 digits, or starts with 0 or 1, answers 400.

Returns

availableboolean: true means you can buy a number in that area code now. An area code that doesn’t exist, or that neither Ready nor the carrier has stock in, answers false.
readyboolean: Only when available is true. true: Ready has a number ready to hand over. false: the number is ordered from the carrier when you buy and is set up in a few minutes.
numbers[]object[]: Always empty, kept so existing code that reads it keeps working. You can’t pick a number; Ready assigns one in that area code when you buy.
alternatives[]object[]: When out of stock: up to 5 nearby area codes, each { area_code, state, ready }. ready: true means a number there can be ready right away.

Errors

HTTP	Code	When
400	`area_code_invalid`	Missing, not 3 digits, or starts with 0 or 1.
500	no code	Ready couldn’t check its stock or the carrier’s just now. This doesn’t mean the area code is sold out. Try again in a minute.

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().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

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 r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "available": true,
  "ready": true,
  "numbers": []
}

{
  "success": true,
  "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."
}

#Suggest an area code

The local area code for a ZIP code. Without one, Ready uses the ZIP code of your registered business.

Query parameters

zipstring · query: A US ZIP code. Only its first 5 digits are read.

Returns

data.suggestedboolean | null: true with an area code, or null when there’s no ZIP code or no area code for it. data.reason then says which.
data.area_codestring: The suggested area code. Check it with Check an area code before you buy.

Errors

HTTP	Code	When
500	no code	Ready couldn’t read your business ZIP code. Send `zip`, or try again.

curl "https://api.tryready.com/v1/area-codes/suggested?zip=80202" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/area-codes/suggested?zip=80202', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/area-codes/suggested",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    params={
        "zip": "80202"
    },
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": {
    "suggested": true,
    "area_code": "303",
    "display": "(303) area, based on ZIP code 80202",
    "zip": "80202"
  }
}

#Area codes of your contacts

Area codes ranked by how many of your contacts have a number there, so you can buy a number local to most of them.

Returns

data.area_codes[]object[]: Each { area_code, contacts }, most contacts first.

Errors

HTTP	Code	When
500	no code	Ready couldn’t count your contacts just now. Try again.

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

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

import os, requests

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

Returns:

{
  "success": true,
  "data": {
    "area_codes": [
      {
        "area_code": "303",
        "contacts": 412
      },
      {
        "area_code": "720",
        "contacts": 180
      }
    ]
  }
}