Async jobs

Most BankID and Persondata endpoints accept ?async=true (or X-Async: true header). Instead of running the upstream call inline, Cerrtify enqueues it and returns immediately.

Enqueue

POST /service/bankid/auth?async=true
X-API-Key: cert_...
Content-Type: application/json

{ "endUserIp": "192.168.0.1" }

Response:

{
  "job_id": "job_01H8X...",
  "status": "queued",
  "poll": "/service/jobs/job_01H8X..."
}

HTTP status is 202 Accepted.

Poll

GET /service/jobs/job_01H8X...
X-API-Key: cert_...

Response while pending:

{ "id": "job_01H8X...", "type": "bankid:auth", "status": "running", "attempts": 1, "max_attempts": 3 }

Response when terminal:

{
  "id": "job_01H8X...",
  "type": "bankid:auth",
  "status": "done",
  "result": { "orderRef": "...", "qrStartToken": "...", "qrStartSecret": "..." },
  "attempts": 1,
  "enqueued_at": "2026-07-01T08:31:02Z",
  "finished_at": "2026-07-01T08:31:14Z",
  "expires_at": "2026-07-08T08:31:02Z"
}

status is one of queued, running, done, failed, cancelled. On failed, look at error_code and error_message. Jobs and their results are pruned after expires_at (7 days).

Which endpoints support async?

All BankID order endpoints (/auth, /sign, /collect, /cancel, /phone/auth, /phone/sign) and the raw-XML Persondata search endpoints. Payment endpoints (/payment, /other/payment) and the .json Persondata variants are synchronous only.

When to use it

• The caller can't wait the full upstream latency (e.g. mobile clients on poor networks).
• You need durable retry on transient upstream failures — Cerrtify retries upstream errors automatically.
• You want a single job_id that's safe to surface in your UI and resume after a page reload.