Skip to main content

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 in result.code, and status has a new meaning.
  • status is how far the verification got. It is completed when the provider finished the check, with or without user data, and failed when the verification stopped before that.
  • result.code is what you branch on. It uses one set of codes for every connection, and each code has a suggested action.
completed no longer means that user data is available. Check that result.code is RECEIVED before you read userinfo or approve a user.

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 a query connection the create response already has the final status, so it changes too.

New

string
The result code of the verification. Branch your next action on it. result is null while the verification is in progress.
string
A short description of the code, for developers. Do not branch on it or show it to users.
string
When the verification reached its final status.

Changed meaning

string
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

string
No longer returned. Use status: failed with result.code USER_CANCELLED or CLIENT_CANCELLED.

Deprecated, still sent

These are still sent and will be removed on Mar 31, 2027.
object
deprecated
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.
string
deprecated
Use endedAt.
string
deprecated
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 follows status.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.
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 completed or failed, 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

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.
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.
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.
Nothing changes. A verification past its expiresAt is deleted and returns 404. See Expiry.
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.
Questions go to support@hopae.com.