Delete a batch job

DELETE /api/v1/verify/batch/{id}

API key required Base https://api.emailvalidator.ai 60 requests per minute per account

Permanently erase one batch job: the job record, the uploaded source file, the generated result files, and every stored copy of the addresses that were submitted. It is immediate and irreversible — the pre-signed download URLs stop working and cannot be reissued — and the job disappears from GET /api/v1/verify/batch/{id} and from the list.

A job still awaiting approval is cancelled rather than erased; it was never charged, so there is nothing to refund either way.

Requires the delete scope. A key created without naming its scopes holds read and verify only, so a key that works everywhere else on this API answers 403 insufficient_scope here until one is created with delete asked for by name.

A result still being produced cannot be deleted — that is 409 result_in_progress, not a 404. The work was charged for and is being delivered, so it finishes first; wait for it to complete and delete it then. No delete path refunds anything, ever: the result was produced and paid for.

If a charged Idempotency-Key still names this result, deleting it does not make that key unknown again. The claim outlives the result as a tombstone for the remainder of its 24 hours and answers 404 result_deleted. Retrying that key is therefore safe — it moves no money and re-runs no work — but it can never replay the original response, because that response described the thing you deleted. Submitting the same address or file again needs a NEW key.

A sandbox (ev_test_) key sees only test-mode resources, so a live id is a 404 to it here exactly as it is on the matching GET.

If the job carried a callback_url, one final batch.deleted webhook is delivered after the data is gone — the job id and deleted: true, and nothing else — so a mirrored copy can be removed in step. A job with no callback_url emits nothing, and neither does a job deleted while it was still awaiting approval: it was never started and never reported.

On this page

Parameters
Responses
Response schema
Error responses
Examples

Parameters

path · parameters

Parameter	Type	Description
id required	string · uuid	Batch job ID returned by `POST /api/v1/verify/batch`. example: 7a4e2c1b-0000-0000-0000-000000000000

Responses

200

Deleted. The body is the deleted stub — a 200 with a body rather than an empty 204, so the response still carries a quotable request_id. · application/json

401

Missing or invalid API key. · application/json

403

The API key authenticated but is not scoped for this endpoint (code: insufficient_scope). It is a 403 rather than a 401 on purpose — the credential is valid, so retrying with it can never help; a key holding the delete scope is needed, and a key created without naming its scopes does not hold it. · application/json

404

No such job for this key (code: not_found) — it never existed, it has already been deleted, it belongs to another account, or it belongs to the other mode. · application/json

409

The job is still being processed and cannot be deleted yet (code: result_in_progress) — it is resolving, probing or assembling. That work was charged for and is being delivered, so the job is neither deletable nor cancellable and nothing is refunded. Retry once it reports status: complete. · application/json

429

Rate limit exceeded. · application/json

500

Unexpected server error. The body carries code internal_error plus a request_id to quote in a support request, and never any exception detail. · application/json

Response schema · 200 · DeletedResource

The body of a successful DELETE — the "deleted stub" that DELETE /api/v1/verify/{id} and DELETE /api/v1/verify/batch/{id} return.

It is a 200 with a body rather than an empty 204, deliberately and permanently. Every /api/v1 response carries a quotable request_id, and a 204 carries no body to put one in — the response a developer is most likely to be asking about would be the one with nothing to quote. Nothing on this API answers 204.

deleted is always true. There is no deleted: false stub: a refusal is an ApiProblem with a code, never a success-shaped body saying nothing happened.

Field	Type	Description
object required	string	The type of the resource that was deleted — `verification` for a single check (the same discriminator `GET /api/v1/verify/{id}` returns) and `batch_job` for a batch. `verification` `batch_job` example: verification
id required	string · uuid	The id of the resource that is now gone — the id you passed in. example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
deleted required	boolean	Always `true`. See this schema's description. `true` example: true

Error responses

401 403 404 409 429 500 · ApiProblem · object

Standard error response shape used by all error status codes.

Field	Type	Description
status required	integer	HTTP status code mirrored in the body. example: 400
code required	string	The stable, machine-readable error vocabulary. Every `ApiProblem.code` is one of these values, and this is the WHOLE vocabulary — any one operation emits only the subset its own responses describe. Branch on this and never on the `error` prose, which is human-readable and may be reworded at any time. What each code means, the status it arrives with, and whether retrying can help are documented on the Errors page — the same page every error body links to as its `doc_url`. Three of these are specific to deletion. `result_in_progress` refuses to delete a result that is still being produced. `insufficient_permissions` refuses the ACTOR rather than the key. `result_deleted` is what a charged `Idempotency-Key` answers once the result it named has been deleted. `unauthorized` `invalid_api_key` `insufficient_scope` `insufficient_permissions` `invalid_request` `invalid_email` `invalid_callback_url` `insufficient_credits` `not_found` `job_not_pending` `result_in_progress` `needs_column_selection` `too_many_rows` `unsupported_file_type` `payload_too_large` `rate_limited` `idempotency_in_progress` `idempotency_key_reuse` `idempotency_resource_gone` `result_deleted` `internal_error` example: invalid_email
error required	string	Human-readable error message. example: Invalid email format.
param	string	The request field the failure is attributable to. Omitted when the failure is not about one specific field. example: email
details	array of string · null	Optional per-field validation messages. Null when not applicable. example: ["email: required"]
doc_url	string	Link to the documentation for this error code. example: https://emailvalidator.ai/docs/get-started/errors
request_id	string	Correlation id for this request. Quote it in a support request — it is how a single call is found in the server logs. example: 0HNCV1TQ3PLRK:00000003

Example response · 200

{
  "object": "batch_job",
  "id": "7a4e2c1b-0000-0000-0000-000000000000",
  "deleted": true
}