Start a verification run

Submits a list of addresses to be checked in the background and returns a run id to poll. Pass either an emails array or a list_id to check one of your prospect lists in place. A run starts in full or not at all: if the list is larger than what your allowance and credits cover today, the whole request is refused with exceeds_today and nothing is charged — the error says how many can start today, so split the list to that size or add credits. When the run finishes, the addresses that are ready for a campaign are saved as a list named "<run name> - Verified" — pass create_list: false with emails if you keep the results in your own system and do not want that list. A list_id run works exactly like Verify list in the app: contacts on that list whose address turns out invalid are marked invalid so campaigns stop emailing them, and the campaign-ready contacts are saved as "<list name> - Verified".

Required scope: verification:write.

Accepts an optional Idempotency-Key header so a retry never starts a second run.

accepted always equals submitted — a run is admitted in full or refused in full. A list too big for today comes back as a 429 exceeds_today carrying details.admissible_today; nothing is charged and nothing is created.

At most 5,000 addresses per run, and at most 5 runs started per minute.

With list_id, contacts that have no real email address yet (LinkedIn-sourced) are left out before anything is charged; skipped_without_email in the response says how many.

With create_list: false, nothing is added to your contacts or lists when the run finishes; read each address's result with GET /verification/batches/{id}/results. create_list is echoed on the run (here and on GET /verification/batches/{id}). If you change your mind, POST /verification/batches/{id}/create-list still builds the list from the finished run.

Lists made by earlier runs can be removed with DELETE /lists/{id}.