API reference

Bulk jobs

Verify a list of addresses asynchronously. Submit a job, poll its progress, then download the results.

Create a job

POST/api/bulk
ParameterTypeDescription
emails*string[]Array of email addresses to verify.
namestringHuman-readable name shown in the dashboard.
curl https://api.purelist.io/api/bulk \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"q3_leads.csv","emails":["a@example.com","b@example.com"]}'

Credits are reserved up front for the whole list. To upload a CSV file directly, POST it as multipart form-data to /api/bulk/upload with a file field.

{
  "id": "job_06f84c78...",
  "name": "q3_leads.csv",
  "rows": 2,
  "status": "Processing",
  "progress": 0,
  "valid": 0,
  "invalid": 0,
  "risky": 0,
  "role": 0,
  "created_at": "2026-06-27T09:39:40Z"
}

Poll job status

GET/api/bulk/{job_id}

Poll until status is Complete. progress is a 0–100 percentage; counts update as batches finish.

{
  "id": "job_06f84c78...",
  "name": "q3_leads.csv",
  "rows": 2,
  "status": "Complete",
  "progress": 100,
  "valid": 1,
  "invalid": 0,
  "risky": 1,
  "role": 0,
  "created_at": "2026-06-27T09:39:40Z"
}

List all your jobs with GET /api/bulk.

Results & export

GET/api/bulk/{job_id}/results

Returns the per-address results as JSON — each row has the same fields as a single verification (status, score, confidence, action, risk, reasons, mailbox_confirmed, verification_method).

GET/api/bulk/{job_id}/export?format=csv

Download the results as a file. format may be csv, xlsx, or pdf.