Verification Flow

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

• A service-user access token requested with the deepcredentials.verify scope (and deepcredentials.verification-cases to author cases). See Authentication.
• Something to verify against — one of two:
  • A credential definition: one of your organization's own, an official one such as the Beta-ID, or any other organization's whose id you were given (a definition id is not a secret: it is the vct of every credential of its type). GET /b2b/v1/credential-definitions lists your own and the official ones; a definition another organization lists in the catalogue (is_listed) shows in the portal's pickers, and any definition reads by id with GET /b2b/v1/credential-definitions/{credentialDefinitionId}.
  • A verification case: a rule authored in the portal or by your integration, possibly accepting several credential types and constraining values. GET /b2b/v1/verification-cases lists your own; any organization's case is read and launched by its id. See Verification Cases.

The rule is short:

• Verify a credential definition when one credential type is enough and any value the holder presents is fine. You pick the claims per session; the disclosed values come back under the claim keys.
• Use a verification case when the check accepts more than one credential type, or when a value must meet a constraint (an allowed set, a bound, an age). A case is the only place either is expressed: a definition session takes no constraints and one definition.

A case also gives you attribute ids that stay the same whichever credential was presented, a holder-facing title and purpose, versions, and one rule that several integrations or organizations run alike — useful, but not what decides.

Whose it is does not decide either. Any organization's credential definition or verification case is used by its id: if it is not yours, ask its owner for the id (it is not a secret — a definition id is the vct of every credential of its type, a case id is in every QR code the case produces). What you cannot do with someone else's is issue from the definition or change the case.

There are two ways to start a session, each with its own endpoint: verify a credential definition (POST /b2b/v1/verification-sessions) or launch a verification case (POST /b2b/v1/verification-cases/{caseId}/sessions). Either way the session is the same resource: polled with GET /b2b/v1/verification-sessions/{sessionId} and reported by the same webhook. What it ran is named on the session, under credential_definition or case, never both. Neither path takes an issuer list: a session trusts the issuers pinned on its credential definitions in X-Environment, reported in accepted_issuer_dids. Both take an optional redirect_uri, which brings a holder on their phone back to you after they answer; see Same-Device Return.

Ask the holder for one credential of a given definition. claims picks the claims to request; omit it (or send it empty) to ask for every claim of the definition.

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 '{
    "claims": [
      "string"
    ],
    "credential_definition_id": "631a1b36-dbe6-4899-b427-3167b0844238",
    "purpose": "string",
    "redirect_uri": "string",
    "reference_id": "string"
  }'

The session names the definition under credential_definition (id, name, has_logo). On success, attributes is keyed by the claim keys of the definition, and presented_credential_definition_id is the definition's id.

Launch a case by its id, your own or any other organization's. The case is the contract: the session asks for every attribute of the case, with its constraints, exactly as authored; there is no per-session narrowing. purpose is optional and replaces the case's purpose for this run; case_version pins the contract version your integration was built against: the current one runs, an older one runs while the case lists it in launchable_versions, anything else is 409 case_version_mismatch (see Versions). The case must run in X-Environment (400 case_not_available otherwise). The session names the case under case (id, the version it ran, the case's title). On success, attributes is keyed by the case's attribute ids, whichever accepted credential the holder presented, and presented_credential_definition_id says which of the case's credential_definition_ids it was; a value that fails a constraint closes the session as failed with attribute_value_rejected and nothing disclosed is stored. See Verification Cases for what a case is and how to author one.

Open in API reference →

curl -i -X POST \
  'https://api.dev.deepcredentials.swiss/b2b/v1/verification-cases/{caseId}/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 '{
    "case_version": 1,
    "reference_id": "door-7B-2026-09-29-0815",
    "purpose": "Access to the server room"
  }'

Both endpoints answer with the launch: the session id, the QR code, the deeplink, the status and the expiry.

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 (its scheme, openid4vp or swiyu-verify, depends on the deployment):

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. To have the wallet bring them back to you once they have answered, create the session with redirect_uri: see Same-Device Return.

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}?response_code=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-Environment: beta' \
  -H 'X-Org-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

A session reads the same whichever way it was launched. What it ran is under case (id, version, title) on a session launched from a case, or credential_definition (id, name, has_logo) on a session created for a definition: exactly one of the two is present. GET /b2b/v1/verification-sessions?case_id=… lists the sessions your organization launched from one case, your own or another organization's.

While status is pending, the response carries qr_content_base64 and deeplink next to what the session asked for, and no disclosed data. On success, attributes holds the disclosed values keyed by attribute id — on a case session the case's attribute ids, the same keys whichever accepted credential the holder presented; on a credential-definition session the claim keys — and presented_credential_definition_id names the credential definition of the credential the holder actually presented (one of the case's credential_definition_ids; on a credential-definition session, credential_definition.id); qr_content_base64/deeplink are omitted. requested_attributes echoes what the session asked for, each with its value_type, sensitive and constraints, and its bindings keyed by credential definition id exactly as on the case (on a credential-definition session, the one definition's id). A session reads the same whichever organization's case it ran (see Whose case).

A value that fails one of an attribute's constraints (values, or min/max) fails the session with error_code: "attribute_value_rejected" and the fixed error_description described in Verification Cases. The constraint is enforced by the verifier after the wallet's response, so treat it as authoritative and attributes as already checked.

A session created with redirect_uri returns attributes only to a read that passes the response_code the wallet's redirect carried; without it, attributes is left out and attributes_withheld is true, and the list never carries them. See Same-Device Return.

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. error_code is always one of the values below, and error_description is written by the platform for that code: what the holder's wallet said is never passed through.

The wallet reports the holder's side of the exchange with the OpenID4VP error codes, and the platform folds them into this vocabulary before the session is stored: access_denied becomes presentation_declined, a refusal of the request itself becomes request_rejected_by_wallet, and anything else wallet_error. Branch on error_code; the third column says whether launching a new session for the same holder can succeed, all else being equal.

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.

• Same-Device Return — Bring a holder on their phone back to you, and bind the result to their browser.
• Webhooks — Receive verification results in real time.
• Error Handling — Handle all possible error scenarios.