Batch Issuing Credentials

Overview

The batch-issue endpoint accepts up to 10,000 credentials in a single call and processes them asynchronously. You get a job_id back immediately; the credentials are issued in the background by a worker Lambda, and you poll job status or subscribe to a webhook stream to find out when the batch is done. Use it for:

One-time backfills when you’ve already KYB-verified a set of businesses out-of-band.
CLI-driven uploads where an operator pastes a JSON file with thousands of records.
Periodic syncs from an internal system that issues credentials nightly.

For low-volume, interactive issuance (≤ 10 credentials), call POST /v1/credentials directly per credential — it’s faster and synchronous.

Prerequisites

A Beltic API key with credentials:write permission
A JSON array of credential payloads (each one a valid POST /v1/credentials body)

Step 1: Submit the Batch

curl -X POST https://api.beltic.com/v1/credentials/batch-issue \
  -H "X-Api-Key: $BELTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": [
      {
        "credential_type": "business",
        "subject": { "id": "biz_001", "type": "organisation", "name": "Acme Corp" },
        "claims": { "kyb_status": "approved", "verified_at": "2026-05-20T00:00:00Z", "jurisdiction": "US-DE" }
      },
      {
        "credential_type": "business",
        "subject": { "id": "biz_002", "type": "organisation", "name": "Widget Co" },
        "claims": { "kyb_status": "approved", "verified_at": "2026-05-20T00:00:00Z", "jurisdiction": "US-NY" }
      }
    ]
  }'

Response

{
  "job_id": "job_01HQ7Q...",
  "status": "queued",
  "total": 2,
  "processed": 0,
  "succeeded": 0,
  "failed": 0,
  "created_at": "2026-05-21T16:00:00Z"
}

The batch is accepted and queued. The HTTP response returns within ~200ms; actual issuance happens in the background.

Step 2: Poll for Status (or use webhooks)

Poll the same job_id endpoint to check progress:

curl "https://api.beltic.com/v1/credentials/batch-issue/$JOB_ID" \
  -H "X-Api-Key: $BELTIC_API_KEY"

{
  "job_id": "job_01HQ7Q...",
  "status": "completed",
  "total": 2,
  "processed": 2,
  "succeeded": 2,
  "failed": 0,
  "credential_ids": [
    "cred_01HQ7R...",
    "cred_01HQ7S..."
  ],
  "started_at": "2026-05-21T16:00:01Z",
  "completed_at": "2026-05-21T16:00:08Z"
}

Status progression: queued → processing → completed (or failed if every item errored).

Webhook Alternative

For long-running batches you don’t want to poll, create a webhook stream that fires on credential.batch_completed:

curl -X POST https://api.beltic.com/v1/audit/streams \
  -H "X-Api-Key: $BELTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks/beltic",
    "actions": ["credential.batch_completed", "credential.batch_failed"]
  }'

See the audit-streams endpoint reference for signature verification details.

Partial Failures

A batch is treated as best-effort: if one credential fails validation (e.g. an invalid kyb_status), the rest still issue. The job’s failed count reflects how many didn’t make it; per-item failure details are surfaced in the job response’s errors array:

{
  "job_id": "job_01HQ7Q...",
  "status": "completed",
  "total": 100,
  "processed": 100,
  "succeeded": 97,
  "failed": 3,
  "credential_ids": ["cred_...", "cred_..."],
  "errors": [
    {
      "index": 42,
      "code": "validation_failed",
      "message": "claims.kyb_status: expected 'approved' | 'pending' | 'declined' | 'manual_review', got 'verified'"
    }
  ]
}

The index field is the 0-based position of the failed item in your original credentials array — use it to reconcile with your source data.

Limits

Constraint	Value
Max items per batch	10,000
Max request body size	25 MB
Concurrent batch jobs per org	10
Per-org batch throughput	100 credentials/second sustained

Submitting a 100k-credential backfill? Split it across multiple jobs.

Idempotency

Like single-issue, batch-issue supports the Idempotency-Key header. Use one key per logical batch — re-submitting with the same key within 24 hours returns the original job_id without enqueuing duplicate work.

CLI Usage

The Beltic CLI wraps batch-issue with a progress bar and per-item retry. If you have a JSON file of credential payloads:

beltic credentials batch-issue --file ./credentials.json --wait

The CLI calls POST /v1/credentials/batch-issue, polls for completion, and exits non-zero if any item failed. Pair it with CI/CD to run nightly backfills.

Overview

Workflow API

Credentials API

Document API

Identity API (Legacy)

Batch Issuing Credentials

Overview

Prerequisites

Step 1: Submit the Batch

Response

Step 2: Poll for Status (or use webhooks)

Webhook Alternative

Partial Failures

Limits

Idempotency

CLI Usage

Next Steps

Verify Credentials

Audit Events

​Overview

​Prerequisites

​Step 1: Submit the Batch

​Response

​Step 2: Poll for Status (or use webhooks)

​Webhook Alternative

​Partial Failures

​Limits

​Idempotency

​CLI Usage

​Next Steps

Verify Credentials

Audit Events

Overview

Prerequisites

Step 1: Submit the Batch

Response

Step 2: Poll for Status (or use webhooks)

Webhook Alternative

Partial Failures

Limits

Idempotency

CLI Usage

Next Steps