Carriers

List and look up carrier information by Operating Company Number (OCN)

The carriers endpoints let you list all carriers or look up detailed information about a specific carrier.

Endpoints

GET /v1/carriers
GET /v1/carrier/:ocn
GET /v1/carrier?ocn=:ocn

Authentication

Requires API key via one of:

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

See Authentication for details.

List All Carriers

Endpoint

GET /v1/carriers

Query Parameters

Request Example

curl -H "Authorization: Bearer your-api-key" \
  "https://api.telco.dev/v1/carriers?country=US&limit=20"

Response (200 OK)

{
  "carriers": [
    {
      "ocn": "7500",
      "company_name": "AT&T WIRELESS",
      "common_name": "AT&T",
      "carrier_type": "WIRELESS",
      "state": "GA",
      "country": "US"
    },
    {
      "ocn": "9740",
      "company_name": "PACIFIC BELL TELEPHONE COMPANY",
      "common_name": "AT&T",
      "carrier_type": "ILEC",
      "state": "CA",
      "country": "US"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 2847
  }
}

Get Carrier by OCN

Endpoint

GET /v1/carrier/:ocn
GET /v1/carrier?ocn=:ocn

Parameters

Request Examples

# Using path parameter
curl -H "Authorization: Bearer your-api-key" \
  "https://api.telco.dev/v1/carrier/9740"

# Using query parameter
curl -H "Authorization: Bearer your-api-key" \
  "https://api.telco.dev/v1/carrier?ocn=9740"

Response (200 OK)

{
  "ocn": "9740",
  "company_name": "PACIFIC BELL TELEPHONE COMPANY",
  "common_name": "AT&T",
  "carrier_type": "ILEC",
  "state": "CA",
  "country": "US",
  "exchanges": {
    "total": 3247,
    "by_state": {
      "CA": 3247
    }
  }
}

Response Fields

Carrier Types

Error Responses

Invalid Request (400)

Missing or invalid OCN:

{
  "error": "invalid_request",
  "message": "Missing required parameter 'ocn' (4-character Operating Company Number). Usage: /v1/carrier?ocn=XXXX"
}

{
  "error": "invalid_request",
  "message": "Invalid 'ocn' parameter: '974'. Must be exactly 4 alphanumeric characters."
}

Not Found (404)

OCN not found:

{
  "error": "not_found",
  "message": "Carrier not found: XXXX"
}

Code Examples

JavaScript

// List all carriers
async function listCarriers(options = {}) {
  const params = new URLSearchParams(options);

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

  return response.json();
}

// Get carrier by OCN
async function getCarrier(ocn) {
  const response = await fetch(
    `https://api.telco.dev/v1/carrier/${ocn}`,
    {
      headers: {
        "Authorization": `Bearer ${process.env.TELCO_API_KEY}`
      }
    }
  );

  return response.json();
}

// Usage
const wireless = await listCarriers({ type: "WIRELESS", limit: 10 });
console.log(`Found ${wireless.pagination.total} wireless carriers`);

const att = await getCarrier("9740");
console.log(`${att.company_name} has ${att.exchanges.total} exchanges`);

Python

import requests
import os

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

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

# Usage
wireless = list_carriers(type="WIRELESS", country="US")
print(f"Found {wireless['pagination']['total']} US wireless carriers")

verizon = get_carrier("6006")
print(f"{verizon['company_name']}: {verizon['exchanges']['total']} exchanges")

Use Cases

Find Largest Carriers

async function getLargestCarriers(limit = 10) {
  // Get all carriers (paginate if needed)
  const result = await listCarriers({ limit: 1000 });

  // This is simplified - in practice you'd use the exchanges.total from individual carrier lookups
  // or aggregate from a full data export
  return result.carriers.slice(0, limit);
}

Get All Carriers in a State

async function getCarriersInState(state) {
  const result = await listCarriers({ state, limit: 1000 });
  return result.carriers;
}

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