Skip to content
SimpleCold

API docs

Endpoints

Download the results

On this page

Downloads a bulk job's results as a CSV or JSON file. The file keeps every original column and adds the result columns at the end.

GET/api/v1/api-validation/bulk/:id/download-result

Parameters

Path

ParameterTypeRequiredDescription
idstringYesThe job id returned by the upload.

Query

Both query parameters are required. Leaving either out returns a 400.

ParameterTypeRequiredDescription
outputstringYesjson returns a JSON array. Any other value (use csv) returns CSV.
verifiedOnlystringYestrue returns only rows with the reason code mailbox_found. Any other value (use false) returns every row.

When you can download

Job statusWhat you get
COMPLETEDThe full result file.
CANCELEDEvery row. Rows that never got a result show the reason code no_response (result Risky).
IN PROGRESS, CANCELINGA snapshot of the results so far. Rows not checked yet show the reason code processing (result Processing).
QUEUE, FAILEDA 400 with Results are not available for this job.

Wait for COMPLETED before you act on the file. See Get the job status.

Examples

curl -o results.csv \
  "https://simplecold.com/api/v1/api-validation/bulk/b0f6c2a4-6a3e-4c55-9d1e-2f8a7c1b9e40/download-result?output=csv&verifiedOnly=false" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON, only mailbox_found rows
curl -o verified.json \
  "https://simplecold.com/api/v1/api-validation/bulk/b0f6c2a4-6a3e-4c55-9d1e-2f8a7c1b9e40/download-result?output=json&verifiedOnly=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful download is the file itself, not the JSON envelope. It is sent as application/octet-stream with Content-Disposition: attachment; filename="<job-id>-validation-result.csv" (or .json).

File format

Every download uses this format, including downloads of jobs that finished before 2026-10-27.

CSV

Your original columns come first, with their exact header text and casing, in the same order. These columns are added after them, in this order:

ColumnDescription
ResultDeliverable, Risky, Undeliverable, or Processing while the job is still running.
ReasonOne plain sentence explaining the result. The same text as statusMessage in the API.
Reason codeThe reason code, for example mailbox_not_found. See Statuses and categories.
SuggestionThe corrected address for possible_typo, otherwise empty.
Retry laterYes when a later re-check may change the result (blocked_by_server, no_response, server_error), otherwise No.
DomainThe domain part of the address.
Mail server countryCountry code where the domain's mail servers appear to be.
Website countryCountry code where the domain's website appears to be.
Website languageLanguage of the domain's website.
results.csv
First Name,Email,Company,Result,Reason,Reason code,Suggestion,Retry later,Domain,Mail server country,Website country,Website language
"Jane","[email protected]","Acme","Deliverable","The mailbox exists and accepts mail.","mailbox_found","","No","acme.com","US","US","EN"
"Bob","[email protected]","Initech","Undeliverable","Possible typo. Did you mean [email protected]?","possible_typo","[email protected]","No","gmial.com","","",""

If one of your columns already has one of these names (ignoring case), your column keeps its name and ours gets (SimpleCold) added, for example Domain (SimpleCold).

Cells that start with =, +, - or @ get a leading apostrophe ('), so a spreadsheet app shows them as text instead of running them as formulas.

JSON

The same rows as an array of objects. Your original fields keep their original keys (the exact header text). These keys are added after them:

KeyTypeDescription
resultstringdeliverable, risky, undeliverable, or pending while the job is still running.
reasonCodestringThe reason code, for example mailbox_not_found.
reasonstringOne plain sentence explaining the result.
suggestionstring | nullThe corrected address for possible_typo, otherwise null.
retryLaterbooleantrue when a later re-check may change the result.
domainstringThe domain part of the address.
mailServerCountrystring | nullCountry code where the domain's mail servers appear to be.
websiteCountrystring | nullCountry code where the domain's website appears to be.
websiteLanguagestring | nullLanguage of the domain's website.

If one of your keys clashes with one of these, ours gets (SimpleCold) added, the same as in CSV.

results.json
[
  {
    "First Name": "Jane",
    "Email": "[email protected]",
    "Company": "Acme",
    "result": "deliverable",
    "reasonCode": "mailbox_found",
    "reason": "The mailbox exists and accepts mail.",
    "suggestion": null,
    "retryLater": false,
    "domain": "acme.com",
    "mailServerCountry": "US",
    "websiteCountry": "US",
    "websiteLanguage": "EN"
  }
]

verifiedOnly=true is handy when you only want a send-ready list: it keeps only mailbox_found rows. Most teams download every row instead, because the risky and undeliverable rows tell you which contacts to suppress and which domains accept all mail.

Errors

HTTPMessageCause
400Please check your input and try again.output or verifiedOnly is missing. The body is { "success": false, "message": ..., "data": [...] }.
400Job not found.No job with this id in your organization.
400Results are not available for this job.The job is QUEUE or FAILED.
401Invalid API key and othersSee authentication errors.
429Rate limit exceeded. Maximum 30 downloads per minute per API key.Over 30 downloads per minute with this API key. Wait Retry-After seconds.
Download the results | SimpleCold API docs