When should I use Ask instead of Enrichment?
Use Ask when you need an answer to a specific question. Use Enrichment when you need structured profile fields.
Person APIs
Person Q&A API
Ask a natural-language question about a person and receive an AI-powered answer. Requires an identifier - at least one of email, phone, or social_media_url - plus a question (max 2000 chars). 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.
Try it needs this required parameter:
Overview
The Ask API answers natural-language questions about a person, turning resolved profile and research context into a direct answer for agents and analyst workflows.
Best for
- Agentic person research
- Answering profile-specific questions
- Reducing manual source review
Returns
- Natural-language answer
- Relevant profile context
- Status and source-oriented metadata when available
Parameters
question string required
The natural-language question to answer. Required, max 2000 characters.
email string optional
Email identifier. Validated for format.
phone string optional
Phone identifier.
social_media_url string optional
Profile URL; At least one identifier is required.
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 |
|---|---|---|
| Person Ask | 10 | 10 credits per request |
| 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
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",
"completed": true,
"result": {
"answer": "Jane Doe is currently VP of Product at Acme, where she has led the product organization since 2021."
},
"completed_on": "2026-01-15T10:31:00Z"
},
"timestamp": "2026-01-01T00:00:00"
}