Phone Number Lookup

Look up carrier and location information for any US or Canadian phone number

The lookup endpoint returns carrier, location, and status information for a 10-digit North American phone number.

Endpoint

GET /v1/lookup/:tn
GET /v1/lookup?tn=:tn

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

Query Parameters

Request Examples

Using Path Parameter (Recommended)

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

Using Query Parameter

curl -H "Authorization: Bearer your-api-key" \
  "https://api.telco.dev/v1/lookup?tn=4155551234"

Response

Success Response (200 OK)

{
  "tn": "4155551234",
  "npa": "415",
  "nxx": "555",
  "nxxx": "1234",
  "carrier": {
    "ocn": "9740",
    "name": "PACIFIC BELL",
    "type": "ILEC"
  },
  "location": {
    "rateCenter": "SAN FRANCISCO",
    "state": "CA",
    "country": "US"
  }
}

If the number is in your organization's inventory:

{
  "tn": "5135551234",
  "npa": "513",
  "nxx": "555",
  "nxxx": "1234",
  "carrier": {
    "ocn": "7500",
    "name": "AT&T WIRELESS",
    "type": "WIRELESS"
  },
  "location": {
    "rateCenter": "CINCINNATI",
    "state": "OH",
    "country": "US"
  },
  "inventory": {
    "division": "enterprise",
    "provider": "bandwidth",
    "active": true,
    "smsEnabled": true,
    "lidbEnabled": false
  }
}

Response Fields

Error Responses

Not Found (404)

Number not found in database:

{
  "error": "not_found",
  "message": "No data found for NPA-NXX 415-555"
}

Invalid Request (400)

Invalid telephone number format:

{
  "error": "invalid_request",
  "message": "Invalid 'tn' parameter: '415555'. Must be exactly 10 digits."
}

Missing required parameter:

{
  "error": "invalid_request",
  "message": "Missing required parameter 'tn' (10-digit telephone number). Usage: /v1/lookup?tn=XXXXXXXXXX"
}

Unauthorized (401)

Missing or invalid API key:

{
  "error": "unauthorized",
  "message": "API key required. Pass via X-API-Key header or api_key query param."
}

Rate Limited (429)

Rate limit exceeded:

{
  "error": "rate_limited",
  "message": "Per-minute rate limit exceeded. Limit: 6/minute. Resets in 45 seconds.",
  "details": {
    "limit_type": "minute",
    "limit": 6,
    "remaining": 0,
    "reset": 1705363260
  }
}

Carrier Types

The carrier.type field indicates the type of service:

Code Examples

JavaScript

async function lookupNumber(tn) {
  const response = await fetch(
    `https://api.telco.dev/v1/lookup/${tn}`,
    {
      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
const result = await lookupNumber("4155551234");
console.log(`Carrier: ${result.carrier.name}`);
console.log(`Location: ${result.location.rateCenter}, ${result.location.state}`);

Python

import requests
import os

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

# Usage
result = lookup_number("4155551234")
print(f"Carrier: {result['carrier']['name']}")
print(f"Location: {result['location']['rateCenter']}, {result['location']['state']}")

Go

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

type LookupResponse struct {
    TN       string `json:"tn"`
    NPA      string `json:"npa"`
    NXX      string `json:"nxx"`
    NXXX     string `json:"nxxx"`
    Carrier  *struct {
        OCN  string `json:"ocn"`
        Name string `json:"name"`
        Type string `json:"type"`
    } `json:"carrier"`
    Location *struct {
        RateCenter string `json:"rateCenter"`
        State      string `json:"state"`
        Country    string `json:"country"`
    } `json:"location"`
    Inventory *struct {
        Division    string `json:"division"`
        Provider    string `json:"provider"`
        Active      bool   `json:"active"`
        SMSEnabled  bool   `json:"smsEnabled"`
        LIDBEnabled bool   `json:"lidbEnabled"`
    } `json:"inventory"`
}

func lookupNumber(tn string) (*LookupResponse, error) {
    req, _ := http.NewRequest("GET", "https://api.telco.dev/v1/lookup/"+tn, nil)
    req.Header.Set("Authorization", "Bearer "+os.Getenv("TELCO_API_KEY"))

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result LookupResponse
    json.NewDecoder(resp.Body).Decode(&result)
    return &result, nil
}

func main() {
    result, _ := lookupNumber("4155551234")
    if result.Carrier != nil {
        fmt.Printf("Carrier: %s\n", result.Carrier.Name)
    }
    if result.Location != nil {
        fmt.Printf("Location: %s, %s\n", result.Location.RateCenter, result.Location.State)
    }
}