--- title: "Carrier Lookup (original carrier) reference" url: "https://lookvalid.com/docs/api/carrier-lookup.md" canonical_url: "https://lookvalid.com/docs/api/carrier-lookup" last_updated: "2026-10-22" type: "reference" summary: "Request and response reference for Carrier Lookup (original carrier): parameters, response fields, credit cost and error codes." related: ["https://lookvalid.com/docs/errors.md"] --- # Carrier Lookup (original carrier) reference Request and response reference for Carrier Lookup (original carrier): parameters, response fields, credit cost and error codes. 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. ```http 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](https://lookvalid.com/docs/credits-and-billing.md) for the full picture. ## Request Send a JSON body with `Authorization: Bearer `. The body can be up to 64 KB. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `phone` | string | yes | Up to 64 characters. | ### Example request **cURL** ```sh curl -X POST https://YOUR_API_HOST/v1/carrier-lookup \ -H "Authorization: Bearer $LOOKVALID_API_KEY" \ -H "Content-Type: application/json" \ -d '{"phone":"+12024561111"}' ``` **Node.js** ```js const response = await fetch("https://YOUR_API_HOST/v1/carrier-lookup", { method: "POST", headers: { Authorization: `Bearer ${process.env.LOOKVALID_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "phone": "+12024561111" }), }); const result = await response.json(); if (!response.ok) throw new Error(`${result.error.code}: ${result.error.fix}`); console.log(result.found, result.data, result.credits_charged); ``` **Python** ```python import os import requests response = requests.post( "https://YOUR_API_HOST/v1/carrier-lookup", headers={"Authorization": f"Bearer {os.environ['LOOKVALID_API_KEY']}"}, json={ "phone": "+12024561111", }, timeout=30, ) result = response.json() if not response.ok: raise RuntimeError(f"{result['error']['code']}: {result['error']['fix']}") print(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 | Field | Type | Notes | | --- | --- | --- | | `request_id` | string | - | | `product` | "carrier-lookup" | - | | `found` | boolean | False means the lookup ran and found nothing; it is free. | | `reason` | string or null | Why nothing was found; null when found. | | `sources` | array of string | Where the data came from, including any attribution the licence requires. | | `credits_charged` | integer | 0 for a cache hit, a not-found result or an error. | | `credits_remaining` | integer | - | | `cache_hit` | boolean | True when the account already paid for this lookup within the cache window. | | `cache` | object | - | ### The `data` object Present when `found` is true, otherwise `null`. | Field | Type | Notes | | --- | --- | --- | | `phone_e164` | string | - | | `npa_nxx_block` | object | - | | `npa_nxx_block.npa` | string | - | | `npa_nxx_block.nxx` | string | - | | `npa_nxx_block.block` | string | - | | `original_carrier` | object | - | | `original_carrier.company` | string | - | | `original_carrier.ocn` | string | - | | `original_carrier.ocn_category` | null | NANPA publishes no OCN category | | `rate_center` | string or null | - | | `state` | string | - | | `assignment_level` | string | One of `thousands_block`, `central_office_code`. | | `code_holder` | object | Holder of the whole central office code; differs from the carrier when the code is pooled | | `code_holder.company` | string | - | | `code_holder.ocn` | string | - | | `in_service` | boolean | - | | `assigned_since` | string or null | - | | `line_type` | string | One of `mobile`, `unknown`. | | `line_type_basis` | "carrier name keywords, not an official category" | - | | `ported` | "unknown" | - | | `data_date` | string | Date of the NANPA central office code report | | `blocks_data_date` | string | Date of the NANPA thousands-block file | | `notes` | string | - | ### 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. ```json { "product": "carrier-lookup", "found": true, "data": { "phone_e164": "+12024561111", "npa_nxx_block": { "npa": "202", "nxx": "456", "block": "1" }, "original_carrier": { "company": "VERIZON WASHINGTON DC, INC.", "ocn": "9211", "ocn_category": null }, "rate_center": "WSHNGTNZN1", "state": "DC", "assignment_level": "central_office_code", "code_holder": { "company": "VERIZON WASHINGTON DC, INC.", "ocn": "9211" }, "in_service": true, "assigned_since": null, "line_type": "unknown", "line_type_basis": "carrier name keywords, not an official category", "ported": "unknown", "data_date": "2026-10-17", "blocks_data_date": "2026-10-17", "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." }, "sources": [ "North American Numbering Plan Administrator (nanpa.com) central office code report of 2026-10-17 and thousands-block report of 2026-10-17" ] } ``` ## Errors - `400` [`invalid_input`](https://lookvalid.com/docs/errors.md#invalid_input): The request input is invalid. - `401` [`unauthorized`](https://lookvalid.com/docs/errors.md#unauthorized): The API key is missing, malformed, revoked or unknown. - `402` [`insufficient_credits`](https://lookvalid.com/docs/errors.md#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`](https://lookvalid.com/docs/errors.md#method_not_allowed): This endpoint does not accept that HTTP method. - `413` [`payload_too_large`](https://lookvalid.com/docs/errors.md#payload_too_large): The request body is too large. - `429` [`rate_limited`](https://lookvalid.com/docs/errors.md#rate_limited): Too many requests for this API key. - `500` [`internal_error`](https://lookvalid.com/docs/errors.md#internal_error): An unexpected error occurred. - `503` [`provider_unavailable`](https://lookvalid.com/docs/errors.md#provider_unavailable): The data source for this product is unavailable right now. ## Related - [Errors](https://lookvalid.com/docs/errors.md)