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

# Verification Flow

> Understanding the verification lifecycle and flow types in Hopae Connect

## The Verification Lifecycle

A session can have one of the following statuses:

| Status | Description |
| :- | :- |
| `initiated` | The session has been created, and communication with the eID provider is starting. |
| `awaiting_user_action` | Waiting for the user to take action (e.g., QR code displayed, awaiting redirect). |
| `authenticating` | (Optional) The user is actively authenticating in their eID app. |
| `completed` | The user has successfully completed the verification. Fetch user + provenance via `GET /verifications/{id}/userinfo`. |
| `failed` | The verification failed (e.g., user rejection, incorrect credentials). Check the `error` field for details. |
| `expired` | The session expired because the user did not complete the action in time. |
| `cancelled` | The verification was cancelled by the developer (RP) or the user. |

## Verification Flows

Every verification starts with `POST /verifications` and ends with `GET /verifications/{id}/userinfo`. The `flowType` in the create response tells you what happens in between. Hopae Connect selects the flow from the eID provider.

Pick a flow type. Each tab shows the flow, what you do, and why the create response has that status.

<Tabs>
  <Tab title="Redirect">
    The user signs in on the provider's own page and comes back to your `redirectUri`. Key eID providers: most European eIDs, for example `mitid`.

    ```mermaid theme={null}
    sequenceDiagram
        participant U as User (browser)
        participant C as Your server
        participant H as Hopae
        participant P as Provider
        C->>H: POST /verifications
        H-->>C: redirect / awaiting_user_action (authorizationUrl)
        Note over C,H: Waiting for the user to sign in at the provider
        C->>U: Send the user to authorizationUrl
        U->>P: Sign in on the provider's page
        P-->>H: Result
        H-->>U: Back to your redirectUri
        C->>H: GET /verifications/{id}
        H-->>C: redirect / completed
        C->>H: GET /verifications/{id}/userinfo
    ```

    * **What you do:** send the user to `flowDetails.authorizationUrl`. When the user is back on your `redirectUri`, check the status.
    * **Why `awaiting_user_action`:** the provider owns the sign-in page. Hopae has no result until the user signs in there.
  </Tab>

  <Tab title="QR">
    The user scans a QR code with the eID app on their phone and approves there. Key eID providers: FrejaID, Diia, KMDL, BankID Sweden.

    ```mermaid theme={null}
    sequenceDiagram
        participant U as User (phone app)
        participant C as Your server
        participant H as Hopae
        participant P as Provider
        C->>H: POST /verifications
        H-->>C: qr / awaiting_user_action (qrData)
        Note over C,H: Waiting for the user to scan and approve
        C->>U: Show qrData as a QR code
        U->>P: Scan and approve in the eID app
        loop Until the status is terminal
            C->>H: GET /verifications/{id}
            H->>P: Check status
            H-->>C: qr / awaiting_user_action, then completed
        end
        C->>H: GET /verifications/{id}/userinfo
    ```

    * **What you do:** render `flowDetails.qrData` as a QR code (on a phone, open `flowDetails.linkData` instead), then poll.
    * **Why `awaiting_user_action`:** the credential lives in an app on another device. Hopae learns the result by asking the provider when you poll.
  </Tab>

  <Tab title="Push">
    Hopae sends the request to the eID app on the user's registered device. The user approves there. Key eID providers: Smart-ID, Audkenni, Evrotrust.

    ```mermaid theme={null}
    sequenceDiagram
        participant U as User (phone app)
        participant C as Your server
        participant H as Hopae
        participant P as Provider
        C->>H: POST /verifications (userData)
        H->>P: Send the request to the user's device
        H-->>C: push / awaiting_user_action
        Note over C,H: Waiting for the user to approve in the app
        P->>U: Notification
        U->>P: Approve in the app
        loop Until the status is terminal
            C->>H: GET /verifications/{id}
            H->>P: Check status
            H-->>C: push / awaiting_user_action, then completed
        end
        C->>H: GET /verifications/{id}/userinfo
    ```

    * **What you do:** show a waiting screen, then poll.
    * **Why `awaiting_user_action`:** the request is already on the user's phone. Only the user's approval can finish it.
  </Tab>

  <Tab title="Push (Query)">
    These eIDs (for example `ng-nin`, `ng-bvn`, `br-cpf`) are listed as `push`, but **nothing is sent to the user**. Hopae checks the ID number or image you send with the source (the national registry) during the create call, so the create response already carries the final status.

    ```mermaid theme={null}
    sequenceDiagram
        participant C as Your server
        participant H as Hopae
        participant S as Source (registry)
        C->>H: POST /verifications
        H->>S: Look up the record
        S-->>H: Record, or no match
        H-->>C: push / completed (or failed + error)
        Note over C,H: Final before create returns
        C->>H: GET /verifications/{id}/userinfo
    ```

    * **What you do:** nothing between create and userinfo. No waiting screen, no polling. On `failed`, read `error.code` in the create response (for example `INVALID_ID_NUMBER`).
    * **Why `completed` / `failed` right away:** the check needs only data you already sent, so there is nothing to wait for. Hopae answers when the source answers.
    * The create call takes as long as the source, usually a few seconds. Allow at least 30 seconds before your HTTP client times out.
    * Create answers `201` either way. A later `GET /verifications/{id}` returns the stored result without asking the source again.

    <Accordion title="Lookup eIDs (21 provider IDs)">
      | Provider ID | eID |
      | :- | :- |
      | `ng-nin` | Nigeria NIN |
      | `ng-bvn` | Nigeria BVN |
      | `ng-vid` | Nigeria Voter ID |
      | `za-nid` | South Africa National ID |
      | `ug-nin` | Uganda National ID |
      | `kenya-nid` | Kenya National ID |
      | `kenya-pass` | Kenya Passport |
      | `kenya-alien` | Kenya Alien Card |
      | `angola-nin` | Angola National ID |
      | `ghana-card` | Ghana Card |
      | `ci-nid` | Côte d'Ivoire National ID |
      | `br-cpf` | Brazil CPF |
      | `br-cnh-match` | Brazil CNH + biometrics |
      | `mx-curp` | Mexico CURP |
      | `mx-ine-qr` | Mexico INE QR Code |
      | `chile-run` | Chile RUN |
      | `peru-dni` | Peru DNI |
      | `in-pan-match` | India PAN |
      | `id-nik-match` | Indonesia NIK |
      | `id-nik-biometric-match` | Indonesia NIK + biometrics |
      | `ph-nid` | Philippine National ID |
    </Accordion>
  </Tab>

  <Tab title="DC">
    Your web page asks the user's digital wallet for a credential through the W3C Digital Credentials API. Key eID providers: US Mobile Driver License (`us-mdl`), US Digital Passport (`us-id-pass`).

    ```mermaid theme={null}
    sequenceDiagram
        participant U as User (wallet)
        participant C as Your server
        participant H as Hopae
        C->>H: POST /verifications
        H-->>C: dc / awaiting_user_action
        Note over C,H: Waiting for the user to share
        C->>H: POST /verifications/dc-request
        H-->>C: Wallet request
        C->>U: Your page calls navigator.credentials.get()
        U-->>C: Wallet response (the user shares the credential)
        C->>H: POST /verifications/dc-response
        H-->>C: completed + verified claims
    ```

    * **What you do:** mint the wallet request, invoke the wallet in the browser, and submit its response. There is no status polling.
    * **Why `awaiting_user_action`:** only the user can release the credential from their wallet.
  </Tab>
</Tabs>

<Tip>
  For detailed instructions on each flow, see the [**Integration Guides**](/guides/api-integration#step-2-handle-flow-response) section.
</Tip>


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