# Launch a verification case.


Starts a verification session from a verification case: your organization's own, or any other organization's, by its id. The case is the contract: the session asks for every attribute of the case, with its constraints, as authored. The session runs in X-Environment, which must be one of the case's `environments` (otherwise 400 case_not_available). Returns a QR code and deeplink; poll GET /b2b/v1/verification-sessions/{sessionId} or subscribe to the "verification.completed" webhook. Requires the deepcredentials.verify scope.

Endpoint: POST /b2b/v1/verification-cases/{caseId}/sessions
Version: 1.0.0
Security: BearerAuth

## Security:

  - `BearerAuth` (unknown)
    http bearer JWT

## Path parameters:

  - `caseId` (string, required)

## 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.

## Request fields (application/json):

  - `case_version` (integer)
    Pins the contract version your integration was built against. The current version runs; an older one runs while the owner keeps it in the case's launchable_versions (a migration window). Any other version is refused with 409 case_version_mismatch. Omitted: the current version.

  - `purpose` (string)
    Optional text shown in wallet/consent context where supported; replaces the case's purpose for this run.

  - `redirect_uri` (string)
    Optional same-device return: where the wallet sends the holder after they answer, with a fresh `response_code` query parameter. Absolute https, no fragment, no `response_code` of its own. A session created with it returns its `attributes` only to a read that passes that code. See the Same-Device Flow guide.

  - `reference_id` (string)
    Optional correlation identifier from your system; echoed on the resource.

## Response 200:

  - `200` (unknown)
    Success response

## Response 200 fields (application/json):

  - `deeplink` (string, required)
    Wallet app link, e.g. openid4vp://?client_id=...&request_uri=...

  - `expires_at` (string, required)
    Session TTL deadline (RFC3339).

  - `qr_content_base64` (string, required)
    Base64-encoded PNG; QR payload is the same URI as deeplink.

  - `session_id` (string, required)
    UUID v4 identifier.
    Example: 550e8400-e29b-41d4-a716-446655440000

  - `status` (string, required)
    Lifecycle state of a verification session.
    Enum: "pending", "success", "failed", "expired"

## Response 400:

  - `400` (unknown)
    Invalid request. Either the body or headers were malformed (`invalid_argument`), or the case cannot run as asked (`failed_precondition`): it does not run in `X-Environment` because a credential it accepts is not enabled there (message prefix `case_not_available:`, `details` naming the environment and the missing definitions by `id` and `name`, whoever's case it is), or the date bounds of one of its attributes have crossed since it was saved (the message names the attribute).

## 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 404:

  - `404` (unknown)
    Resource not found. Either the resource ID is unknown, or the X-Org-Id you supplied is not an organization the authenticated service user is a member of.

## Response 404 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 409:

  - `409` (unknown)
    Conflict: `case_version` pins a version that is neither the case's current one nor listed in its `launchable_versions` (`aborted`, message prefix `case_version_mismatch:`).

## Response 409 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.

## Response 400 examples:

  - `Malformed request` (unknown)

  - `The case does not run in X-Environment` (unknown)

## Response 409 examples:

  - `case_version is neither current nor launchable` (unknown)