Search

Search for phone number records by state, carrier, rate center, or other criteria

The search endpoint allows you to find phone number records matching various criteria.

Endpoint

GET /v1/search

Authentication

Requires API key via one of:

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

See Authentication for details.

Query Parameters

Parameter	Type	Required	Description
`state`	string	No	2-letter state/province code (e.g., `CA`, `ON`)
`country`	string	No	Country code: `US` or `CA`
`ocn`	string	No	4-character Operating Company Number
`carrier`	string	No	Partial carrier name match (case-insensitive)
`rate_center`	string	No	Partial rate center name match (case-insensitive)
`status`	string	No	Number status: `ASSIGNED`, `UNASSIGNED`, `RESERVED`
`limit`	integer	No	Number of results per page (default: 50, max: 100)
`offset`	integer	No	Number of results to skip for pagination (default: 0)

ℹ️ At Least One Filter Required

You must provide at least one search parameter (state, country, ocn, carrier, rate_center, or status).

Request Examples

Search by State

curl -H "Authorization: Bearer your-api-key" \
  "https://api.telco.dev/v1/search?state=CA"

Search by Carrier Name

curl -H "Authorization: Bearer your-api-key" \
  "https://api.telco.dev/v1/search?carrier=verizon"

Combined Search

curl -H "Authorization: Bearer your-api-key" \
  "https://api.telco.dev/v1/search?state=CA&carrier=wireless&limit=20"

Search Canadian Numbers

curl -H "Authorization: Bearer your-api-key" \
  "https://api.telco.dev/v1/search?country=CA&state=ON"

Response

Success Response (200 OK)

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

Response Fields

Field	Type	Description
`results`	array	List of matching NPA-NXX records
`results[].npa`	string	3-digit area code
`results[].nxx`	string	3-digit exchange code
`results[].ocn`	string	Operating Company Number
`results[].company_name`	string	Carrier/company name
`results[].rate_center`	string	Rate center name
`results[].state`	string	State/province code
`results[].country`	string	Country code
`results[].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)

No search parameters provided:

{
  "error": "invalid_request",
  "message": "At least one search parameter is required"
}

Code Examples

JavaScript

async function searchRecords(params) {
  const searchParams = new URLSearchParams(params);

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

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

  return response.json();
}

// Find all VoIP carriers in New York
const voipNY = await searchRecords({
  state: "NY",
  carrier: "voip"
});

console.log(`Found ${voipNY.pagination.total} VoIP exchanges in NY`);

Python

import requests
import os

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

# Find all T-Mobile exchanges in California
result = search_records(state="CA", carrier="t-mobile")
print(f"Found {result['pagination']['total']} T-Mobile exchanges in CA")

Use Cases

Find All Carriers in a State

async function getCarriersInState(state) {
  const result = await searchRecords({ state, limit: 1000 });

  // Extract unique carriers
  const carriers = new Set();
  result.results.forEach(r => {
    if (r.company_name) {
      carriers.add(r.company_name);
    }
  });

  return Array.from(carriers).sort();
}

const caCarriers = await getCarriersInState("CA");
console.log(`${caCarriers.length} unique carriers in California`);

Count Exchanges by Rate Center

async function countByRateCenter(state) {
  const result = await searchRecords({ state, limit: 1000 });

  const counts = {};
  result.results.forEach(r => {
    const rc = r.rate_center || "Unknown";
    counts[rc] = (counts[rc] || 0) + 1;
  });

  return Object.entries(counts)
    .sort((a, b) => b[1] - a[1])
    .slice(0, 10);
}

const topRateCenters = await countByRateCenter("CA");
console.log("Top 10 rate centers:", topRateCenters);