Batch KYC at Scale

Backfill or onboard 1000 users asynchronously with the Batch API instead of single requests.

• Build a batch file of 1000 Helios verification requests
• Submit to the Batch API for async processing at 50 percent discount
• Poll the batch job and download per-request results

Time to complete: ~15 minutes

Prerequisites

• SAGEA_API_KEY set in your environment as Bearer auth.
• Read Send your first API request to create a key.
• Read How Helios works to understand decisions and score thresholds.
• A CSV or database mapping external_id values to hosted file URLs or pre-encoded media.

Step 1: Build a batch file of 1000 verifications

Each entry targets /helios/kyc/v1. Use hosted URLs your pipeline can resolve; keep external_id unique per user.

head -n 2 users.csv
wc -l batch_requests.jsonl

# build_batch.py
import csv, json
with open("users.csv") as f, open("batch_requests.jsonl", "w") as out:
    for row in csv.DictReader(f):
        out.write(json.dumps({
            "external_id": row["external_id"],
            "front_image_url": row["front_url"],
            "back_image_url": row["back_url"],
            "liveness_video_url": row["video_url"],
        }) + "\n")
print("wrote batch_requests.jsonl")

Validate that the file has 1000 lines and every row has a unique external_id before submitting.

Step 2: Submit the batch job

POST https://api.sagea.space/v1/batch with endpoint set to /helios/kyc/v1 processes the whole file asynchronously at 50 percent discount versus sync calls.

curl -X POST https://api.sagea.space/v1/batch \
  -H "Authorization: Bearer $SAGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "/helios/kyc/v1",
    "requests": []
  }'

Save the returned batch_id. Batch jobs run offline and cost half the sync rate, ideal for migrations and nightly backfills.

Step 3: Poll and download results

Poll the batch job, then fetch per-verification decisions and route review cases to analysts.

BATCH_ID=$(cat batch_id.txt)
curl https://api.sagea.space/v1/batch/$BATCH_ID \
  -H "Authorization: Bearer $SAGEA_API_KEY"

Each result line uses the standard schema with verification_id, decision, scores, reasons, and extracted fields.

Verify

A successful submit returns HTTP 200 with a batch_id. Poll until completed, then confirm 1000 result lines. If it fails, check below.

What's next

• Review queue and webhooks
• Step-up re-authentication
• How Helios works