API access

Carrier lookup API for phone validation and SMS readiness

A REST API for phone validation and carrier lookup. Send a number, get back its normalized E.164 form, validity, country and region, line type, best-effort carrier, SMS-ready and call-ready decisions, a reason code, cache state, and the credits the call debited. Authentication is a Bearer API key, created on our developer platform at phonelistcleaner.com, which handles keys, credits and billing.

Base URL: https://api.phonelistcleaner.com
Auth: Bearer plc_<key>
Bulk limit: 100 numbers / call

Get an API key Jump to the quickstart See API pricing

Quickstart

1. Get an API key
Create a key at phonelistcleaner.com/app/api-keys. Keys look like plc_… and are shown once at creation, so store it immediately. Keys can be set to expire after 30 days, 90 days, a year, or never.
2. Pick your scopes
Every key carries scopes. lookup covers single lookups and bulk covers batch calls. Issue least-privileged keys: an integration that only calls /v1/lookup does not need the bulk scope.
3. Make your first call
Send the key as a Bearer token against https://api.phonelistcleaner.com. A call with no key returns 401 missing_or_invalid_api_key.

Request

curl -X POST https://api.phonelistcleaner.com/v1/lookup \
  -H "Authorization: Bearer plc_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+447400123456","defaultCountry":"GB"}'

Response

{
  "input_phone": "+447400123456",
  "normalized_e164": "+447400123456",
  "valid": true,
  "country": "GB",
  "country_name": "United Kingdom",
  "region": "Europe",
  "line_type": "mobile",
  "carrier": "EE",
  "sms_ready": true,
  "call_ready": true,
  "reason": "valid_mobile",
  "cached": false,
  "checked_at": "2026-06-30T10:04:11.204Z",
  "error_code": null,
  "credits_debited": 1
}

Endpoints

Six endpoints, all under https://api.phonelistcleaner.com. Requests and responses are JSON.

Method	Path	Purpose	Scope
POST	/v1/lookup	Look up a single phone number.	lookup
POST	/v1/lookup/bulk	Look up 1 to 100 numbers in one request.	bulk
GET	/v1/account	Account snapshot: credit balance, key metadata, rate-limit state.	—
GET	/v1/batches	List your 25 most recent batches.	—
GET	/v1/batches/{id}	Read one batch's status and counters.	—
GET	/v1/batches/{id}/results	Signed download URLs for both result CSVs.	—

Bulk request

curl -X POST https://api.phonelistcleaner.com/v1/lookup/bulk \
  -H "Authorization: Bearer plc_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"phones":["+447400123456","+12025550143"],"defaultCountry":"GB"}'

Status codes

400: Malformed request body, or a phone value that cannot be parsed.
401: Missing, invalid, revoked or expired API key.
402: Credit balance exhausted.
403: The key lacks the scope this endpoint requires.
404: Batch id does not exist, or is not yours.
409: Idempotency conflict, or results not ready yet.
429: Rate limit reached. Back off and retry.

Every response field is documented on the API fields reference. For idempotency keys, webhooks and the full OpenAPI spec, see the full API reference.

API pricing

The API is billed separately from the per-reveal pricing on this site. API calls draw down prepaid credits bought on our developer platform: one credit per unique, parseable, uncached number. Credit packs are one-time purchases, there is no subscription, and credits do not expire.

Credits	Price	Per credit
2,500	$19	$0.0076
10,000	$49	$0.0049
50,000	$149	$0.00298
100,000	$249	$0.00249
250,000	$499	$0.001996

Calls that cost nothing

Malformed input that cannot be parsed. It never reaches a lookup.
Duplicates inside one batch. Only the first occurrence of a normalized number is billed.
Cache hits inside the 24-hour window, which return credits_debited: 0.
Lookups we cannot resolve. The credit is refunded automatically.

Watching your balance

Every lookup response carries credits_debited, and GET /v1/account returns the remaining balance. A 402 means the balance is exhausted. A hard daily spend cap applies and the balance never goes negative.

Buy API credits Full billing rules

Looking for one-off lookups instead of an integration? The Carrier Reveal pricing page covers pay-per-reveal lookups on this site. It does not apply to API calls.

When the API is the right fit

The self-serve lookup screen is useful for testing individual numbers and small batches. API access is better when phone validation and SMS-readiness decisions need to happen automatically inside signup, campaign, CRM, support, or calling workflows. Teams usually request API access when manual exports slow down reviews or when validated phone fields need to join internal operational data.

Common API workflows

SMS readiness gates

Call the API before campaigns or onboarding messages, then use valid, line_type, sms_ready, call_ready, and reason to decide which numbers should move forward.

CRM and data quality

Normalize raw phone values, identify duplicate or malformed rows, and keep the carrier and country fields attached to the records your CRM or data pipeline needs.

Calling workflows

Use call_ready, line_type, carrier, and reason to separate callable mobile, landline, and VoIP rows from invalid, duplicate, or unresolved inputs.

Data available through API access

Field availability depends on country and carrier network coverage. The full field reference, including bulk wrappers and batch shapes, is on the API fields page.

Raw and normalized phone fields: input_phone and normalized_e164

Validation fields: valid, error_code, and reason

Country fields: country, country_name, and region

Line classification: line_type

Best-effort network label: carrier

Decision flags: sms_ready and call_ready

Cache and timing fields: cached and checked_at

Billing field: credits_debited

Rate limits and retries

Per-minute and per-day limits apply to each key, and the remaining allowance for both windows is returned by GET /v1/account under rate_limit.minute_remaining and rate_limit.day_remaining. A 429 means back off rather than retry immediately. Cache hits are served from a 24-hour cache and can return credits_debited: 0, so re-checking the same number inside a day is cheap.

Privacy expectations

Phone numbers should be treated as sensitive input in every API workflow. Normalize numbers to E.164 format before lookup, keep payment and billing metadata free of raw phone numbers, and confirm retention, logging, and batching expectations before sending production traffic.

Get your API key

Create a key on our developer platform, then point your first request at https://api.phonelistcleaner.com/v1/lookup.

Create an API key Contact Carrier Reveal