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

# Create Verification

Initiates a new identity verification session with the specified eID provider.

## Headers

<Info>
  Basic authentication: set `Authorization.username` to your Client ID (`client_id`) and `Authorization.password` to your Client Secret (`client_secret`). The interface builds the header automatically.
  See [Authentication](/api-reference/authentication) for an overview of the two auth schemes and when to use each.
</Info>

<ParamField header="Authorization" type="string" required>
  Direct API format: `Basic <base64(client_id:client_secret)>`.
</ParamField>

## Request Body

<ParamField body="providerId" type="string" required default="frejaid">
  The identifier for the desired eID provider.
</ParamField>

<ParamField body="redirectUri" type="string" default="http://localhost:3000/callback">
  URL to redirect to after a redirect-based verification.
</ParamField>

<ParamField body="userData" type="object">
  User information required by certain eID providers.

  Returns HTTP 400 if required fields are missing.
  See <a href="/api-reference/verifications/user-data-requirements">requirements per provider</a>.

  ```json theme={null}
  {
    "registrationId": "PNOLT-40504040001"
  }
  ```
</ParamField>

<ParamField body="requestedLoa" type="integer">
  Minimum Level of Assurance required (1–5).

  * Returns HTTP 422 if the provider cannot meet this level.
  * Verification status becomes `failed` if final LoA is lower than requested.

  See [Level of Assurance](/guides/concepts/assurance) for details.
</ParamField>

<ParamField body="requestedClaims" type="string[]">
  Claims to request from the eID provider for this verification.

  * When provided, overrides the default scopes configured in your app settings.
  * When omitted, falls back to your app settings.

  See [Normalized User Data](/guides/concepts/normalized-user-data) for details.

  ```json theme={null}
  ["name", "given_name", "family_name", "middle_name", "nickname", "preferred_username", "gender", "birthdate", "locale", "email", "phone_number", "address", "nationality"]
  ```

  <Note>Not all claims are available from every provider. Unavailable claims appear in `missing_claims` of the `/userinfo` response.</Note>
</ParamField>

<ParamField body="matchData" type="object">
  Required when `providerId` is a match-capable provider. Carries the values you want compared against the authoritative source. The keys are **provider-native** — Hopae does not normalize them so the audit trail stays aligned with the upstream IDP. The keys submitted here populate `match.submitted_fields` in the result and the values appear under `match.details[*].submitted_value` in `/userinfo`.

  Refer to the provider's match field schema for the exact required/optional keys; some providers also require an additional lookup key under `userData` (`userData` selects the record; `matchData` is the set of values to verify against it).

  ```json Example theme={null}
  {
    "fullName": "Test User",
    "dateOfBirth": "1990-01-01"
  }
  ```

  See [Return Data Model — Verification models](/guides/concepts/return-data-model#verification-models) for how match results are returned.
</ParamField>

## Response

<ResponseField name="verificationId" type="string">
  The unique identifier for the verification session
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the verification.

  Possible values: `initiated`, `pending`, `authenticating`, `completed`, `failed`, `expired`, `cancelled`
</ResponseField>

<ResponseField name="providerId" type="string">
  The identifier of the eID provider
</ResponseField>

<ResponseField name="flowType" type="string">
  Type of verification flow.

  Possible values: `qr`, `redirect`, `push`
</ResponseField>

<ResponseField name="flowDetails" type="object">
  <Expandable title="Properties">
    <ResponseField name="qrData" type="string">
      Base64 data for QR code generation
    </ResponseField>

    <ResponseField name="authorizationUrl" type="string">
      URL for browser redirection
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="expiresAt" type="string">
  ISO 8601 timestamp when the verification session expires. Once the current time passes this value, treat the verification as expired — the user can no longer complete it, and subsequent status calls will report `status: "expired"`. Stop polling and start a new verification if the user still needs to authenticate.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp when the verification session was created
</ResponseField>

<ResponseField name="verification_model" type="string">
  Resolved from the provider's capability. `disclosure` returns user attributes; `match` returns a comparison envelope. Tells the RP which userinfo shape to expect ahead of time. Returned only on the creation response, not on subsequent status calls.
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl --request POST \
    --url 'https://sandbox.api.hopae.com/connect/v1/verifications' \
    --user '{clientId}:{clientSecret}' \
    --header 'Content-Type: application/json' \
    --data '{
      "providerId": "frejaid"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "verificationId": "058ff1aa613a40a883d367a07d7b3713",
    "status": "initiated",
    "providerId": "frejaid",
    "flowType": "qr",
     "flowDetails": {
      "qrData": "qr-deep-link-url"
    },
    "expiresAt": "2025-08-06T12:00:00Z",
    "createdAt": "2025-08-06T11:00:00Z"
  }
  ```
</ResponseExample>