Requested fields
Use the person lookup API when the request should name exact fields, such as emails, phones, work history, social profiles, or other targeted profile attributes.
Person APIs
Person Lookup Fields API
Targeted lookup: resolve a person from one or more identifiers and return only the fields (and/or profile_urls) you ask for. Requires at least one of email, phone, social_media_url, or name, plus at least one requested field or profile-url key. Credits are billed per requested unit. Use /person/email when you only need the best work email, and /person/phone when you only need the mobile number. The request is queued and returns a request_id; poll the status endpoint or supply a callback_url.
Manual credentials take precedence over your account key.
Overview
Lookup Fields is a selective person lookup API: provide identifiers and request only the fields your workflow needs, from contact details to work history or social context.
Best for
- Avoiding full-profile overfetch
- Appending only selected fields
- Building targeted contact-data workflows
Returns
- Requested person fields
- Resolved identity context
- Field-specific availability results
Implementation guide
Identifier strategy
Start from the strongest identifier you have, then include fallback context such as name, company, location, or social URL to improve match quality.
Response shape
The response stays focused on the requested fields, making it easier to control payload size, credits, and downstream schema mapping.
Parameters
email string optional
Email identifier.
example.com is rejected as fake/test; lowercased.phone string optional
Phone identifier. At least 7 digits, ≤50 chars.
social_media_url string optional
Profile URL (aliased as
social_url/profile_url/url). At least one identifier is required.name string optional
Full name.
company string optional
Employer context.
company_domain string optional
Company domain; scheme/path/www stripped, must be a bare domain.
location string optional
Free-form location; split into
city/state on the first comma.state string optional
State/region context for a name-based lookup.
fields array | string optional
Field names to return (array or comma-separated). Required unless
profile_urls is supplied. Supported: displayname, firstname, lastname, best_work_email, best_personal_email, mobile, address, location, headline, current_company, current_title, photo_url. The mobile selector returns phone data under result.fullphone; each phone object uses phone_type for classification and does not return a type alias.profile_urls array optional
Specific profile-url keys to resolve. Max 10.
0 / 10
probability_score boolean optional
Include match-probability scoring.
e.g. false
lookup_mode string optional
Response-depth preference. Choose based on how long you can wait for the response or callback:
fast returns sooner with a lighter search, balanced allows more time to improve the chance of returning requested fields, and deep gives the search the most time for harder-to-find data when omitted.callback_url string optional
If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured.
Retrieving the result
This endpoint is asynchronous. A successful submit returns a request_id while the job runs in the background. Poll the same path with a GET request - same authentication headers - passing the request_id as a
query parameter:
Loading your API credentials...
Each poll returns the job's current status; once it is completed the payload carries the result shown under Responses. Polling an
unknown or expired request_id returns 404 request_not_found.
| Status | Meaning |
|---|---|
| queued · processing · pending | The job is still running - keep polling. |
| completed | The job finished; the payload carries the result and completed: true. |
| failed | Terminal - the job could not complete; the error field explains why. |
Poll every few seconds at first, backing off for long-running jobs. Polling is free - status checks never burn credits.
Prefer push delivery?
Supply the optional
callback_url parameter and the completed payload is POSTed to your endpoint
when the job finishes - no polling required. Delivery is retried up to 5 times with exponential backoff (1s,
5s, 15s, 1m, 5m) and a 30-second timeout per attempt; respond with a 2xx status to acknowledge receipt.Credit usage
Credits are charged based on the matched configuration. The listed cost is the per-result unit price.
| Feature | Credits | Notes |
|---|---|---|
| Lookup Fields | - | Billed per requested unit (count of fields + profile_urls) |
| Email field | 1 | /person/email - billed when an email field is requested |
| Phone field | - | /person/phone - billed when a phone field is requested |
| No match | 0 | Empty results never burn credits |
Heads up
Empty results do not burn credits.
Responses
200 Status poll result - returns the current request status and result/error fields when available
202 Request queued - poll the status endpoint (or wait for the callback) with the returned request_id
400 Malformed JSON, missing required parameters, or an invalid field
401 Missing or invalid API credentials
402 insufficient_credits - not enough credits to complete the request
403 subscription_required or ip_not_allowed
404 request_not_found - no matching request is available for this API key
429 rate_limit_exceeded
503 service_unavailable - the API is temporarily unavailable
404 not_found - the lookup completed but no matching data exists (a completed response, not a processing failure)
A successful response wraps the payload in the { success, data, timestamp } envelope (also shown live in the panel on the right):
{
"success": true,
"data": {
"request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
"status": "completed",
"lookup_mode": "balanced",
"completed": true,
"result": {
"best_work_email": "[email protected]",
"fullphone": [
{
"fullphone": "+1-555-123-4567",
"phone_type": "mobile"
}
],
"organizations": [
{
"name": "Acme",
"title": "Senior Product Manager",
"is_current": true
}
]
},
"completed_on": "2026-01-15T10:31:00Z"
},
"timestamp": "2026-01-01T00:00:00"
}