Verify large volumes of phone numbers by uploading a CSV file through the dashboard or API.
The bulk verification process follows this sequence:
Bulk processing runs Static lookups. For the current carrier of individual numbers, use mode=current on the verify endpoint.
/v3/file/upload)/v3/file/verify)/v3/file/status) until processing completes/v3/file/download)Upload a CSV file for bulk verification. Content-Type: multipart/form-data.
| 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). |
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"
{
"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. |
| 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 |
Starts a background job to verify all phone numbers in the uploaded file.
| 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. |
curl -X POST "https://api.veriphone.io/v3/file/verify?id=abc123def456" \ -H "Authorization: Bearer YOUR_API_KEY"
{
"status": "success",
"id": "abc123def456"
}| Code | Message |
|---|---|
| 402 | Insufficient credits |
| 403 | File not ready / Unauthorized file access / Account inactive |
| 404 | File not found |
Returns all non-deleted uploads for your account, newest first.
No additional parameters beyond authentication.
curl "https://api.veriphone.io/v3/file/list" \ -H "Authorization: Bearer YOUR_API_KEY"
{
"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 |
Returns details for a single upload. Same fields as a single entry in the /v3/file/list response.
| Name | Type | Description | |
|---|---|---|---|
| id | string | Required | Upload ID. |
Poll the current status of a bulk verification job.
| Name | Type | Description | |
|---|---|---|---|
| id | string | Required | Upload ID. |
{
"id": "abc123def456",
"status": "completed"
}status if the file does not exist or is not owned by your account.Download the verified results CSV. Returns the verified results if available, otherwise the original uploaded file.
| Name | Type | Description | |
|---|---|---|---|
| id | string | Required | Upload ID. |
| as | string | Optional | Filename for the download (used in Content-Disposition header). |
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.
| Code | Message |
|---|---|
| 404 | File not found |
Permanently deletes an uploaded file and its results.
| Name | Type | Description | |
|---|---|---|---|
| id | string | Required | Upload ID. |
{
"status": "success"
}| Code | Message |
|---|---|
| 403 | Access to file is forbidden |
| 404 | File not found |