Cancels a bulk CSV validation job that hasn't started processing yet.
Only jobs with status awaiting_upload or queued can be cancelled. Jobs that are already processing or have finished return 409. A job whose file has been uploaded but hasn't finished being accepted (it can still show awaiting_upload) also returns 409; retry after a few seconds.
Credits reserved for a queued job are returned, except monthly or daily allowance credits whose allowance has reset since the file was accepted. A bulk_validation.cancelled webhook is sent to the job's callbackUrl if one was set.
You can cancel the jobs created by the API key's user. To cancel any job in your workspace, the API key must belong to a user whose role can manage all of your team's validation jobs in the app; otherwise, cancelling a colleague's job returns 403.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Cancels a bulk CSV validation job that hasn't started processing yet.
You can cancel a job while its status is awaiting_upload or queued. Once a job is processing or has finished, it can no longer be cancelled and you'll receive a 409 error. If you cancel just after uploading the file, while the job is still being accepted (its status can still show awaiting_upload), you'll also receive a 409; retry after a few seconds.
You can cancel the jobs created by the API key's user. To cancel any job in your workspace, the API key must belong to a user whose role can manage all of your team's validation jobs in the app — the same rule the app enforces when deleting them. If it can't, cancelling a job created by a colleague returns a 403.
Example request:
curl -X DELETE https://api.allegrow.co/v1/email/validate-file/550e8400-e29b-41d4-a716-446655440000 \
-H "x-api-key: YOUR_API_KEY"Python:
import requests
response = requests.delete(
f"https://api.allegrow.co/v1/email/validate-file/{job_id}",
headers={"x-api-key": "YOUR_API_KEY"},
)JavaScript:
const response = await fetch(`https://api.allegrow.co/v1/email/validate-file/${jobId}`, {
method: 'DELETE',
headers: { 'x-api-key': 'YOUR_API_KEY' },
});Response
A successful request returns HTTP 200 with the following fields:
| Field | Description |
|---|---|
jobId | Unique identifier of the cancelled job |
status | Always cancelled |
{
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"status": "cancelled"
}What Happens When You Cancel
- The job's status changes to
cancelled, and it will not be processed. - If the job was
queued, the credits reserved for it are returned (see Credits). A job that was stillawaiting_uploadhad no credits reserved. - If you set a
callbackUrlwhen creating the job, Allegrow sends abulk_validation.cancelledwebhook. - Your queued jobs behind it move up one place.
- Cancelling doesn't revoke the job's
uploadUrl. A file uploaded to it after the job is cancelled is ignored: it isn't validated and no credits are reserved for it.
Error Responses
All errors return a JSON body with an error field:
{
"error": "Job is already running or finished and can no longer be cancelled"
}| Status | Error | Cause |
|---|---|---|
| 400 | Invalid jobId format | jobId is not a valid UUID |
| 403 | API key does not have permission to cancel this job | The job was created by another user in your workspace, and the API key's user can't manage all of your team's validation jobs |
| 404 | Job not found | No job with this ID exists for your account |
| 409 | Job is already running or finished and can no longer be cancelled | The job's status is processing, completed, insufficient_credits, failed, expired or cancelled |
| 409 | The uploaded file is still being accepted. Retry in a few seconds | The file has been uploaded, but the job hasn't finished being accepted yet (its status can still show awaiting_upload). Retry the request after a few seconds |
| 503 | Service temporarily unavailable | A dependent Allegrow service is briefly unavailable. Retry after the number of seconds in the Retry-After header |