id back
immediately, and Encrata delivers the finished result to your webhook. No
held-open request, no polling.
The flow is always the same:
- Submit the job with
download_link=true. - Encrata processes it in the background and, when it finishes, calls your
webhook with a
download_url. - Fetch the
download_urlwith your API key to get the file.
enc_ API key:
Supported lookups
Pick the lookup with thetype field on the unified endpoint.
Credits are reserved when a job is created and refunded for any rows that don’t
process. Size your list against your balance first - an identity job costs
1,000 credits per resolved email.
Input formats
Upload a file asmultipart/form-data (field file) or send a JSON list. Files
may be CSV, TXT, MD, XLS, XLSX, DOCX, or PDF, up to 50 MB
(60 MB for password breaches). Password jobs take SHA-1 hashes - the raw
password never leaves your infrastructure.
Run a bulk job
A single endpoint runs every lookup, and a webhook delivers the finished file.1
Register a webhook once
In Settings → Webhooks, add your endpoint and subscribe to the
bulk.completed event. Encrata signs every delivery so you can verify it -
see Webhooks.2
Submit the job
Send three fields:
type, file, and download_link=true. You get a job
id back right away (202 Accepted).3
Receive the completion webhook
When the job finishes, Encrata
POSTs your endpoint. Because you set
download_link=true, the payload carries a ready-to-fetch download_url.4
Download the file with your API key
Fetch the Add
download_url exactly as delivered, authenticating with the same
API key. It redirects to the finished file.&json=1 to get {"url": "..."} instead of a redirect.Download options
Thedownload_url in the webhook returns a CSV of every row. To get a different
format or a filtered subset, request the file yourself with the same fields:
kind matches the job type, except for two lookups: email-breaches uses kind=breaches and password-breaches uses kind=password.
string
csv (default), xlsx, or json.string
Which rows to include.
all (default), plus per-lookup subsets:
validity → valid / invalid / catch-all; identity / gender → found;
breaches / password → breached.Credits
Each processed row costs the standard rate for that lookup - see the Supported lookups table above. Rows that fail on invalid input are not charged, and any reserved-but-unused credits are refunded when the job finishes. See Credits for the full breakdown.Troubleshooting
402 - insufficient credits
402 - insufficient credits
Credits are reserved up front. Top up, or split the list into smaller jobs
that fit your balance. Unused reservations are refunded on completion.
400 - invalid type
400 - invalid type
type must be one of validity, identity, email-breaches, gender, or
password-breaches.No download_url in the webhook
No download_url in the webhook
The job was created without
download_link=true. Re-submit with the flag set
to receive the download_url in the webhook.Webhook returns 4xx / never arrives
Webhook returns 4xx / never arrives
Confirm the endpoint is subscribed to
bulk.completed and returns 2xx
quickly. Check delivery attempts in Settings → Webhooks; failed deliveries
are retried. See Webhooks for signature verification.Next steps
- Webhooks: Verify signatures and handle the
bulk.completeddelivery. - All lookups: Every lookup you can run in bulk.
- Credits: Costs, reservations, and refunds.