veridock.io

Bulk verification

Submit a list, let it run in the background, then page through the results or export them.

Submit a list#

POST/v1/bulk/verify1 credit per unique address, reserved up front
FieldTypeDescription
emailsstring[]1 to 50,000 addresses. Duplicates are removed before charging.
namestring?Label shown in the dashboard (max 120 chars).
Example
curl https://new-project-rho-ecru.vercel.app/v1/bulk/verify \
  -H "Authorization: Bearer vd_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"October signups","emails":["a@example.com","b@example.com"]}'
202 Accepted
{
  "job": {
    "id": "job_…",
    "name": "October signups",
    "status": "queued",
    "source": "api",
    "total": 2,
    "processed": 0,
    "counts": {},
    "credits_reserved": 2,
    "created_at": "2026-10-21T08:00:00.000Z",
    "started_at": null,
    "completed_at": null,
    "expires_at": "2026-11-20T08:00:00.000Z",
    "error": null
  }
}

Credits

The whole list is reserved atomically. If you do not have enough credits you get 402 insufficient_credits with available and required, and nothing is charged. Unused reservations are refunded if a job fails.

Poll the job#

GET/v1/bulk/jobs/:idfree
FieldTypeDescription
results"1"?Include result rows.
statusenum?Filter rows by status (valid, invalid, …).
limitinteger?Rows per page, max 1000 (default 100).
offsetinteger?Row offset for paging.
Example
curl https://new-project-rho-ecru.vercel.app/v1/bulk/jobs/job_…?results=1&status=invalid&limit=1000 \
  -H "Authorization: Bearer vd_live_…"
200 OK
{
  "job": { "id": "job_…", "status": "completed", "total": 2, "processed": 2, "counts": { "valid": 1, "invalid": 1 }, … },
  "results": [
    { "email": "b@example.com", "status": "invalid", "reason": "no_mx_records", "result": { "mx_hosts": [], "suggestion": null, … } }
  ],
  "pagination": { "limit": 1000, "offset": 0, "total": 2 }
}

Job status moves queued → processing → completed (or failed). Poll every few seconds; lists of a few thousand addresses usually finish within a minute. Results stay available for 30 days and can be exported as CSV from the Lists page.

Related

Lists in the dashboardPaste or upload, watch progress, export CSVPrivacy & retention