Skip to main content
POST
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.
​
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.
Not all claims are available from every provider. Unavailable claims appear in missing_claims of the /userinfo response. For match providers, requested claims take effect only when the provider also exposes disclosed (IDP-asserted) claims; otherwise the parameter is accepted and ignored.
​
matchData
object
Required when providerId is a match-capable provider. Carries the values you want compared against the authoritative source. The keys are OIDC-normalized names (see Normalized User Data); fields with no normalized catalog entry keep their provider-native name. Hopae translates to the upstream IDP’s native names at the provider boundary, so the provenance audit trail stays aligned with the source while match.submitted_fields and match.details keys mirror exactly what you submitted. 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
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, awaiting_user_action, 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.