Developer Docs
Platform guideSign in

Import jobs

What happened to contacts you handed over.

Every contact import runs in the background, so the request that starts it returns a job rather than a result. The job's progress carries counts as it goes (processedRows, successfulRows, failedRows, skippedRows) and errors lists the first ten row errors, so a partial import tells you which rows did not make it and why.

Status moves pending or queued, then running, then completed, failed or cancelled (through cancelling while a running job stops). A job can be cancelled while it is pending, queued or running. Contacts already written stay written: cancelling stops the work, it does not undo it.

List import jobs#

Import jobs into lists in the key's organization that the key can read, newest first.

GET/api/v1/import-jobs

Query parameters

contactListIdstring
Only jobs importing into this list.
statusstring
pending, queued, running, cancelling, completed, failed or cancelled.
pagenumber
Page number.
Default1
pageSizenumber
Jobs per page, up to 50.
Default20

Responses

A page of jobs.

curl -X GET "https://voice.evryhealth.com/api/v1/import-jobs" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response200
{
  "importJobs": [
    {
      "id": "b0a7e4d2-5c3f-4e8a-9b1c-7d6e5f4a3b21",
      "contactListId": "6d1f3c2a-8b4e-4f7a-9c1d-2e5b7a9f0c13",
      "status": "completed",
      "progress": {
        "totalRows": 500,
        "processedRows": 500,
        "successfulRows": 498,
        "failedRows": 2,
        "skippedRows": 0,
        "processingRate": 41.5
      },
      "startedAt": "2026-01-20T10:30:05.000Z",
      "completedAt": "2026-01-20T10:31:02.000Z",
      "errors": [
        {
          "row": 12,
          "field": "phoneNumber",
          "error": "Invalid phone number format"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 1,
    "totalPages": 1
  }
}

Get an import job#

One job, with its progress and, once rows have failed, the first ten errors.

GET/api/v1/import-jobs/{id}

Path parameters

idstringrequired
Import job id.

Responses

The job.

curl -X GET "https://voice.evryhealth.com/api/v1/import-jobs/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response200
{
  "id": "b0a7e4d2-5c3f-4e8a-9b1c-7d6e5f4a3b21",
  "contactListId": "6d1f3c2a-8b4e-4f7a-9c1d-2e5b7a9f0c13",
  "status": "completed",
  "progress": {
    "totalRows": 500,
    "processedRows": 500,
    "successfulRows": 498,
    "failedRows": 2,
    "skippedRows": 0,
    "processingRate": 41.5
  },
  "startedAt": "2026-01-20T10:30:05.000Z",
  "completedAt": "2026-01-20T10:31:02.000Z",
  "errors": [
    {
      "row": 12,
      "field": "phoneNumber",
      "error": "Invalid phone number format"
    }
  ]
}

Cancel an import job#

Stops a job that is pending, queued or running. Contacts already imported remain in the list. A running job finishes stopping in the background.

POST/api/v1/import-jobs/{id}/cancel

Path parameters

idstringrequired
Import job id.

Responses

Cancelled. A running job answers `Import job cancellation requested` and stops shortly after.

curl -X POST "https://voice.evryhealth.com/api/v1/import-jobs/{id}/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response200
{
  "success": true,
  "message": "Import job cancelled successfully"
}