# List verification sessions.


Returns a paginated list of verification sessions for the calling service user's organization (X-Org-Id) and environment (X-Environment).

Endpoint: GET /b2b/v1/verification-sessions
Version: 2.0.0
Security: BearerAuth

## Security:

  - `BearerAuth` (unknown)
    http bearer JWT

## Query parameters:

  - `limit` (integer)
    Maximum number of results to return (1-100, default 20).

  - `offset` (integer)
    Number of results to skip for pagination.

  - `status` (string)
    Filter by session status: pending, success, failed, expired.

  - `credential_definition_id` (string)
    Filter by credential definition ID (UUID): sessions created from that definition.

  - `case_id` (string)
    Filter by verification case ID (UUID): sessions your organization launched from that case, your own or another organization's.

## Header parameters:

  - `X-Org-Id` (string, required)
    Organization the call is acting on. The authenticated service user must be a member of this organization in DeepAdmin; otherwise the request returns 404.

  - `X-Environment` (string, required)
    Environment the call is scoped to. Resources are isolated per environment.

## Response 200:

  - `200` (unknown)
    Success response

## Response 200 fields (application/json):

  - `counts` (object, required)
    SessionStatusCounts mirrors the filter tabs on the verification page — one tenant-wide count per status, plus a grand `All` total.

  - `counts.all` (integer, required)

  - `counts.expired` (integer, required)

  - `counts.failed` (integer, required)

  - `counts.pending` (integer, required)

  - `counts.success` (integer, required)

  - `sessions` (array, required)
    Page of sessions matching the list filters.

  - `sessions.accepted_issuer_dids` (array)
    The issuer DIDs this session trusted: those pinned on its credential definitions in its environment, every accepted credential's together. A credential from any other issuer is refused.

  - `sessions.attributes` (object)
    On success: the disclosed values keyed by attribute id — the case's attribute ids, the same keys whichever accepted credential the holder presented, or the claim keys on a credential-definition session. Absent for sessions of cases launched before attributes existed.

  - `sessions.attributes_withheld` (boolean)
    True when the session has disclosed values that this read leaves out: a session created with `redirect_uri` returns `attributes` only to GET /b2b/v1/verification-sessions/{sessionId} with the `response_code` the wallet's redirect carried, and never in the list.

  - `sessions.case` (object)
    The verification case this session ran, only on a session launched from a case (POST /b2b/v1/verification-cases/{caseId}/sessions). Exactly one of `case` and `credential_definition` is present.

  - `sessions.case.id` (string, required)
    Case id: read it at GET /b2b/v1/verification-cases/{caseId}. UUID v4 identifier.
    Example: 550e8400-e29b-41d4-a716-446655440000

  - `sessions.case.title` (array)
    The case's localised headline for the verification screen, if it has one.

  - `sessions.case.title.locale` (string, required)
    Language of the text: "de", "fr", "it" or "en".

  - `sessions.case.title.name` (string, required)
    The text in this language.

  - `sessions.case.version` (integer)
    The case's contract version this session ran. Absent on a session launched before cases carried versions.

  - `sessions.completed_at` (string)
    Set when the session leaves pending (success, failed, or expired).

  - `sessions.created_at` (string, required)
    When the session was created (RFC3339).

  - `sessions.credential_definition` (object)
    The credential definition this session verifies, only on a session created from one (POST /b2b/v1/verification-sessions). Exactly one of `case` and `credential_definition` is present.

  - `sessions.credential_definition.has_logo` (boolean, required)
    Whether the credential definition currently has an uploaded logo.

  - `sessions.credential_definition.id` (string, required)
    Credential definition UUID. UUID v4 identifier.
    Example: 550e8400-e29b-41d4-a716-446655440000

  - `sessions.credential_definition.name` (string, required)
    Human-readable credential definition name.

  - `sessions.credential_status` (string)
    On success: the token-status-list state of the credential the holder presented — "valid", "suspended" (shown as "Locked" in the portal), or "revoked". Resolved when the holder presented and never recomputed.
