Bulk Verification

Verify large volumes of phone numbers by uploading a CSV file through the dashboard or API.

Workflow

The bulk verification process follows this sequence:

Bulk processing supports both lookup modes: static (the default, 1 credit per number) and current, which resolves the current serving carrier of every valid number — 10 credits per successful lookup, 1 credit when the carrier can't be resolved, nothing for invalid rows. On the free plan, Current files draw pay-as-you-go credits only. See supported countries for Current lookups.

Upload a CSV file (/v3/file/upload)
Start verification (/v3/file/verify)
Poll status (/v3/file/status) until processing completes
Download the results (/v3/file/download)

POST /v3/file/upload

Upload a CSV file for bulk verification. Content-Type: multipart/form-data.

Parameters

Name	Type		Description
file	file	Required	CSV file (multipart form field). Max 100 MB, max 1 million rows.
column	number	Required	Zero-based index of the column containing phone numbers.
firstrow	number	Required	Zero-based index of the first data row (use to skip header rows).

Example

curl -X POST https://api.veriphone.io/v3/file/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@contacts.csv" \
  -F "column=0" \
  -F "firstrow=1"

Response 200

{
  "result": "success",
  "id": "abc123def456",
  "column": 0,
  "firstrow": 1,
  "lastrow": 5000,
  "record1": "+14158586273",
  "record2": "+442071234567"
}

Field	Type	Description
id	string	Upload ID. Use this for all subsequent file operations.
lastrow	number	Total number of rows detected in the file.
record1	string	Sample value from the first data row at the specified column.
record2	string	Sample value from the second data row at the specified column.

Errors

Code	Message
400	`File type not supported` (must be `.csv`)
400	`File is too large` (max ~100 MB)
400	`Too many entries` (max 1 million rows)
400	`Missing column` / `Missing firstrow`

POST /v3/file/verify

Starts a background job to verify all phone numbers in the uploaded file.

Parameters

Name	Type		Description
id	string	Required	Upload ID returned by `/v3/file/upload`.
default_country	string	Optional	ISO 3166-1 alpha-2 country code for numbers without a country prefix.
mode	string	Optional	`static` (default) or `current`. Current mode resolves the serving carrier of every valid number and appends four extra result columns — see the results format.

Example

curl -X POST "https://api.veriphone.io/v3/file/verify?id=abc123def456" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "status": "success",
  "id": "abc123def456"
}

Errors

Code	Message
402	`Insufficient credits` — the message quotes the file's full cost (rows × credits per lookup), and the body carries `credits_required`, `credits_available` and `credits_missing`. The account must cover every row at the mode's full rate to start.
403	`File not ready` / `Unauthorized file access` / `Account inactive`
404	`File not found`

GET /v3/file/list

Returns all non-deleted uploads for your account, newest first.

Parameters

No additional parameters beyond authentication.

Example

curl "https://api.veriphone.io/v3/file/list" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "status": "success",
  "uploads": [
    {
      "id": "abc123def456",
      "name": "contacts.csv",
      "status": "completed",
      "filesize": 102400,
      "created": "2026-03-15T10:30:00Z",
      "firstrow": 1,
      "lastrow": 5000,
      "column": 0,
      "position": 5000,
      "stage": "done",
      "speed": 120,
      "billable": 4999,
      "syntaxerr": 50,
      "valid": 4500,
      "invalid": 449,
      "record1": "+14158586273",
      "record2": "+442071234567"
    }
  ]
}

Field	Type	Description
status	string	`new`, `ready`, `verifying`, `completed`, or `deleted`
position	number	Current processing row (tracks progress during verification)
stage	string	Processing stage during verification
speed	number	Processing speed in rows per second
billable	number	Rows that counted against credits
syntaxerr	number	Rows with phone number syntax errors (not billed)
valid	number	Valid phone numbers found
invalid	number	Invalid phone numbers found

GET /v3/file/get

Returns details for a single upload. Same fields as a single entry in the /v3/file/list response.

Parameters

Name	Type		Description
id	string	Required	Upload ID.

Note

Returns an empty object if the file does not exist or is not owned by your account.

GET /v3/file/status

Poll the current status of a bulk verification job.

Parameters

Name	Type		Description
id	string	Required	Upload ID.

Response 200

{
  "id": "abc123def456",
  "status": "completed"
}

Note

Returns an empty status if the file does not exist or is not owned by your account.

GET /v3/file/download

Download the verified results CSV. Returns the verified results if available, otherwise the original uploaded file.

The results file preserves every original column and appends seven result columns: phone_valid, e164, local_number, type, country, region, carrier. Files verified with mode=current append four more: ported, current_carrier, current_line_type and current_lookup — ok when the carrier was resolved, unavailable when a valid number's carrier couldn't be resolved (charged 1 credit, not 10), and empty for rows that weren't valid numbers.

Parameters

Name	Type		Description
id	string	Required	Upload ID.
as	string	Optional	Filename for the download (used in `Content-Disposition` header).

Example

curl -o results.csv "https://api.veriphone.io/v3/file/download?id=abc123def456&as=results.csv" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns binary application/octet-stream with Content-Disposition: attachment.

Errors

Code	Message
404	`File not found`

POST /v3/file/delete

Permanently deletes an uploaded file and its results.

Parameters

Name	Type		Description
id	string	Required	Upload ID.

Response 200

{
  "status": "success"
}

Errors

Code	Message
403	`Access to file is forbidden`
404	`File not found`