API Reference

Batch Jobs

The Batch Jobs API lets you enroll hundreds of faces in a single asynchronous request. Instead of making one HTTP call per image, you submit a multipart form with up to 100 images and get a job id back immediately. The server enrolls them in the background while you poll for the result.

When to use batch jobs

Initial data migration: importing an existing employee/customer database.
Bulk re-enrollment: replacing low-quality images with better ones.
Nightly sync jobs: syncing a new batch of identities each day.

Submit a batch job

Send a multipart/form-data POST request. Files are numbered: images[0], images[1], and so on. Send an entries field alongside them, a JSON array with one object per image, to give each face its externalId and metadata. Leave entries out and the filename becomes the external ID.

Shell

POST /api/v1/collections/{collection_id}/faces/batch-async
X-API-Key: <your-api-key>
Content-Type: multipart/form-data

# Up to 100 images per request
images[0]=@alice.jpg
images[1]=@bob.jpg
entries=[{"externalId":"employee-001"},
         {"externalId":"employee-002","metadata":{"team":"ops"}}]

Response: 202 Accepted

JSON

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "collectionId": "9f1c2b7e-3d84-4a16-8c55-0b7e2a1d6f30",
    "status": "queued",
    "total": 2,
    "processed": 0,
    "succeeded": 0,
    "failed": 0,
    "createdAt": "2026-09-20T10:05:00Z",
    "updatedAt": "2026-09-20T10:05:00Z"
  }
}

Poll for job status

Poll with the job id until status is done or failed.

Shell

GET /api/v1/collections/{collection_id}/batch/{job_id}
X-API-Key: lxf_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6

JSON

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "collectionId": "9f1c2b7e-3d84-4a16-8c55-0b7e2a1d6f30",
    "status": "done",
    "total": 2,
    "processed": 2,
    "succeeded": 1,
    "failed": 1,
    "results": [
      { "index": 0, "externalId": "employee-001", "faceId": "dc3e7a57-22d5-4271-b707-213e49c8fe54" },
      { "index": 1, "externalId": "employee-002", "error": "no face detected in image" }
    ],
    "createdAt": "2026-09-20T10:05:00Z",
    "updatedAt": "2026-09-20T10:05:14Z"
  }
}

Job status values

Status	Meaning
queued	Job accepted, waiting for a worker.
processing	Worker is actively enrolling faces.
done	All items processed. Check results for per-item outcome.
failed	The job itself could not be started (e.g., invalid collection).

Limits

Maximum 100 images per job.
An item that fails does not fail the job. Each entry in results carries either a faceId or an error, so read it per item rather than trusting the job status alone.
Every image in the batch counts against your quota when the job is accepted, not when it finishes.

Polling strategy (example)

JavaScript

async function waitForJob(collectionId, jobId, apiKey) {
  const interval = 2000 // poll every 2 seconds
  while (true) {
    const res = await fetch(
      `https://api.livexface.com/api/v1/collections/${collectionId}/batch/${jobId}`,
      { headers: { 'X-API-Key': apiKey } }
    )
    const { data } = await res.json()
    if (data.status === 'done' || data.status === 'failed') {
      return data
    }
    await new Promise(r => setTimeout(r, interval))
  }
}