A "suspended" or "revoked" value still accompanies a successful verification with its disclosed claims: the wallet can present such a credential and the holder can consent to sharing it, so the verifier is given the state and applies its own policy. Branch on this in addition to `status` if a locked credential should not be accepted.

  - `sessions.deeplink` (string)
    Only when status is pending: wallet deep link (e.g. openid4vp://...).

  - `sessions.environment` (string, required)
    Swiyu environment: "beta" or "production" (matches the credential binding).

  - `sessions.error_code` (string)
    Machine-readable failure reason when status is failed or expired: one of the session error codes listed in the Verification Flow guide ("Session error_code values"), each with whether launching a new session can succeed. A wallet's own error is mapped onto that vocabulary (presentation_declined, request_rejected_by_wallet, wallet_error); the raw OAuth code is never exposed.

  - `sessions.error_description` (string)
    Human-readable error detail when status is failed or expired, written by the platform for the code. On attribute_value_rejected it is one fixed sentence that names neither the attribute nor the value: which rule failed is what the case gates on.

  - `sessions.expires_at` (string, required)
    When a pending session expires if not completed (RFC3339).

  - `sessions.issuer_trust` (object)
    On success: on what basis the presented credential's issuer was accepted. `method` is "trusted_authority" when the issuer is one of `accepted_issuer_dids`, or "trust_protocol_2" when the session pins none (Sandbox only) and the swiyu trust registry vouches for the issuer; the other fields are that registry's trust marks.

  - `sessions.issuer_trust.compliant_actor` (boolean, required)
    trust_protocol_2 only: the issuer is not on the non-compliance list.

  - `sessions.issuer_trust.governed_use_case` (boolean, required)
    trust_protocol_2 only: the credential type is one only authorized issuers may issue.

  - `sessions.issuer_trust.governed_use_case_authorization` (boolean, required)
    trust_protocol_2 only: the issuer is authorized to issue it.

  - `sessions.issuer_trust.identity` (boolean, required)
    trust_protocol_2 only: the registry holds a valid identity trust statement for the issuer.

  - `sessions.issuer_trust.method` (string, required)
    "trusted_authority" or "trust_protocol_2".

  - `sessions.presented_credential_definition_id` (string)
    On success: the credential definition of the credential the holder actually presented, one of the case's `credential_definition_ids`. On a credential-definition session it is `credential_definition.id`.
    Example: 550e8400-e29b-41d4-a716-446655440000

  - `sessions.purpose` (string)
    Purpose string from the create request, if any.

  - `sessions.qr_content_base64` (string)
    Only when status is pending: Base64 PNG QR code for the wallet.

  - `sessions.redirect_uri` (string)
    The same-device redirect the session was created with, if any.

  - `sessions.reference_id` (string)
    Your reference_id from the create request, if any.

  - `sessions.requested_attributes` (array)
    The attributes this session asked for, as launched: the case's, or the definition's claims on a direct session. Bindings are keyed by credential definition id, as on the case.

  - `sessions.requested_attributes.bindings` (object)
    The claim this attribute read in each accepted credential, keyed by credential definition id.

  - `sessions.requested_attributes.constraints` (object)
    What the verifier checked a presented value against, if anything.

  - `sessions.requested_attributes.constraints.max` (any)
    Inclusive upper bound, in the same forms as `min`. `today-18y` as `max` of a birth date means at least 18 years old.

  - `sessions.requested_attributes.constraints.min` (any)
    Inclusive lower bound: a number, or for a date an ISO date (`2000-01-01`) or a date relative to the day of verification (`today`, `today-18y`, `today+30d`, `today-6m`).

  - `sessions.requested_attributes.constraints.values` (array)
    Allowed values: strings for string and enum attributes, booleans for a boolean attribute.

  - `sessions.requested_attributes.id` (string, required)
    The attribute's id: the key of its value in the session's `attributes`.

  - `sessions.requested_attributes.label` (string)
    Display name of the attribute, for your staff. Absent: the bound claim's label is shown.

  - `sessions.requested_attributes.sensitive` (boolean, required)
    True when a bound claim is marked sensitive in its credential definition.

  - `sessions.requested_attributes.value_type` (string, required)
    Value type of the attribute ("string", "integer", "number", "boolean", "date", "enum", "image/jpeg").

  - `sessions.session_id` (string, required)
    Session id (matches the value returned at creation time). UUID v4 identifier.
    Example: 550e8400-e29b-41d4-a716-446655440000

  - `sessions.status` (string, required)
    Current lifecycle state of the session.
    Enum: "pending", "success", "failed", "expired"

  - `total` (integer, required)
    Total count matching filters (for pagination UI).

## Response 400:

  - `400` (unknown)
    Invalid request. Common causes: missing or malformed X-Org-Id / X-Environment headers, or a missing required field in the request body.

## Response 400 fields (application/json):

  - `code` (string, required)
    Machine-readable error code.

  - `message` (string, required)
    Human-readable error description.

  - `details` (object)
    Optional structured data with additional context.

## Response 401:

  - `401` (unknown)
    Unauthenticated. The Bearer token failed validation (signature, issuer, audience, or expiry).

## Response 401 fields (application/json):

  - `code` (string, required)
    Machine-readable error code.

  - `message` (string, required)
    Human-readable error description.

  - `details` (object)
    Optional structured data with additional context.

## Response 403:

  - `403` (unknown)
    Permission denied. The token does not carry the scope required by this endpoint. Check the `scope` claim on the token you received from the DeepCloud SSO token endpoint.

## Response 403 fields (application/json):

  - `code` (string, required)
    Machine-readable error code.

  - `message` (string, required)
    Human-readable error description.

  - `details` (object)
    Optional structured data with additional context.

## Response 429:

  - `429` (unknown)
    Rate limit exceeded.

## Response 429 fields (application/json):

  - `code` (string, required)
    Machine-readable error code.

  - `message` (string, required)
    Human-readable error description.

  - `details` (object)
    Optional structured data with additional context.

## Response 500:

  - `500` (unknown)
    Internal server error.

## Response 500 fields (application/json):

  - `code` (string, required)
    Machine-readable error code.

  - `message` (string, required)
    Human-readable error description.

  - `details` (object)
    Optional structured data with additional context.