Verification Flow

This guide explains the full lifecycle of an identity verification session — from creation to result retrieval.

• An API credential with the deepcredentials.verify scope. See Authentication.
• A credential definition configured in your organization.

Open in API reference →

curl -i -X POST \
  https://api.dev.deepcredentials.swiss/b2b/v1/verification-sessions \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: beta' \
  -H 'X-Org-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -d '{
    "allowed_issuer_dids": [
      "string"
    ],
    "case_id": "c74269e5-1f97-4e20-9164-ffbe3494d8d6",
    "claims": [
      "string"
    ],
    "credential_definition_id": "631a1b36-dbe6-4899-b427-3167b0844238",
    "purpose": "string",
    "reference_id": "string"
  }'

You have two options to present the verification request to the user:

The qr_content_base64 field is a standard Base64-encoded PNG image. Display it directly:

<img src="data:image/png;base64,iVBORw0KGgo..." alt="Scan to verify your identity" />

Or decode it to a file:

import base64

png_bytes = base64.b64decode(qr_content_base64)
with open("qr.png", "wb") as f:
    f.write(png_bytes)

The deeplink field contains a URI that opens the wallet app directly:

swiyu-verify://?client_id=...&request_uri=...

Use this when the user is on a mobile device — redirect them to the deeplink instead of showing a QR code.

Poll GET /b2b/v1/verification-sessions/{sessionId} until the status is no longer pending:

Open in API reference →

curl -i -X GET \
  'https://api.dev.deepcredentials.swiss/b2b/v1/verification-sessions/{sessionId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-Environment: beta' \
  -H 'X-Org-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

While status is pending, only session_id, qr_content_base64, deeplink, status, and expires_at are populated. On success, credential_subject_data contains the disclosed claims and qr_content_base64/deeplink are omitted. Sessions created with the deprecated credential_definition_id plus claims shape populate credential_subject_types from the definition. Case-based sessions currently return an empty object instead, so do not use that field to infer types in the preferred flow.

On success, credential_status reports the token-status-list state of the credential the holder actually presented. Values: valid, suspended, or revoked.

Polling recommendations:

• Poll every 2–3 seconds.
• Stop when status is success, failed, or expired.
• Respect the expires_at timestamp — stop polling after expiration.

For production integrations, opt in to the Verification Completed webhook event. Its data field is a slim terminal hint containing session_id, status, and, on successful status resolution, credential_status. Follow it with authenticated GET /b2b/v1/verification-sessions/{sessionId} to reconcile the authoritative session and read disclosed fields. The callback is not a copy of the GET response.

See the Webhooks guide for setup, signature verification, and secret rotation.

On failure: the same response object is returned with status: failed and error_code/error_description populated. See the full schema above.

On a status-check failure: if the credential's token-status-list entry can't be fetched or its signature can't be verified, the session fails with error_code: status_check_failed rather than being reported with an unknown or stale state. credential_status is absent on such a session.

On expiration:

Sessions that remain pending past their expires_at transition to expired automatically.

See Error Handling for a complete list of error codes.

• Webhooks — Receive verification results in real time.
• Error Handling — Handle all possible error scenarios.