> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopae.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate to Result Codes

> Update a v2 integration built before v2.1.0.

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

> [!WARNING]
>
> `completed` no longer means that user data is available. Check that `result.code` is `RECEIVED` before you read userinfo or approve a user.

```mermaid theme={null}
%%{init: {"flowchart": {"nodeSpacing": 24, "rankSpacing": 40}}}%%
flowchart LR
    Q{"Did the provider<br/>finish the check?"}
    Q -- Yes --> C["completed"]
    Q -- No --> F["failed"]
    C -- "User data" --> R["RECEIVED"]
    C -- "No user data" --> N["4 other codes"]
    F --> W["11 codes"]
```

## Who is affected

| Integration | Affected | Details |
| :- | :- | :- |
| v2 REST | Yes | `status` on the Verification response has a new meaning. |
| v2 OIDC | No | The authorization code is issued as before. |
| v1 | No | v1 responses and v1 webhooks do not change, and your code needs no change. The Console shows your verifications by the new rule. See [Console](#console). |

## Why it changed

Previously, the response did not say clearly how a verification ended.

| | Before | Now |
| :- | :- | :- |
| Billing | A billed verification could end as `completed` or as `failed`. It was hard for both you and Hopae to tell which verifications were billed. | `status` matches billing. In a production app, `completed` is billed and `failed` is not. What is billed has not changed. |
| Failure reason | The error code was broad. To tell why a verification failed and what to do next, you had to rely on the provider's own code, which is different on every connection. | `result.code` uses one set of codes for every connection. Each code has a suggested action. |

## What changes

The changes are on the Verification response and on the webhook event names. [Create Verification](https://docs.hopae.com/v2/api-reference/verifications/create-verification.md) and [Get Verification](https://docs.hopae.com/v2/api-reference/verifications/get-verification.md) both return the Verification response. On a `query` connection the create response already has the final status, so it changes too.

### New

**result.code** `string`

The result code of the verification. Branch your next action on it. `result` is `null` while the verification is in progress.

**result.message** `string`

A short description of the code, for developers. Do not branch on it or show it to users.

**endedAt** `string`

When the verification reached its final status.

### Changed meaning

**status: completed** `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

**status: cancelled** `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**.

**error** `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.

**where each property is now**

**error.code** `string`

`result.code`

**error.details.provider\_code** `string`

`result.code`. Hopae maps each provider code to a result code.

**error.message** `string`

`result.message`

**verifiedAt, cancelledAt** `string` *deprecated*

Use `endedAt`.

**redirectUri query parameters** `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`.

| Before | Now |
| :- | :- |
| `verification.succeeded` | `verification.completed` |
| `verification.cancelled` | `verification.failed` |

`verification.completed` is sent for every `completed` verification. Check `data.result.code`. See [Webhooks](https://docs.hopae.com/v2/guides/webhook-signing.md).

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

> [tab] Data received
>
> The status is the same. `result.code` is `RECEIVED`, and userinfo is available.
>
> ```json Before theme={null}
> {
>   "verificationId": "019bc4f2-8a31-7c5e-9d02-4f7a1b3e60d8",
>   "status": "completed",
>   "createdAt": "2026-11-19T09:00:12.004Z",
>   "verifiedAt": "2026-11-19T09:01:05.120Z"
> }
> ```
>
> ```json Now highlight={10-11} theme={null}
> {
>   "verificationId": "019bc4f2-8a31-7c5e-9d02-4f7a1b3e60d8",
>   "status": "completed",
>   "result": { // [!code ++:4]
>     "code": "RECEIVED",
>     "message": "User data is available from the userinfo endpoint."
>   },
>   "createdAt": "2026-11-19T09:00:12.004Z",
>   "endedAt": "2026-11-19T09:01:05.120Z", // [!code ++]
>   /** deprecated, use endedAt */
>   "verifiedAt": "2026-11-19T09:01:05.120Z"
> }
> ```

> [tab] Failed
>
> On `br-cpf`, the provider was unavailable. The status stays `failed`. `result` is added, and the deprecated `error` is still sent.
>
> ```json Before theme={null}
> {
>   "verificationId": "019bc4f2-8a31-7c5e-9d02-4f7a1b3e60d8",
>   "status": "failed",
>   "error": {
>     "code": "provider_error",
>     "message": "Consulta CPF service error",
>     "details": {
>       "provider_code": "PROVIDER_ERROR",
>       "provider_type": "verification_error"
>     }
>   },
>   "createdAt": "2026-11-19T09:00:12.004Z"
> }
> ```
>
> ```json Now highlight={8-16} theme={null}
> {
>   "verificationId": "019bc4f2-8a31-7c5e-9d02-4f7a1b3e60d8",
>   "status": "failed",
>   "result": { // [!code ++:4]
>     "code": "PROVIDER_UNAVAILABLE",
>     "message": "The provider is temporarily unavailable."
>   },
>   /** deprecated, use result */
>   "error": {
>     "code": "provider_error",
>     "message": "Consulta CPF service error",
>     "details": {
>       "provider_code": "PROVIDER_ERROR",
>       "provider_type": "verification_error"
>     }
>   },
>   "createdAt": "2026-11-19T09:00:12.004Z",
>   "endedAt": "2026-11-19T09:00:22.310Z" // [!code ++]
> }
> ```

> [tab] Cancelled
>
> You called [Cancel Verification](https://docs.hopae.com/v2/api-reference/verifications/cancel-verification.md). The status moves from `cancelled` to `failed`, and the code says who cancelled.
>
> ```json Before theme={null}
> {
>   "verificationId": "019bc4f2-8a31-7c5e-9d02-4f7a1b3e60d8",
>   "status": "cancelled", // [!code --]
>   "createdAt": "2026-11-19T09:00:12.004Z",
>   "cancelledAt": "2026-11-19T09:01:05.120Z"
> }
> ```
>
> ```json Now highlight={10-11} theme={null}
> {
>   "verificationId": "019bc4f2-8a31-7c5e-9d02-4f7a1b3e60d8",
>   "status": "failed", // [!code ++]
>   "result": { // [!code ++:4]
>     "code": "CLIENT_CANCELLED",
>     "message": "The verification was cancelled by the requesting application."
>   },
>   "createdAt": "2026-11-19T09:00:12.004Z",
>   "endedAt": "2026-11-19T09:01:05.120Z", // [!code ++]
>   /** deprecated, use endedAt */
>   "cancelledAt": "2026-11-19T09:01:05.120Z"
> }
> ```

> [tab] In progress
>
> The status is the same. `result` is present and `null`.
>
> ```json Before theme={null}
> {
>   "verificationId": "019bc4f2-8a31-7c5e-9d02-4f7a1b3e60d8",
>   "status": "awaiting_user_action",
>   "createdAt": "2026-11-19T09:00:12.004Z"
> }
> ```
>
> ```json Now theme={null}
> {
>   "verificationId": "019bc4f2-8a31-7c5e-9d02-4f7a1b3e60d8",
>   "status": "awaiting_user_action",
>   "result": null, // [!code ++]
>   "createdAt": "2026-11-19T09:00:12.004Z"
> }
> ```

## How to migrate

```ts theme={null}
// 1. Create. On a query connection the response is already final.
let v = await createVerification(request);

// 2. Otherwise poll until the result is set. Stop at expiresAt.
while (!v.result) {
  v = await getVerification(v.verificationId); // wait v.polling.intervalMs between calls
}

// 3. Branch on result.code.
switch (v.result.code) {
  case "RECEIVED":
    return decide(await getUserinfo(v.verificationId)); // your rule, e.g. userinfo.match.matched
  case "RECORD_NOT_FOUND":
  case "INVALID_USER_DATA":
  case "IMAGE_INVALID":
    return askToCheckInput();
  case "LOGIN_FAILED":
  case "SESSION_EXPIRED":
    return retry();
  case "USER_CANCELLED":
  case "EID_NOT_ELIGIBLE":
  case "LOA_NOT_MET":
    return offerAnotherMethod();
  case "CREDENTIAL_INVALID":
  case "MINOR_NOT_ALLOWED":
    return decline();
  case "PROVIDER_UNAVAILABLE":
  case "PROVIDER_ERROR":
    return retryLater();
  case "PROVIDER_CONFIGURATION_ERROR":
  case "INTERNAL_ERROR":
    return contactSupport();
  case "CLIENT_CANCELLED":
    return; // you cancelled it
  default:
    // A code added later. Only RECEIVED gives user data.
    return offerAnotherMethod();
}
```

**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`.

> [card] [Result Codes](https://docs.hopae.com/v2/guides/reference/result-codes.md)
>
> 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

> [accordion] 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`.

> [accordion] 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`.

> [accordion] 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.

> [accordion] What happens after expiresAt?
>
> Nothing changes. A verification past its `expiresAt` is deleted and returns `404`. See [Expiry](https://docs.hopae.com/v2/guides/verifications/verification-flow.md#expiry).

> [accordion] 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](https://docs.hopae.com/v2/guides/oidc-integration.md).

Questions go to [support@hopae.com](mailto:support@hopae.com).

On this page
[Who is affected](#who-is-affected)
[Why it changed](#why-it-changed)
[What changes](#what-changes)
[Example responses](#example-responses)
[How to migrate](#how-to-migrate)
[Console](#console)
[FAQ](#faq)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.