Verify a CSV, TSV or TXT upload
Two steps. action: "get_upload_url", with the file's filename and its file_size in bytes, returns a presigned URL and a file_key; PUT the file to that URL, then call again with action: "process" and the file_key. The URL accepts exactly file_size bytes, up to 50 MB.
CSV, TSV and TXT only. An .xlsx filename is refused at the handshake with 400 Only CSV, TSV and TXT files are supported, before any upload, and a workbook uploaded under a text name is refused by process with 400 This looks like an Excel file. Save it as CSV UTF-8 and upload again. The name also says how the file is read: a .csv or .tsv as delimited records whatever Content-Type it was PUT with, and a .txt one address per line unless it was PUT with a CSV Content-Type such as text/csv. Text in UTF-8, UTF-16 (with or without a byte-order mark) or Windows-1252 (Excel's plain CSV on Windows) is read as such.
Addresses come from one column, which the response names in email_column: the column whose header names it (Email, E-mail, E-Mail-Adresse, Correo electrónico, Courriel and other languages), else the first header that mentions email with addresses under it, preferring one that is not a manager's, owner's, CC or second address, else the column with the most addresses. The full rule is at https://kawaa.com/docs/api/batch/#file-upload.
What process charges: one credit per address, counted after invalid entries and duplicates are removed, and debited up front: a 50,000-row file with 9,300 distinct valid addresses is a 9,300-credit debit before any verification starts. Check the balance first; the plan's batch ceiling also applies. An address that definitively fails to enqueue is refunded; one whose dispatch is ambiguous is reported in enqueue_unknown with its credits in credits_held until reconciliation settles it.
The process action accepts Idempotency-Key. Any field the chosen action does not read is a 400 rather than silently ignored. A webhook_secret alongside webhook_url signs the completion callback, as on POST /v1/verify/batch; without one the callback is delivered unsigned, so treat its body as a hint to go and read GET /v1/jobs/{job_id} rather than as evidence.
Request
- Base URL: https://api.kawaa.com
- URL: https://api.kawaa.com/v1/verify/file
- Auth: one of:
- API key in header X-Api-Key
- HTTP bearer
- OAuth 2 (authorization code, authorization URL https://api.kawaa.com/oauth/authorize, token URL https://api.kawaa.com/oauth/token, scopes: verification:write)
Headers
Makes a charging call safe to retry: a repeat under the same key replays the original outcome instead of buying the work again. The window depends on the route: the receipt behind it expires, and after that the same key is a new paid request. It is 30 days for a deliverability check, at least 30 days for a single find, 24 hours for an activity lookup, and 15 minutes for a bulk find. What a replay returns also differs: a batch replays its JOB, an activity lookup replays its RESULT. A different request under the same key is 409 IDEMPOTENCY_KEY_CONFLICT, before any charge.
How long a key stays safe differs per route, and for the verification routes it depends on the plan. POST /v1/verify, /v1/verify/batch and /v1/verify/file keep their receipts for the job's data-retention period, never less than 30 days, so longer on plans that keep results longer. The job itself is kept only for the plan's data-retention period, which is 7 days on Free: a repeat that arrives after the job's retention period has ended but while its receipt is still live is refused with 410 IDEMPOTENT_JOB_EXPIRED and charged nothing, rather than bought a second time; send a new key to run it again. Once the receipt expires the same key claims a fresh target and creates another paid job. POST /v1/deliverability/check keeps its receipt 30 days. POST /v1/find keeps its receipt at least 30 days and its stored address only for the plan's retention period; a repeat after the address expires but before the receipt does return 410 IDEMPOTENT_JOB_EXPIRED without charging. The activity lookups keep receipts about 24 hours, and POST /v1/find/bulk 15 minutes. Without a key, GET /v1/activity/{email} and GET /v1/activity/domain/{domain} still answer an identical repeat from the same account free for 15 minutes after the lookup that was charged (POST /v1/find/bulk does the same for its content); a key buys a fresh read inside that window. An unkeyed POST /v1/verify that arrives while an identical one from the same account is still being verified (at most 15 minutes after its charge) joins it and is not charged; once that verification has its answer, a repeat is charged as usual. Only a key makes a later retry free.
Retry with the key you have rather than minting a new one. A key is not a refund (it prevents a second charge, it does not undo the first), but it stays good far longer than the shortest advertised retention suggests, and dropping one early is how a retry becomes a second paid job.
The characters are checked after trimming. Surrounding whitespace is trimmed from the header first; the resulting key must be 1-255 printable ASCII characters (0x21-0x7e) other than a comma, with no internal spaces or anything outside that range. Leading and trailing whitespace is accepted and is not part of the key. Because OpenAPI constraints apply to the raw header rather than the post-trim value, this schema deliberately has no minLength, maxLength, or pattern; those constraints would make generated clients reject values the API accepts. Invalid post-trim values get 400 before the route starts. A UUID is the obvious choice. Sending the header twice with different raw values is also a 400. A key may not contain a comma, because a header sent more than once reaches the API joined by commas; a comma is refused with the same 400, before anything is charged. A receipt claimed under a comma-bearing key before 2026-10-03 still replays for its window.
Request body
Response
A presigned upload URL and the key to submit with it (for get_upload_url). Nothing is charged by this step.
Example response
{
"data": {
"file_key": "uploads/usr_123/2026-09-17/list.csv",
"expires_in_seconds": 900
}
}Changes
No recorded changes to this operation across all 1 revision of this API.