> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopae.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Verification Status

> Retrieve the status and timing of a verification session. No personal attributes are returned.

Retrieves the current status of a verification session. Poll this endpoint until the status is terminal, then call [Get Verification UserInfo](/v2/api-reference/verifications/get-verification-userinfo) to read the result.

## Headers

<ParamField header="Authorization" type="string" required>
  `Basic <base64(appId:appSecret)>`. See [Authentication](/v2/api-reference/authentication).
</ParamField>

## Path Parameters

<ParamField path="verificationId" type="string" required>
  The session id returned by [Create Verification](/v2/api-reference/verifications/create-verification).
</ParamField>

## Response

<ResponseField name="verificationId" type="string">
  The session id.
</ResponseField>

<ResponseField name="status" type="string">
  `awaiting_user_action`, `authenticating`, `completed`, `failed`, or `cancelled`. `processing` is reserved and not currently returned. You do not receive `expired`: an unfinished verification is deleted at `expiresAt`, and this endpoint then returns `404`. See [Expiry](/v2/guides/verifications/verification-flow#expiry).
</ResponseField>

<ResponseField name="providerId" type="string">
  The catalog provider id (for example `smart-id`, `freja`, `google-wallet`), the same value [Create Verification](/v2/api-reference/verifications/create-verification) returned.
</ResponseField>

<ResponseField name="workflowId" type="string">
  The workflow that governed the session: the one you passed, or the app's default.
</ResponseField>

<ResponseField name="flowType" type="string">
  `qr`, `redirect`, `push`, `dc`, or `query`. A `query` session is already terminal at creation. Reading it again returns the stored result.
</ResponseField>

<ResponseField name="flowDetails" type="object">
  The same flow details returned at creation, while the session is still waiting for the user.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 creation time.
</ResponseField>

<ResponseField name="expiresAt" type="string">
  ISO 8601 expiry time, 30 minutes after creation. If the verification has not finished by then, it has expired and is deleted.
</ResponseField>

<ResponseField name="verifiedAt" type="string">
  ISO 8601 completion time. Present when `status` is `completed`.
</ResponseField>

<ResponseField name="failedAt" type="string">
  Present when `status` is `failed`.
</ResponseField>

<ResponseField name="cancelledAt" type="string">
  Present when `status` is `cancelled`.
</ResponseField>

<ResponseField name="error" type="object">
  Present when `status` is `failed`. Carries `type`, `code` (for example `user_cancelled`, `loa_insufficient`), `message`, and optionally `providerError` with the provider's own code.
</ResponseField>

<ResponseField name="acr" type="string">
  Authentication Context Class Reference, present when the provider asserted a LoA explicitly.
</ResponseField>

<ResponseField name="hopae_loa" type="number">
  Numeric [Level of Assurance](/v2/guides/verifications/assurance), 1 to 5.
</ResponseField>

<ResponseField name="hopae_loa_label" type="string">
  Human-readable LoA label (for example `substantial`).
</ResponseField>

<ResponseField name="connectionInstanceId" type="string">
  The activated connection instance the session runs on (`conn_…`).
</ResponseField>

<ResponseField name="connectionId" type="string">
  The catalog connection id, for example `google-wallet-us-mdl`.
</ResponseField>

<ResponseField name="credentialId" type="string">
  The credential being verified, for example `us-mdl`.
</ResponseField>

<ResponseField name="verificationModel" type="string">
  `disclosure` or `match`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.hopae.com/connect/v2/verifications/{verificationId}' \
    --user '{appId}:{appSecret}'
  ```
</RequestExample>

Non-terminal responses carry a `polling` hint: `intervalMs` is how long to wait between polls (per connection — some providers reject faster status reads), `maxDurationMs` is the session window.

<ResponseExample>
  ```json Completed theme={null}
  {
    "verificationId": "019bc4f2-8a31-7c5e-9d02-4f7a1b3e60d8",
    "status": "completed",
    "providerId": "smart-id",
    "workflowId": "wf_01J8XJ4Q2R7TPX9K",
    "flowType": "push",
    "createdAt": "2026-09-03T09:18:31.774Z",
    "verifiedAt": "2026-09-03T09:19:52.110Z",
    "expiresAt": "2026-09-03T09:48:31.774Z",
    "acr": "urn:hopae:loa:4",
    "hopae_loa": 4,
    "hopae_loa_label": "high",
    "connectionInstanceId": "conn_01J8XK2P4M9QR3TV",
    "connectionId": "smart-id",
    "credentialId": "smart-id",
    "verificationModel": "disclosure"
  }
  ```

  ```json Awaiting user action theme={null}
  {
    "verificationId": "019bc4f4-5e77-7a9c-b0d1-6c3a2f8e9b44",
    "status": "awaiting_user_action",
    "providerId": "freja",
    "workflowId": "wf_01J8XJ4Q2R7TPX9K",
    "flowType": "qr",
    "flowDetails": {
      "qrData": "<value to render as a QR code>"
    },
    "createdAt": "2026-09-03T09:12:44.301Z",
    "expiresAt": "2026-09-03T09:42:44.301Z",
    "polling": { "intervalMs": 2000, "maxDurationMs": 1800000 },
    "hopae_loa": 3,
    "hopae_loa_label": "substantial",
    "connectionInstanceId": "conn_01J8XN2C6QF9W1AZ",
    "connectionId": "freja-plus",
    "credentialId": "freja-plus",
    "verificationModel": "disclosure"
  }
  ```

  ```json Failed theme={null}
  {
    "verificationId": "019bc4f4-5e77-7a9c-b0d1-6c3a2f8e9b44",
    "status": "failed",
    "providerId": "freja",
    "workflowId": "wf_01J8XJ4Q2R7TPX9K",
    "flowType": "qr",
    "error": {
      "code": "provider_error",
      "message": "The user cancelled the authentication",
      "details": { "provider_code": "<the provider's own code>", "provider_type": "provider_error" }
    },
    "createdAt": "2026-09-03T09:12:44.301Z",
    "failedAt": "2026-09-03T09:13:51.204Z",
    "expiresAt": "2026-09-03T09:42:44.301Z",
    "connectionInstanceId": "conn_01J8XN2C6QF9W1AZ",
    "connectionId": "freja-plus",
    "credentialId": "freja-plus",
    "verificationModel": "disclosure"
  }
  ```
</ResponseExample>

## Errors

| HTTP | Code | When |
| :- | :- | :- |
| 404 | `SESSION_VERIFICATION_NOT_FOUND` | Unknown id, a session of another app, an environment mismatch, or a verification past its `expiresAt` |


## OpenAPI

````yaml GET /verifications/{verificationId}
openapi: 3.1.0
info:
  title: Hopae Connect Verification API
  version: 2.0.0
servers:
  - url: https://api.hopae.com/connect/v2
    description: Hopae Connect
security:
  - basicAuth: []
tags:
  - name: Verifications
paths:
  /verifications/{verificationId}:
    get:
      tags:
        - Verifications
      summary: Get Verification Status
      operationId: getVerification
      parameters:
        - name: verificationId
          in: path
          required: true
          description: The session id.
          schema:
            type: string
      responses:
        '200':
          description: Status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationStatus'
        '404':
          description: >-
            `SESSION_VERIFICATION_NOT_FOUND`: unknown id, or created on another
            mode.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: SESSION_VERIFICATION_NOT_FOUND
                  message: Verification not found
                  details: {}
                request_id: req_01J8XQ3V9K2M7N4P
components:
  schemas:
    VerificationStatus:
      type: object
      properties:
        verificationId:
          type: string
          description: The session id.
        status:
          type: string
          description: Current status. `processing` is reserved and not currently returned.
          enum:
            - awaiting_user_action
            - authenticating
            - processing
            - completed
            - failed
            - expired
            - cancelled
        providerId:
          type: string
          description: >-
            Catalog provider id, for example `smart-id`. The same value Create
            Verification returned.
        workflowId:
          type: string
          description: The workflow that ran.
        flowType:
          type: string
          description: The flow.
          enum:
            - qr
            - redirect
            - push
            - dc
            - query
        flowDetails:
          type: object
          description: Flow details while the session waits for the user.
        createdAt:
          type: string
          description: ISO 8601.
        expiresAt:
          type: string
          description: ISO 8601.
        verifiedAt:
          type: string
          description: ISO 8601. Present when `completed`.
        failedAt:
          type: string
          description: Present when `failed`.
        cancelledAt:
          type: string
          description: Present when `cancelled`.
        error:
          type: object
          description: 'Present when `failed`: `type`, `code`, `message`.'
        acr:
          type: string
          description: Authentication Context Class Reference.
        hopae_loa:
          type: number
          description: Numeric Level of Assurance, 1 to 5.
        hopae_loa_label:
          type: string
          description: LoA label, for example `substantial`.
        connectionInstanceId:
          type: string
          description: The activated connection instance the session runs on (`conn_…`).
        connectionId:
          type: string
          description: Catalog connection id.
        credentialId:
          type: string
          description: Catalog credential id.
        verificationModel:
          type: string
          description: '`disclosure` or `match`.'
          enum:
            - disclosure
            - match
        polling:
          type: object
          description: >-
            Present while the session is not terminal. Wait `intervalMs` between
            polls. It is set per connection, because some providers reject
            faster status reads. `maxDurationMs` is the session window.
          properties:
            intervalMs:
              type: integer
              description: Milliseconds to wait between polls.
            maxDurationMs:
              type: integer
              description: Milliseconds from creation to expiry.
          required:
            - intervalMs
            - maxDurationMs
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
        request_id:
          type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        `Basic base64(appId:appSecret)`. See
        [Authentication](/v2/api-reference/authentication).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.