# Phone Carrier Lookup

Check a phone number’s carrier, type and country through the SMS.Red API. Base URL: `https://sms.red/api/v1/developer`; branded stores use their own HTTPS origin with the same paths.

Every API lookup costs **USD0.05** from the wallet bound to the API key. API requests never use the three free monthly dashboard lookups. A completed result is charged even when `valid` is false or carrier data is missing. Technical failures are refunded. An identical retry does not incur another charge.

## Create a lookup

`POST /api/v1/developer/tools/phone-carrier-lookup`

Required headers: `X-API-Key` and `Idempotency-Key`. An idempotency key must be 8–128 letters, digits, underscores or hyphens. Persist one key per intended lookup before sending. Include an international phone number with its country code; spaces, parentheses and hyphens are accepted. Do not send account IDs or dashboard price options: the API key determines the wallet and the price is fixed.

```bash
curl https://sms.red/api/v1/developer/tools/phone-carrier-lookup \
  -H "X-API-Key: YOUR_SMS_RED_API_KEY" \
  -H "Idempotency-Key: carrier-lookup-example-001" \
  -H "Content-Type: application/json" \
  -d '{"number":"+12025550142"}'
```

The number and output below are **synthetic examples**, not a claim about a real carrier.

```json
{
  "id": "lookup-example",
  "charged": "0.05",
  "free": false,
  "replayed": false,
  "result": {
    "valid": true,
    "number": "+12025550142",
    "internationalFormat": "+1 202 555 0142",
    "nationalFormat": "(202) 555-0142",
    "carrier": "Example Carrier",
    "lineType": "mobile",
    "countryCode": "US",
    "countryName": "United States",
    "location": null,
    "timezones": ["America/New_York"]
  }
}
```

`valid` indicates recognition in numbering data, not confirmed reachability or SMS eligibility. Metadata can be null or incomplete. `charged` is a USD decimal string. `free` is always false for API lookups. `replayed` is true when returning a saved result.

## Recover after an interrupted connection

Repeat the POST with the **same number and Idempotency-Key**, or use:

`GET /api/v1/developer/tools/phone-carrier-lookup/{key}`

Authenticate with the same account’s API key. Retrieval is not charged. A pending request returns `409 LOOKUP_PENDING`; wait briefly and retry the same key. Saved results are retained for **24 hours**; expired results return `410 LOOKUP_RESULT_EXPIRED`. Starting a new lookup requires a new key and costs USD0.05. Do not use a new key for an uncertain request.

## Errors

| Status | Code | Action |
| --- | --- | --- |
| 400 | LOOKUP_INVALID_NUMBER / LOOKUP_INVALID_KEY | Correct the input; no lookup was started. |
| 401 | Authentication error | Use an active key from the correct store. |
| 402 | LOOKUP_INSUFFICIENT_BALANCE | Add at least USD0.05 to the key’s wallet. |
| 404 | Lookup not found | Check the key and account/store scope. |
| 409 | LOOKUP_PENDING | Retry the same request shortly. |
| 409 | LOOKUP_KEY_REUSED | This key belongs to a different number or channel. Do not change the payload of an existing request. |
| 409 / 503 | LOOKUP_INTERRUPTED | The charge has been refunded; a new lookup needs a new key. |
| 410 | LOOKUP_RESULT_EXPIRED | The saved result has expired; a new lookup is paid. |
| 429 | LOOKUP_LIMIT_REACHED | Wait before another attempt; a technical failure is not charged. |
| 503 | LOOKUP_UNAVAILABLE | Try later; failed requests are refunded. |

The service enforces a shared limit of ten new lookup requests per minute. Allowance/lookup responses use `Cache-Control: no-store`. Lookup results are encrypted at rest for their recovery window; financial records retain identifiers and amounts without the phone number. The dashboard shows the current monthly free allowance and accepts a displayed price ceiling before submission.

[Documentation index](https://sms.red/docs/ai/index.md) · [Live API contract](https://sms.red/api/v1/developer/openapi.json)