Skip to main content

Batch Screening

Screen hundreds or thousands of subjects in a single request. Batch screening processes subjects asynchronously and delivers results via webhook.

Create a Batch​

curl -X POST https://api.korastratum.com/api/v1/screenings/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "PERIODIC",
    "callback_url": "https://your-server.com/webhooks/batch",
    "checks": ["SANCTIONS", "PEP"],
    "subjects": [
      {
        "external_id": "cust_001",
        "type": "INDIVIDUAL",
        "name": "John Doe",
        "date_of_birth": "1990-01-15",
        "nationality": "US"
      },
      {
        "external_id": "cust_002",
        "type": "INDIVIDUAL",
        "name": "Jane Smith",
        "date_of_birth": "1985-03-20",
        "nationality": "GB"
      },
      {
        "external_id": "cust_003",
        "type": "ENTITY",
        "name": "Acme Corp",
        "country": "US"
      }
    ]
  }'

Response (HTTP 202):

{
  "batch_id": "bat_abc123",
  "status": "PROCESSING",
  "total_subjects": 3,
  "created_at": "2025-06-01T12:00:00Z"
}

Check Batch Status​

Poll the batch endpoint to monitor progress:

curl https://api.korastratum.com/api/v1/screenings/batch/bat_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

Response:

{
  "batch_id": "bat_abc123",
  "status": "COMPLETED",
  "total_subjects": 3,
  "completed": 3,
  "failed": 0,
  "summary": {
    "approve": 2,
    "review_required": 1,
    "block": 0
  },
  "screenings": [
    {
      "screening_id": "scr_001",
      "external_id": "cust_001",
      "status": "COMPLETED",
      "risk_score": 120,
      "risk_band": "LOW",
      "decision": {"outcome": "APPROVE"}
    },
    {
      "screening_id": "scr_002",
      "external_id": "cust_002",
      "status": "COMPLETED",
      "risk_score": 450,
      "risk_band": "MEDIUM",
      "decision": {"outcome": "REVIEW_REQUIRED"}
    },
    {
      "screening_id": "scr_003",
      "external_id": "cust_003",
      "status": "COMPLETED",
      "risk_score": 80,
      "risk_band": "LOW",
      "decision": {"outcome": "APPROVE"}
    }
  ],
  "created_at": "2025-06-01T12:00:00Z",
  "completed_at": "2025-06-01T12:02:30Z"
}

Webhook Notification​

When the batch completes, a batch.completed webhook is sent:

{
  "event": "batch.completed",
  "timestamp": "2025-06-01T12:02:30Z",
  "data": {
    "batch_id": "bat_abc123",
    "total_subjects": 3,
    "completed": 3,
    "failed": 0,
    "summary": {
      "approve": 2,
      "review_required": 1,
      "block": 0
    }
  }
}

Individual screening.completed events are also sent for each subject as they finish.

Scheduled Rescreening (Coming Soon)​

Coming Soon

The POST /v1/screenings/reschedule endpoint is not yet available. Scheduled rescreening functionality is planned for a future release. In the meantime, you can achieve periodic rescreening by creating new batch screening requests on a schedule.

Best Practices​

  • Use external_id — Map each subject to your internal customer ID for easy correlation
  • Limit batch size — Keep batches under 1,000 subjects for optimal processing time
  • Use webhooks — Don't poll continuously; wait for batch.completed events
  • Stagger large rescreens — For 10,000+ customers, split into multiple batches
  • Set purpose correctly — Use BATCH for bulk operations, PERIODIC for scheduled rescreens