Skip to main content

Overview

Bulk lookups run as asynchronous jobs. You submit a job, get a job id 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:
  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

Every lookup shares the same job lifecycle. Pick the one you need with the type 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 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 asynchronously. Encrata retries deliveries that don’t receive a 2xx.

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:
Statuses: 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

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:
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
Offset. Pass 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

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.