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
default:"smart-id"
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 userInputSchema. Required fields are validated before the session starts: a missing field or an out-of-range select value 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
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.
​
string
Preferred flow when the connection supports more than one: qr, redirect, push, dc, or query. The response’s flowType reports the flow that was actually started.
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), not by the request body. requestedClaims, requestedLoa, and matchData from v1 are not accepted. 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, completed, failed, cancelled (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. 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
Present only when the session already failed at creation, which happens only on a query connection. Same shape as in Get Verification: type, code (for example INVALID_ID_NUMBER), message.
​
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 userInputSchema.

Example:
​
redirectUri
string

Where to send the user after a redirect flow. Supply it explicitly when the flow needs a return destination. REST does not default from the OIDC allowlist.

​
flowType
enum<string>

Preferred flow when the connection supports several.

Available options:
qr,
redirect,
push,
dc,
query
​
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,
expired,
cancelled
​
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.

​
error
object

Present only when the session already failed at creation (a query connection): type, code, message.

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