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.completed delivery.All lookups
Every lookup you can run in bulk.
Credits
Costs, reservations, and refunds.