Search by task, endpoint, field, or error.

Response

A successful request can answer that an input is invalid. For example, Phone can return 200 with valid: false for an invalid number. Email rejects malformed addresses with 400. Check the fields as well as the HTTP status.

false
A negative answer to that field's question. valid: false does not mean the request failed.
null
No answer is available for that field. Keep it distinct from false, zero, or an empty string.
Omitted
The field is not part of this response. For example, optional population is absent unless its profile detail is included.

Each endpoint explains its fields, supported inputs, and coverage. Handle missing answers explicitly and allow new fields to be added to the response.

Included data

API 2.1 returns everything your plan includes. Free returns the complete everyday answer. Paid plans automatically include their available profile detail in the same lookup.

Additional fields use their natural paths, such as population, registration or current.pressure. There is no response deep object. Included unknown values can be null; zero and false keep their meanings.

Read the field your task needs. For example, Number.isFinite(response.population) distinguishes a usable count, including zero, from a missing or unknown count.

Existing explicit deep requests and earlier API versions keep their behavior and access rules. You do not need a depth option or dashboard setting for the API 2.1 paid default. Existing accounts keep their current profile access.

Profile detail uses the ordinary pooled request allowance. It covers geography profiles, Name, Industry, IP, Useragent, Domain, Weather, Phone, Time, Date, Emoji, Card, Company and Point. Language and Currency already return their complete answers without a Deep option.

Mailbox verification is a separate POST /email/verify operation using the Email verification allowance. Its result includes basic validation, so one verification call is sufficient. Carrier, Caller and HLR each return their complete selected metered result without a Deep option or another check charge.

Response headers

Authenticated requests send X-API-Key or Authorization: Bearer (see Authentication). Optionally send your own X-Request-Id for tracing. We echo it back, or generate one (e.g. req_...) if you don't.

X-API-Key: YOUR_API_KEY
X-Request-Id: req_01hxyz…

Authenticated responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset, your per-minute limit, calls left in the current window, and seconds until it rolls over. Separate from your monthly quota. On rate_limited (429), Remaining is 0 and a Retry-After header (seconds) tells you how long to wait before trying again. Concurrent callers share the team allowance, so another request can use capacity during that wait.

X-Request-Id: req_01hxyz…
X-API-Version: 2.1.0
X-Response-From: Virginia
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 42

Burst capacity lets you briefly send requests faster than your sustained rate. Burst requests still count toward your monthly quota. When X-RateLimit-Burst is present, capacity replenishes continuously. Limit is the sustained requests per minute, Burst is the bucket capacity, Remaining is the current estimate, and Reset is seconds until full recovery if no more calls arrive. On a 429, use Retry-After for the next attempt; you do not need to wait for the bucket to fill completely.

X-Response-From names the region that answered your request, such as Virginia or Tokyo.

Error bodies include that same request_id, copy it from Activity in the dashboard if you contact support.

The X-API-Version response header identifies the exact API version that answered, such as 2.1.0. Send an optional X-API-Version request header to pin your application to a supported contract. Requests with neither version header use the team setting in Settings → API version. Your authentication and lookup URL stay the same.

Questions? Email