Overview
Bulk lookups run as asynchronous jobs. You submit a job, get a jobid back
immediately, and Encrata delivers the finished result to your webhook - there’s
no need to hold a request open or poll for completion.
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
Every lookup shares the same job lifecycle. Pick the one you need with thetype
field on the unified endpoint (or its dedicated -jobs path).
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.Check job status
You don’t need to poll - the webhook tells you when a job is done. But you can request the current status at any time, for example to show progress in your UI:queued, processing, completed, failed, cancelled.
Validity reports valid_count / invalid_count / catch_all_count /
risky_count; identity and gender report found_count (gender also
male_count / female_count); breaches and password report breached_count.
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:
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.Read results programmatically
To stream results into your own system rather than download a file, page the job’s/results endpoint. Two pagination styles are supported.
Cursor (recommended for large jobs). Start with cursor=0 and follow
next_cursor until it comes back empty. Keyset paging stays fast at millions of
rows.
Python
page and page_size for a fixed-window read (returns total
and pages). Simpler, but slower on very large jobs.
Manage jobs
<kind> is validity, identity, breaches, gender, or password.
Credits
Each processed row costs the standard rate for that lookup. Rows that fail on invalid input are not charged, and any reserved-but-unused credits are refunded when the job finishes.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.