Migrate to Result Codes
Update a v2 integration built before v2.1.0.From v2.1.0, released on Nov 19, 2026, a verification that has ended reports its result inresult.code, and status has a new meaning.statusis how far the verification got. It iscompletedwhen the provider finished the check, with or without user data, andfailedwhen the verification stopped before that.result.codeis what you branch on. It uses one set of codes for every connection, and each code has a suggested action.
Who is affected
Why it changed
Previously, the response did not say clearly how a verification ended.What changes
The changes are on the Verification response and on the webhook event names. Create Verification and Get Verification both return the Verification response. On aquery connection the create response already has the final status, so it changes too.New
The result code of the verification. Branch your next action on it.
result is null while the verification is in progress.Changed meaning
The provider finished the check, with or without user data. A check that finished without user data, for example because there is no record, used to end as
failed. To know whether userinfo is available, check that result.code is RECEIVED.Removed, use the replacement
Deprecated, still sent
These are still sent and will be removed on Mar 31, 2027.Use
result. Hopae maps what error told you into it. error is still sent on a failed verification that had it before. A cancelled verification now ends as failed and has no error, so do not assume error is present.The result in the
redirectUri query parameters (status, result, error, error_description, idp_error, idp_error_description). You do not need them. A URL is not proof of the result, so read the result from the Verification response.Webhook events
If you receive v2 webhooks, the final event followsstatus.verification.completed is sent for every completed verification. Check data.result.code. See Webhooks.Example responses
Each tab is one way a verification ends, as it was before and as it is returned now. Green lines are new. Red lines are no longer returned. Gray lines are deprecated and still sent. Other fields are omitted.- Data received
- Failed
- Cancelled
- In progress
The status is the same.
result.code is RECEIVED, and userinfo is available.Before
Now
How to migrate
1
Poll until result is set
Stop polling when
result is not null. The status is then completed or failed.2
Branch on result.code
Read userinfo only when the code is
RECEIVED. On a match connection, RECEIVED applies even when the comparison did not match, so check match.matched as before.3
Handle a code you do not know
More codes can be added. Only
RECEIVED gives user data, so treat any other code as not verified and offer the user another method.4
Stop reading the deprecated fields
Read
result instead of error, and endedAt instead of verifiedAt and cancelledAt.Result Codes
Every code, its status, and what to do next.
Console
- Security & Compliance → Audit Log shows an ended verification as
completedorfailed, with a Result code column. - The same rule applies to verifications created with the v1 API. The v1 API response does not change.
- Records from before this change keep the status they had.
FAQ
Is result.message written by Hopae or by the provider?
Is result.message written by Hopae or by the provider?
By Hopae. It is a short description of the code for developers, not the provider’s text. Write the text your users see from
result.code.Can I still read the provider's own error code?
Can I still read the provider's own error code?
Hopae maps it for you. Each provider code is mapped to a result code, so one code means the same thing on every connection and decides the next action. The provider’s own code is not part of
result.Do I have to handle every code?
Do I have to handle every code?
No. Handle
RECEIVED, and treat every other code as not verified. Add a case for a code when you want a specific message or action for it.What happens after expiresAt?
What happens after expiresAt?
Nothing changes. A verification past its
expiresAt is deleted and returns 404. See Expiry.I use OIDC. Is there anything new?
I use OIDC. Is there anything new?
Nothing to change. A verification that ends as
RECEIVED returns an authorization code as before. Any other ending returns error=access_denied, now with status and result_code. See OIDC Integration.
