Skip to main content
With the REST API, your backend starts the verification, your UI handles the user step, and your backend reads the result. Before you start Every call uses HTTP Basic auth with the App ID and App Secret against 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, or providerId. Add credentialId to narrow a providerId that has several connections. An ambiguous one returns 400.
  • Required for redirect connections: redirectUri, where Hopae sends the user back. Without it, the call fails with 400 VALIDATION_REDIRECT_URI_REQUIRED.
  • Optional: workflowId (otherwise the default workflow), requestedClaims (otherwise the workflow’s claims).
See Create Verification and User Input.

3. Handle the flow

Act on flowType:
For 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 for query: 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.
For qr and push, your polls drive the verification: Hopae checks the provider only when you poll. If you stop polling, the status stops updating and no terminal webhook is sent. Redirect and dc verifications finish without polling, except mObywatel, which you poll after the redirect.
Statuses are explained in Verification Flow.

5. Read the result

Branch on result.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, use user.source_id together with the connection, not sub. source_id is opt-in and stable only on the same connection. See Source ID.
  • Add provenance=true and missing_claims=true to 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.
The full payload, including 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 on error.code and quote request_id to support.
Every code and what to do: Error Codes.