Skip to main content
POST
/
verifications
curl --request POST \
  --url 'https://sandbox.api.hopae.com/connect/v1/verifications' \
  --user '{clientId}:{clientSecret}' \
  --header 'Content-Type: application/json' \
  --data '{
    "providerId": "frejaid"
  }'

{
  "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"
}

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.

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

​
Headers

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 for an overview of the two auth schemes and when to use each.
​
Authorization
string
required
Direct API format: Basic <base64(client_id:client_secret)>.

​
Request Body

​
providerId
string
default:"frejaid"
required
The identifier for the desired eID provider.
​
redirectUri
string
default:"http://localhost:3000/callback"
URL to redirect to after a redirect-based verification.
​
userData
object
User information required by certain eID providers.Returns HTTP 400 if required fields are missing. See requirements per provider.
{
  "registrationId": "PNOLT-40504040001"
}
​
requestedLoa
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 for details.
​
requestedClaims
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 for details.
["name", "given_name", "family_name", "middle_name", "nickname", "preferred_username", "gender", "birthdate", "locale", "email", "phone_number", "address", "nationality"]
Not all claims are available from every provider. Unavailable claims appear in missing_claims of the /userinfo response.
​
matchData
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).
Example
{
  "fullName": "Test User",
  "dateOfBirth": "1990-01-01"
}
See Return Data Model — Verification models for how match results are returned.

​
Response

​
verificationId
string
The unique identifier for the verification session
​
status
string
Current status of the verification.Possible values: initiated, pending, authenticating, completed, failed, expired, cancelled
​
providerId
string
The identifier of the eID provider
​
flowType
string
Type of verification flow.Possible values: qr, redirect, push, dc
​
flowDetails
object
​
expiresAt
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.
​
createdAt
string
ISO 8601 timestamp when the verification session was created
​
verification_model
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.
curl --request POST \
  --url 'https://sandbox.api.hopae.com/connect/v1/verifications' \
  --user '{clientId}:{clientSecret}' \
  --header 'Content-Type: application/json' \
  --data '{
    "providerId": "frejaid"
  }'

{
  "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"
}