- An app’s App ID and App Secret. See Authentication.
- At least one connection that is activated and enabled in a workflow. See Activate Connections.
https://api.hopae.com/connect/v2.
1. Find a connection
status=enabled returns exactly the connections you can start for the default workflow. For each one, note connectionId, flowTypes, and userInputJsonSchema (the fields to send). See Get Connections.
2. Create a verification
- Send one of
connectionId,connectionInstanceId, orproviderId. AddcredentialIdto narrow aproviderIdthat has several connections. An ambiguous one returns400. - Required for
redirectconnections:redirectUri, where Hopae sends the user back. Without it, the call fails with400 VALIDATION_REDIRECT_URI_REQUIRED. - Optional:
workflowId(otherwise the default workflow),requestedClaims(otherwise the workflow’s claims).
3. Handle the flow
Act onflowType:
qr, what qrData is and how the app opens on a phone differ by connection. flowDetails.linkData, when present, is a link to Hopae’s page, which runs these steps for you.
Full responses and diagrams for each type: Flow Types.
4. Poll until finished
Skip this forquery: its create response is already final.
Poll GET /verifications/{id} until result is set. The status is then completed or failed. Wait polling.intervalMs between calls (each non-terminal response has it). Stop at expiresAt: a verification not finished by then has expired and is deleted, so later calls return 404. See Expiry.
5. Read the result
Branch onresult.code. Every code and what to do next is in Result Codes. When it is RECEIVED, read userinfo:
Response (abridged)
- Read identity data from
user. To recognise a returning person, useuser.source_idtogether with the connection, notsub.source_idis opt-in and stable only on the same connection. See Source ID. - Add
provenance=trueandmissing_claims=trueto the query for the audit trail and the claims the source could not provide. - Read it before
expiresAt. After that the result is gone. See Expiry.
match results, is in Return Data.
Cancel
DELETE /verifications/{id} cancels a verification that has not finished (204). One that already ended answers 409 SESSION_INVALID_STATUS_TRANSITION. A cancelled verification ends as failed with result.code CLIENT_CANCELLED. See Cancel Verification.
Errors
Errors share one envelope. Switch onerror.code and quote request_id to support.

