Quick Start

Get up and running with the telco.dev API in minutes

This guide will help you make your first API request in under 5 minutes.

Step 1: Get Your API Key

Go to telco.dev and sign up for a free account
Navigate to your Dashboard
Click "Create API Key"
Copy your new API key (starts with tk_live_)

⚠️ Keep your API key secure

Your API key grants access to your account. Never share it publicly or commit it to version control.

Step 2: Make Your First Request

Using cURL

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

Using JavaScript (fetch)

const response = await fetch(
  "https://api.telco.dev/v1/lookup/4155551234",
  {
    headers: {
      "Authorization": "Bearer tk_live_your_key_here"
    }
  }
);

const data = await response.json();
console.log(data);

Using Python (requests)

import requests

response = requests.get(
    "https://api.telco.dev/v1/lookup/4155551234",
    headers={"Authorization": "Bearer tk_live_your_key_here"}
)

data = response.json()
print(data)

Step 3: Understand the Response

A successful lookup returns carrier and location information for the phone number:

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

Field	Description
`tn`	The full 10-digit telephone number
`npa`	Area code (first 3 digits)
`nxx`	Exchange code (next 3 digits)
`nxxx`	Line number (last 4 digits)
`carrier.ocn`	Operating Company Number
`carrier.name`	Carrier/company name
`carrier.type`	Carrier type (ILEC, CLEC, WIRELESS, etc.)
`location.rateCenter`	Rate center name
`location.state`	State/province code
`location.country`	Country code (US or CA)

What's Next?

Authentication - Learn about API key authentication
Rate Limits - Understand usage limits for your tier
API Reference - Explore all available endpoints
Error Handling - Handle errors gracefully