Skip to main content
POST
Starts a verification session against a connection instance, a connection you activated for your app. Get the id from Get Connections.

Headers

string
required
Basic <base64(appId:appSecret)>. See Authentication.
string
default:"application/json"
required
Must be application/json.

Request Body

string
The catalog connection id, as listed in the Console and returned by Get Connections (for example smart-id, google-wallet-us-mdl). It resolves to your app’s activated instance of that connection. Provide exactly one of connectionId, connectionInstanceId, or providerId.
string
Alternative to connectionId or providerId: the activated connection instance (conn_…) from Get Connections.
string
Catalog provider id (provider.id from Get Connections). Resolves among the workflow’s enabled connections. If several match, the request returns 400 and names the candidates. Add credentialId or use connectionId.
string
Catalog credential id (credential.id from Get Connections). Only accepted together with providerId. The pair identifies one catalog connection. A credential id alone does not identify a provider.
string
The workflow that governs this verification: which connections are enabled and which claims are requested. Defaults to the app’s default workflow. An unknown id returns 400 VALIDATION_INVALID_PARAMETER. An app with no workflow returns 409 WORKFLOW_NOT_CONFIGURED.
object
Values the connection needs before it can start: a lookup key such as a registration id, or the values to compare for a match connection. One flat map. The fields come from the connection’s userInputJsonSchema. Required fields are validated before the session starts: a missing field or a value outside the field’s enum returns HTTP 400, and a value the connection rejects returns HTTP 422 VALIDATION_INVALID_USER_DATA. Keys the schema does not declare are dropped. See User Input.
string[]
Claims to request in this verification. A non-empty list replaces the workflow’s claims, so include source_id if you need it. If omitted or empty, the workflow’s claims are used. Get Connections shows each connection’s availableClaims. See Normalized User Data.
integer
The Level of Assurance to ask the provider for, from 1 to 4.
  • Only a connection with acceptsRequestedLoa: true in Get Connections whose highest credential.loa level is at least requestedLoa supports it. Any other connection returns 422 VALIDATION_UNPROCESSABLE before the session starts.
  • The provider asks the user to sign in at that level, so hopae_loa is at least requestedLoa.
  • To require a minimum, check hopae_loa yourself or add a check-min-loa node to the workflow.
See Request a target LoA.
string
Where to send the user after a redirect-based flow completes. Required when the session starts a redirect flow (otherwise 400 VALIDATION_REDIRECT_URI_REQUIRED). REST creation does not select a default from the app’s OIDC redirect URI allowlist.
Without requestedClaims, the claims requested from the provider are decided by the workflow (the common claims of the verification step plus any credential-specific claims for this connection). matchData from v1 is not accepted, and there is no loaStrategy. Unknown fields are ignored. See Workflows.

Provider-key example

The selected connection must still be activated and enabled in the resolved workflow.

Response

Returns 201 Created.
string
The session id (UUID v7). It is also the sub of the userinfo response.
string
awaiting_user_action immediately after creation. Later values: authenticating, then completed or failed (processing is reserved and not currently returned). An unfinished verification expires at expiresAt and is then deleted. See Verification Flow.A query connection (lookup eID such as ng-nin or br-cpf) runs its lookup inside this call, so status is already completed or failed and result is set. See Flow Types.
string
The flow that was started: qr, redirect, push, dc, or query. See Flow Types.
object
What your UI needs to continue. The keys depend on flowType.
object
Set when the verification already reached a final status at creation, which happens only on a query connection. null otherwise. Same shape as in Get Verification: code and message. See Result Codes.
string
ISO 8601 time the verification reached its final status. Present with result.
object
deprecated
Use result. Present on some failed verifications, with code, message, and optionally details. A negative answer from the provider ends as completed and has no error.
string
ISO 8601 creation time.
string
ISO 8601 expiry, 30 minutes after creation. A verification not finished by then has expired and is deleted: GET /verifications/{id} returns 404. Stop polling at this time and start a new verification. See Expiry.
string
Echo of the connection instance used.
string
The catalog connection id, for example google-wallet-us-mdl.
string
The credential being verified, for example us-mdl.
string
The provider presenting the credential, for example google-wallet.
string
disclosure or match. Tells you which userinfo shape to expect.

Errors

See Error Codes for the envelope.

Authorizations

Authorization
string
header
required

Basic base64(appId:appSecret). See Authentication.

Body

application/json

Provide exactly one of connectionId, connectionInstanceId, or providerId. credentialId is valid only with providerId.

connectionId
string
required

Catalog connection id from Get Connections. Mutually exclusive with connectionInstanceId and providerId.

Example:

"smart-id"

connectionInstanceId
string

Activated instance (conn_…). Mutually exclusive with connectionId and providerId.

workflowId
string

Workflow to run. Defaults to the app's default workflow. An unknown id returns 400. An app with no workflow returns 409 WORKFLOW_NOT_CONFIGURED.

userInput
object

Values the connection needs, per its userInputJsonSchema.

Example:
requestedClaims
string[]

Claims to request in this verification. A non-empty list replaces the workflow's claims, so include source_id if you need it. If omitted or empty, the workflow's claims are used.

Example:
requestedLoa
integer

The Level of Assurance to ask the provider for. Only a connection with acceptsRequestedLoa: true in GET /connections whose highest credential.loa level is at least this level supports it; any other connection returns 422 VALIDATION_UNPROCESSABLE. The provider asks the user to sign in at that level, so hopae_loa is at least this level. To require a minimum, check hopae_loa yourself or add a check-min-loa workflow node.

Required range: 1 <= x <= 4
Example:

3

redirectUri
string

Where to send the user after a redirect flow. Required for redirect connections: without it, the call fails with 400 VALIDATION_REDIRECT_URI_REQUIRED. REST does not default from the OIDC allowlist.

providerId
string

Catalog provider id. Mutually exclusive with connectionId and connectionInstanceId. Add credentialId when the provider has multiple enabled credentials.

credentialId
string

Catalog credential id. Accepted only together with providerId.

Response

Created.

verificationId
string

The session id.

status
enum<string>

awaiting_user_action after creation.

Available options:
awaiting_user_action,
authenticating,
processing,
completed,
failed
flowType
enum<string>

The flow that was started.

Available options:
qr,
redirect,
push,
dc,
query
flowDetails
object

What your UI needs next. Keys depend on flowType.

result
object | null

Set when the verification already reached a final status at creation, which happens only on a query connection. code and message. See Result Codes.

error
object
deprecated

Deprecated, use result. Present on some failed verifications: code, message, and optionally details.

endedAt
string

ISO 8601 time the verification reached its final status. Present with result.

createdAt
string

ISO 8601.

expiresAt
string

ISO 8601, 30 minutes after creation.

connectionInstanceId
string

The instance used.

connectionId
string

Catalog connection id.

credentialId
string

The credential.

providerId
string

The provider.

verificationModel
enum<string>

disclosure or match.

Available options:
disclosure,
match
polling
object

Present while the session is not terminal. Wait intervalMs between polls. It is set per connection, because some providers reject faster status reads. maxDurationMs is the session window.