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 receive a job_id back immediately. The server processes images 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. Each file field must be named images and accompanied by a matching external_ids[] value that identifies the person in your system.

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=@alice.jpg
images=@bob.jpg
external_ids[]=employee-001
external_ids[]=employee-002

Response: 202 Accepted

{
  "success": true,
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued",
    "total": 2,
    "processed": 0,
    "succeeded": 0,
    "failed": 0
  }
}

Poll for job status

Use the job_id to poll until status is done or failed.

GET /api/v1/organizations/{org_id}/batch/{job_id}
Authorization: Bearer <jwt-token>

{
  "success": true,
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "done",
    "total": 2,
    "processed": 2,
    "succeeded": 2,
    "failed": 0,
    "results": [
      { "index": 0, "external_id": "employee-001", "face_id": "abc123", "success": true },
      { "index": 1, "external_id": "employee-002", "face_id": "def456", "success": true }
    ]
  }
}

Job status values

List all batch jobs

GET /api/v1/organizations/{org_id}/batch
Authorization: Bearer <jwt-token>

Limits

• Maximum 100 images per job.
• Individual items that fail (bad image, face not detected) do not fail the whole job. Check results[].success per item.
• Jobs are retained for 7 days after completion.

Polling strategy (example)

async function waitForJob(orgId, jobId, token) {
  const interval = 2000 // poll every 2 seconds
  while (true) {
    const res = await fetch(
      `https://api.example.com/api/v1/organizations/${orgId}/batch/${jobId}`,
      { headers: { Authorization: `Bearer ${token}` } }
    )
    const { data } = await res.json()
    if (data.status === 'done' || data.status === 'failed') {
      return data
    }
    await new Promise(r => setTimeout(r, interval))
  }
}