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.
​
string
required
Direct API format: Basic <base64(client_id:client_secret)>.

​
Request Body

​
string
default:"frejaid"
required
The identifier for the desired eID provider.
​
string
default:"http://localhost:3000/callback"
URL to redirect to after a redirect-based verification.
​
string
The workflow to apply to this verification (equivalent to the workflow_id parameter in the OIDC authorize request).
  • When omitted, your app’s default workflow is used.
  • When the ID does not match any workflow in your app, the request falls back to the default workflow instead of failing.
Workflow IDs look like wf_abc123 — find them in the Console on your app’s Workflows page.
​
object
User information required by certain eID providers.Returns HTTP 400 if required fields are missing. See requirements per provider.
​
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.
​
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.
​
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

​
string
The unique identifier for the verification session
​
string
Current status of the verification.Possible values: initiated, awaiting_user_action, authenticating, completed, failed, expired, cancelledLookup eIDs (for example ng-nin, ng-bvn, br-cpf) report flowType: push but run their lookup inside this call, so status is already completed or failed. See Verification Flows → Push (Query).
​
string
The identifier of the eID provider
​
string
Type of verification flow.Possible values: qr, redirect, push, dc
​
object
​
object
Present only when the verification already failed at creation, which happens only for a lookup eID. Same shape as in Get Verification: type, code (for example INVALID_ID_NUMBER), message.
​
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.
​
string
ISO 8601 timestamp when the verification session was created
​
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.