Area Code (NPA) Lookup

Get all exchanges within an area code or look up a specific NPA-NXX combination

The NPA endpoint returns information about area codes and their associated exchanges (NXX codes).

Endpoints

GET /v1/npa/:npa
GET /v1/npa/:npa/nxx/:nxx
GET /v1/npa?npa=:npa
GET /v1/npa?npa=:npa&nxx=:nxx

Authentication

Requires API key via one of:

Authorization: Bearer <key> header (recommended)
X-API-Key header
apiKey query parameter

See Authentication for details.

Parameters

Path Parameters

Parameter	Type	Required	Description
`npa`	string	Yes	3-digit area code (e.g., `415`)
`nxx`	string	No	3-digit exchange code (e.g., `555`)

Query Parameters

Parameter	Type	Required	Description
`npa`	string	Yes*	3-digit area code. *Required when not using path parameter.
`nxx`	string	No	3-digit exchange code to filter results.
`limit`	integer	No	Number of results per page (default: 50, max: 100)
`offset`	integer	No	Number of results to skip for pagination (default: 0)

Request Examples

Get All Exchanges in an Area Code

curl -H "Authorization: Bearer your-api-key" \
  "https://api.telco.dev/v1/npa/415"

Get a Specific NPA-NXX

curl -H "Authorization: Bearer your-api-key" \
  "https://api.telco.dev/v1/npa/415/nxx/555"

Using Query Parameters with Pagination

curl -H "Authorization: Bearer your-api-key" \
  "https://api.telco.dev/v1/npa?npa=415&limit=20&offset=40"

Response

Success Response (200 OK)

{
  "npa": "415",
  "state": "CA",
  "country": "US",
  "total_exchanges": 847,
  "exchanges": [
    {
      "nxx": "200",
      "ocn": "7500",
      "company_name": "AT&T WIRELESS",
      "rate_center": "SAN FRANCISCO",
      "status": "ASSIGNED"
    },
    {
      "nxx": "201",
      "ocn": "9740",
      "company_name": "PACIFIC BELL",
      "rate_center": "SAN FRANCISCO",
      "status": "ASSIGNED"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 847
  }
}

Response Fields

Field	Type	Description
`npa`	string	The 3-digit area code
`state`	string	Primary state/province for this area code
`country`	string	Country code: `US` or `CA`
`total_exchanges`	integer	Total number of exchanges in this area code
`exchanges`	array	List of exchange records
`exchanges[].nxx`	string	3-digit exchange code
`exchanges[].ocn`	string	Operating Company Number
`exchanges[].company_name`	string	Carrier/company name
`exchanges[].rate_center`	string	Rate center name
`exchanges[].status`	string	Assignment status
`pagination.limit`	integer	Number of results requested
`pagination.offset`	integer	Number of results skipped
`pagination.total`	integer	Total matching records

Error Responses

Invalid Request (400)

Missing or invalid area code:

{
  "error": "invalid_request",
  "message": "Missing required parameter 'npa' (3-digit area code). Usage: /v1/npa?npa=XXX"
}

{
  "error": "invalid_request",
  "message": "Invalid 'npa' parameter: '41'. Must be exactly 3 digits."
}

Code Examples

JavaScript

async function getAreaCodeExchanges(npa, options = {}) {
  const params = new URLSearchParams({
    npa,
    limit: options.limit || 50,
    offset: options.offset || 0
  });

  if (options.nxx) {
    params.set("nxx", options.nxx);
  }

  const response = await fetch(
    `https://api.telco.dev/v1/npa?${params}`,
    {
      headers: {
        "Authorization": `Bearer ${process.env.TELCO_API_KEY}`
      }
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }

  return response.json();
}

// Usage: Get all exchanges in 415
const result = await getAreaCodeExchanges("415");
console.log(`Found ${result.total_exchanges} exchanges in ${result.npa}`);

// Usage: Get specific NPA-NXX
const specific = await getAreaCodeExchanges("415", { nxx: "555" });
console.log(specific.exchanges[0]);

Python

import requests
import os

def get_area_code_exchanges(npa, nxx=None, limit=50, offset=0):
    params = {
        "npa": npa,
        "limit": limit,
        "offset": offset
    }
    if nxx:
        params["nxx"] = nxx

    response = requests.get(
        "https://api.telco.dev/v1/npa",
        params=params,
        headers={"Authorization": f"Bearer {os.environ['TELCO_API_KEY']}"}
    )
    response.raise_for_status()
    return response.json()

# Usage
result = get_area_code_exchanges("415")
print(f"Found {result['total_exchanges']} exchanges in {result['npa']}")

# With pagination
page2 = get_area_code_exchanges("415", limit=50, offset=50)

Use Cases

Find All Wireless Carriers in an Area Code

const result = await getAreaCodeExchanges("415");

const wirelessCarriers = result.exchanges.filter(
  ex => ex.company_name?.toLowerCase().includes("wireless")
);

console.log(`Found ${wirelessCarriers.length} wireless exchanges`);

Paginate Through All Exchanges

async function getAllExchanges(npa) {
  const allExchanges = [];
  let offset = 0;
  const limit = 100;

  while (true) {
    const result = await getAreaCodeExchanges(npa, { limit, offset });
    allExchanges.push(...result.exchanges);

    if (offset + limit >= result.pagination.total) {
      break;
    }
    offset += limit;
  }

  return allExchanges;
}

const all415Exchanges = await getAllExchanges("415");
console.log(`Total: ${all415Exchanges.length} exchanges`);