Skip to main content
Bulk operations run any Encrata lookup over hundreds to millions of records from a single API call. Submit the list as a background job, get a job id back immediately, and Encrata delivers the finished result to your webhook. No held-open request, no polling. The flow is always the same:
  1. Submit the job with download_link=true.
  2. Encrata processes it in the background and, when it finishes, calls your webhook with a download_url.
  3. Fetch the download_url with your API key to get the file.
Every request is authenticated with your enc_ API key:

Supported lookups

Pick the lookup with the type field on the unified endpoint.
Dashboard only: Job status, paginated results, cancellation, retry, and deletion routes under /api/jobs/{kind} are not available with an API key on developer.encrata.com. Submit with POST /api/jobs/bulk, receive the completion webhook, then download with GET /api/jobs/exports/download.
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 as multipart/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 download_url exactly as delivered, authenticating with the same API key. It redirects to the finished file.
Add &json=1 to get {"url": "..."} instead of a redirect.
A complete receiver - verify the signature, then download:
Acknowledge the webhook quickly (return 2xx), then download the file in the background. Encrata retries deliveries that don’t receive a 2xx.

Download options

The download_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:
The export 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

Credits are reserved up front. Top up, or split the list into smaller jobs that fit your balance. Unused reservations are refunded on completion.
type must be one of validity, identity, email-breaches, gender, or password-breaches.
The job was created without download_link=true. Re-submit with the flag set to receive the download_url in the webhook.
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.