Documented field names
Responses use snake_case fields for lookup results and nested objects for wrappers.
API fields
Carrier lookup API fields
As of June 30, 2026, the API returns fields for validation, country and region, line type, best-effort carrier, SMS-ready and call-ready decisions, reason codes, cache state, timestamps, and credits. See the full API reference for authentication, endpoints, scopes, idempotency, rate limits, and webhooks.
Decision-ready output
The core API decisions are sms_ready, call_ready, reason, valid, line_type, and carrier.
Source docs first
If this summary ever differs from the live API, use the full API reference as the contract.
Single lookup result fields
These fields are returned by POST /v1/lookup.
| Field | Type | Use |
|---|---|---|
| input_phone | string | stringThe phone value sent in the request. |
| normalized_e164 | string | null | string | nullE.164-normalized phone number when parsing succeeds. |
| valid | boolean | null | boolean | nullTrue or false when validation completes; null when the lookup cannot complete. |
| country | string | null | string | nullTwo-letter ISO country code. |
| country_name | string | null | string | nullHuman-readable country name. |
| region | string | null | string | nullContinent or region label. |
| line_type | mobile | landline | voip | toll_free | unknown | mobile | landline | voip | toll_free | unknownLine classification returned by the lookup. |
| carrier | string | null | string | nullBest-effort carrier or network name. |
| sms_ready | boolean | booleanTrue when the row is valid, non-duplicate, and suitable for SMS sending. |
| call_ready | boolean | booleanTrue when the row is valid, non-duplicate, and suitable for calling workflows. |
| reason | string | stringDecision code such as valid_mobile, duplicate, malformed_input, or provider_unavailable. |
| cached | boolean | booleanTrue when the lookup was served from the 24-hour cache. |
| checked_at | ISO 8601 string | ISO 8601 stringTimestamp for when the lookup ran. |
| error_code | string | null | string | nullLookup or validation error code when something went wrong. |
| credits_debited | number | numberCredits charged for this lookup. Soft failures and cache hits can return zero. |
Bulk lookup wrapper fields
POST /v1/lookup/bulk returns one result wrapper per submitted phone number, preserving input order.
| Field | Type | Use |
|---|---|---|
| count | number | numberNumber of submitted phone values in the response. |
| creditsExhausted | boolean | booleanTrue when credits run out before every submitted phone is processed. |
| results[].index | number | numberZero-based input index for the result row. |
| results[].result | SingleLookupResult | SingleLookupResultThe single lookup result shape documented above. |
| results[].error | object | undefined | object | undefinedReturned for rows that cannot be processed after credits are exhausted. |
Account and key fields
GET /v1/account exposes balance, lookup spend, rate-limit budget, and API key metadata.
| Field | Type | Use |
|---|---|---|
| user_id | string | stringAccount identifier. |
| balance_credits | number | numberCurrent available credit balance. |
| today_provider_spend_usd | number | numberLookup spend recorded for the current day. |
| today_provider_calls | number | numberLookup calls recorded for the current day. |
| rate_limit.minute_remaining | number | numberRequests left in the current minute window. |
| rate_limit.day_remaining | number | numberRequests left in the current day window. |
| key.id | string | stringAPI key record identifier. |
| key.label | string | stringLabel assigned when the key was created. |
| key.prefix | string | stringVisible key prefix for identification. |
| key.scopes | string[] | string[]Scopes attached to the key, such as lookup or bulk. |
| key.expires_at | ISO 8601 string | null | ISO 8601 string | nullKey expiration date, or null for no expiration. |
| key.last_used_at | ISO 8601 string | null | ISO 8601 string | nullLast recorded key usage time. |
Batch and download fields
Batch endpoints describe processing state, counters, timestamps, and short-lived signed result URLs.
| Field | Type | Use |
|---|---|---|
| batches[].id | string | stringBatch identifier. |
| batches[].status | uploaded | processing | completed | failed | cancelled | uploaded | processing | completed | failed | cancelledCurrent batch processing state. |
| batches[].package | string | stringSelected credit package. |
| batches[].phone_column | string | stringSource column selected for the phone values. |
| batches[].default_country | string | null | string | nullDefault country used for local-format numbers. |
| counters.total_rows | number | numberRows submitted in the batch. |
| counters.unique_numbers | number | numberUnique numbers after normalization and deduplication. |
| counters.duplicate_rows | number | numberRows identified as duplicates. |
| counters.credits_used | number | numberCredits used by the batch. |
| urls.full | string | stringSigned URL for the full result CSV. |
| urls.sms_ready | string | stringSigned URL for the SMS-ready result CSV. |
| expires_in_seconds | number | numberSigned URL lifetime in seconds. |