canonical: https://jentic.com/apis/carrierlookup.com/carrierlookup

# Carrier Lookup API

Carrier Lookup API resolves a US phone number to its underlying carrier metadata: carrier name, line type (mobile, landline, VoIP), number validity, and active status. It exposes a single GET /lookup endpoint that takes a phone number and an API key, making it a lightweight enrichment service for SMS routing decisions, contact data hygiene, fraud and bot detection, and form validation. Authentication is an API key passed as the `key` query parameter.

## For AI agents

Resolve a US phone number to carrier name, line type (mobile/landline/VoIP), validity, and active status via a single GET /lookup call.

## Scope

Does not handle international phone validation, SMS sending, or voice calls - use for US carrier and line-type lookup only.

## Capabilities

- Identify the carrier behind a US phone number (Verizon, AT&T, T-Mobile, etc.)
- Detect line type - mobile, landline, or VoIP - to inform SMS deliverability
- Validate that a phone number is well-formed and reachable
- Check whether a phone number is currently active
- Filter out VoIP numbers in fraud-screening or signup-quality workflows

## Use cases

### Signup Form Phone Validation

Block signups using fake or VoIP-only phone numbers. On submission, call GET /lookup with the user-entered number; if the response says the number is invalid, inactive, or VoIP (depending on policy), reject or flag the registration. This catches throwaway numbers commonly used to evade per-account limits.

Example prompt: Look up the phone number a user just entered, and reject the form if line type is VoIP or active is false.

### SMS Deliverability Routing

Route messages intelligently based on carrier and line type. Mobile numbers go via SMS; landlines and VoIP can be routed to voice or skipped entirely. The Carrier Lookup response provides the carrier name and line_type fields needed to make this routing decision per-recipient before submitting to a messaging gateway.

Example prompt: For each recipient phone number, call GET /lookup and only queue SMS messages to those returned as line_type=mobile.

### CRM Contact Data Hygiene

Run a periodic enrichment pass over a CRM's phone column to mark inactive or invalid numbers and append carrier metadata. Each contact gets a single GET /lookup request, and the response fills carrier, line_type, valid, and active fields back onto the record. This avoids wasting outbound calls and SMS attempts on stale numbers.

Example prompt: Iterate the CRM contacts table, call /lookup for each phone, and update the record with carrier, line_type, and active status.

### AI Agent Phone Verification via Jentic

Plug Carrier Lookup into an agent through Jentic so a question like 'is this number a real mobile?' becomes a single tool call. Jentic returns the GET /lookup operation schema, holds the API key in its vault, and lets any framework (LangChain, CrewAI, MCP) issue the lookup without managing the query parameter manually.

Example prompt: Through Jentic, look up phone number 415-555-1234 and return carrier, line_type, and active fields.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /lookup | Look up carrier information for a US phone number |

## Key resources

- **Lookup** — Resolve a US phone number to carrier name, line type, validity, and active status

## Why Jentic

- **Setup:** Wiring the Carrier Lookup API by hand means passing your key in the key query parameter on every call to the api.carrierlookup.com host yourself. Through Jentic you install once, import the Carrier Lookup API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Carrier Lookup exposes a single lookup operation, so you scope by operation: limit the agent to the carrier lookup it needs, and it can do nothing beyond that call.
- **Credential handling:** Your Carrier Lookup API key is stored once, encrypted, by your own Jentic One instance and injected into the key query parameter at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'look up a phone carrier' or 'detect a VoIP number', and Jentic returns the lookup operation with its input schema so the agent supplies the right parameters without browsing the reference docs.

## Related APIs

- **CarAPI.dev** — Vehicle data API for VIN decoding and history; pairs with phone validation in marketplace fraud checks.
- **Careerjet Job Search API** — Job search API often paired when validating candidate contact data.
- **Careem POS API** — Restaurant POS integration; phone validation supports order confirmation flows.

## FAQ

### What authentication does the Carrier Lookup API use?

Carrier Lookup uses an API key passed as the `key` query parameter on every request. Through Jentic the key is stored encrypted in the credential vault and injected into the URL at request time, so the raw key never appears in chat logs or agent prompts.

### What does the Carrier Lookup API return for a phone number?

The /lookup endpoint returns the carrier name (Verizon, AT&T, T-Mobile, etc.), the line type (mobile, landline, VoIP), a validity flag indicating whether the number is well-formed, and an active flag indicating whether the line is in service. This combination supports both routing and fraud-screening use cases.

### Does Carrier Lookup work for non-US phone numbers?

The API is documented as a US phone number lookup service. Coverage outside the US is not part of the OpenAPI surface; for international validation pair Carrier Lookup with another provider that covers your target geographies.

### Can I use Carrier Lookup to detect VoIP numbers?

Yes. The line_type field returned by GET /lookup will indicate `voip` for VoIP numbers, `mobile` for cellular, and `landline` for fixed lines. This is the standard signal used by signup-fraud screens to filter out disposable or virtual numbers.

### What are the rate limits for the Carrier Lookup API?

The OpenAPI specification does not declare numeric rate limits. Limits are tied to the plan associated with your API key - keep concurrent requests modest and back off on 429 responses. Refer to https://www.carrierlookup.com/carrier-lookup-api-integration/ for plan tiers and quotas.

### How do I look up a number through Jentic?

Run `pip install jentic`, then use Jentic's search to find the lookup operation with the query "look up phone carrier", load the schema, and execute with `{"number": "4155551234"}`. Jentic calls GET /lookup with your API key from the vault and returns carrier, line_type, valid, and active fields.

### Can I batch-process a list of phone numbers?

The API exposes a single GET /lookup endpoint that takes one number per call. To process a list, iterate sequentially or in modest concurrency from your application; the API does not provide a built-in bulk endpoint, so batching is the caller's responsibility.

### Can I limit what my agent is allowed to do with the Carrier Lookup API?

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use. The Carrier Lookup API exposes a single operation, GET /lookup, so you scope by operation: grant the agent only the carrier lookup it needs, and it can do nothing beyond that one call. Your API key stays with your Jentic One instance and is injected into the request at execution time rather than exposed to the agent.