Batch Submissions

When you need to score many applications at once — for example, a weekly intake at an agency — use the Batches endpoint. One request submits up to 500 reports, counts as a single rate-limit hit, and fires a webhook when the entire batch finishes.

Create a batch

Each item is identical to the body you would send to POST /v1/reports, plus an optional external_id so you can match results to your internal records.

bash

curl -X POST https://api.heyvisa.com/v1/batches \
  -H "Authorization: Bearer $HEYVISA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://app.example.com/heyvisa/batches",
    "items": [
      {
        "external_id": "client-001",
        "applicant": { "country": "TR", "destination": "DE", "purpose": "tourism" },
        "documents": ["doc_01...", "doc_02..."]
      },
      {
        "external_id": "client-002",
        "applicant": { "country": "TR", "destination": "FR", "purpose": "tourism" },
        "documents": ["doc_03..."]
      }
    ]
  }'

Immediate response

The API allocates report IDs synchronously and queues the analyses.

json

201 Created
{
  "id": "btc_01HXYZbatch",
  "object": "batch",
  "status": "processing",
  "total":    2,
  "completed": 0,
  "failed":    0,
  "items": [
    { "external_id": "client-001", "report_id": "rep_01HXYZ001", "status": "queued" },
    { "external_id": "client-002", "report_id": "rep_01HXYZ002", "status": "queued" }
  ]
}

Async processing

Items are processed in parallel up to your plan's concurrency limit. You will receive one webhook per individual report (as usual) and an additional batch.completed event when the last item finishes.

Polling pattern

If you cannot use webhooks, poll the batch envelope every 5–10 seconds. The completed and failed counters tell you progress; the status field transitions to completed once every item is terminal.

bash

# Poll the batch envelope
curl https://api.heyvisa.com/v1/batches/btc_01HXYZbatch \
  -H "Authorization: Bearer $HEYVISA_API_KEY"

json

{
  "id": "btc_01HXYZbatch",
  "status": "completed",
  "total":     2,
  "completed": 2,
  "failed":    0,
  "items": [
    { "external_id": "client-001", "report_id": "rep_01HXYZ001", "status": "completed", "risk_score": 78 },
    { "external_id": "client-002", "report_id": "rep_01HXYZ002", "status": "completed", "risk_score": 64 }
  ]
}

Limits

Maximum 500 items per batch. For higher volumes, submit multiple batches back-to-back; the batch endpoint itself is not throttled beyond your standard request rate limit.