Carrier Lookup (original carrier)

The carrier originally assigned a US number block: company name, operating company number (OCN), rate center and state, from the public NANPA central office code and thousands-block reports, with the report date. Porting is not reflected (ported: unknown), so a number moved to another carrier still shows its original one. NANPA data has no carrier category, so line type is only a hint from the carrier name. Canada and the Caribbean are not covered.

POST https://YOUR_API_HOST/v1/carrier-lookup

Credits and caching

• Success billing. 1 credit per lookup (numbers outside the covered numbering plan areas are free). You are charged only when the lookup finds something; a not-found result is free.
• Results are cached per account for 7 days. Repeating the same lookup in that window is free and returns cache_hit: true.
• Invalid input, rate limits and errors are never charged.
• Read the billing rules for the full picture.

Request

Send a JSON body with Authorization: Bearer <key>. The body can be up to 64 KB.

Example request

curl -X POST https://YOUR_API_HOST/v1/carrier-lookup \
  -H "Authorization: Bearer $LOOKVALID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+12024561111"}'

1const response = await fetch("https://YOUR_API_HOST/v1/carrier-lookup", {
2  method: "POST",
3  headers: {
4    Authorization: `Bearer ${process.env.LOOKVALID_API_KEY}`,
5    "Content-Type": "application/json",
6  },
7  body: JSON.stringify({
8    "phone": "+12024561111"
9  }),
10});
11​
12const result = await response.json();
13if (!response.ok) throw new Error(`${result.error.code}: ${result.error.fix}`);
14console.log(result.found, result.data, result.credits_charged);

1import os
2import requests
3​
4response = requests.post(
5    "https://YOUR_API_HOST/v1/carrier-lookup",
6    headers={"Authorization": f"Bearer {os.environ['LOOKVALID_API_KEY']}"},
7    json={
8        "phone": "+12024561111",
9    },
10    timeout=30,
11)
12result = response.json()
13if not response.ok:
14    raise RuntimeError(f"{result['error']['code']}: {result['error']['fix']}")
15print(result["found"], result["data"], result["credits_charged"])

Response

The status is 200 whether or not anything was found. Check found. Every response also carries the X-Request-Id, X-Credits-Charged, X-Credits-Remaining and X-RateLimit-* headers.

Envelope

The data object

Present when found is true, otherwise null.

Captured example (2026-10-18)

A real run of this lookup on 2026-10-18, using the request above, which is a public input. The envelope fields are left out.

1{
2  "product": "carrier-lookup",
3  "found": true,
4  "data": {
5    "phone_e164": "+12024561111",
6    "npa_nxx_block": {
7      "npa": "202",
8      "nxx": "456",
9      "block": "1"
10    },
11    "original_carrier": {
12      "company": "VERIZON WASHINGTON DC, INC.",
13      "ocn": "9211",
14      "ocn_category": null
15    },
16    "rate_center": "WSHNGTNZN1",
17    "state": "DC",
18    "assignment_level": "central_office_code",
19    "code_holder": {
20      "company": "VERIZON WASHINGTON DC, INC.",
21      "ocn": "9211"
22    },
23    "in_service": true,
24    "assigned_since": null,
25    "line_type": "unknown",
26    "line_type_basis": "carrier name keywords, not an official category",
27    "ported": "unknown",
28    "data_date": "2026-10-17",
29    "blocks_data_date": "2026-10-17",
30    "notes": "This is the carrier the number block was originally assigned to. Number porting is not reflected (ported: unknown), so a number moved to another carrier still shows its original one. Line type is a hint from the carrier name only. Data is from the NANPA public reports and is not complete for routing or billing."
31  },
32  "sources": [
33    "North American Numbering Plan Administrator (nanpa.com) central office code report of 2026-10-17 and thousands-block report of 2026-10-17"
34  ]
35}

Errors

• 400 invalid_input: The request input is invalid.
• 401 unauthorized: The API key is missing, malformed, revoked or unknown.
• 402 insufficient_credits: The account does not have enough credits for this lookup. Error code: insufficient_credits. During a trial whose allowance is used up the code is trial_allowance_exhausted: nothing is charged and the customer starts the plan from the billing page.
• 405 method_not_allowed: This endpoint does not accept that HTTP method.
• 413 payload_too_large: The request body is too large.
• 429 rate_limited: Too many requests for this API key.
• 500 internal_error: An unexpected error occurred.
• 503 provider_unavailable: The data source for this product is unavailable right now.