> For the complete documentation index, see [llms.txt](https://docs.vida.id/identity-stack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vida.id/identity-stack/verify/kyc-web-sdk/integration/backend-integration/overview.md).

# Overview

{% hint style="info" %}
**Platform Note** This section applies to the KYC Web SDK running in any supported browser. The backend API calls are the same VIDA APIs used across VIDA's SDKs — what differs is the shape of the SDK response payload your web app forwards. For the exact field structure, see the SDK Response page.
{% endhint %}

After the KYC Web SDK completes in the user's browser, your client backend needs to call VIDA's backend APIs to retrieve the KYC outcome, transaction records, and fraud evaluation results.

This section covers all backend calls — when to make them, how to make them, and how to act on the results.

***

### Who Is This For?

This section is for backend engineers responsible for:

* Receiving the SDK response forwarded from the web app
* Calling VIDA's APIs after the SDK session ends
* Routing users based on the KYC outcome (approved, manual review, or rejected)
* Audit logging and billing reconciliation using transaction IDs

***

### End-to-End Flow

Below is how the end-to-end KYC Backend flow works.

<details>

<summary>End-to-End Flow</summary>

```mermaid
sequenceDiagram
    participant U as End User
    participant App as Client App (iOS/Android)
    participant BE as Client Backend
    participant GX as VIDA My-Verify
    participant LS as VIDA Liveness Service

    U->>App: Starts KYC
    App->>GX: OCR + ID Verification
    App->>LS: Liveness check (direct)
    App->>GX: Face Match (+ livenessTransactionIds)
    GX-->>App: SDK Response
    App->>BE: Forward SDK Response

    Note over BE,GX: Backend calls VIDA APIs
    BE->>GX: GET /api/v2/verify/status?verificationId=UUID
    GX-->>BE: overallStatus + per-operation breakdown
    BE->>GX: GET /api/v2/transaction?transactionId=UUID
    GX-->>BE: Full transaction payload
    BE->>GX: GET /api/v1/evaluation/{verificationId}
    GX-->>BE: Fraud Shield result

    BE->>App: KYC decision
    App->>U: Show result
```

</details>

***

### Quick Reference: Which API to Call

| Trigger                     | API Endpoint                                                                      | Purpose                                                                                   |
| --------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| SDK response received       | `GET /api/v2/verify/status?verificationId=UUID`                                   | Get the overall KYC decision and per-operation status breakdown                           |
| Need full operation payload | `GET /api/v2/transaction?transactionId=UUID` (Optional: `&includeDocuments=true`) | Retrieve complete result for a single attempt — for audit, billing, or dispute resolution |
| Fraud Shield is enabled     | `GET /api/v1/evaluation/{verificationId}`                                         | Get the full device/session fraud evaluation result                                       |

***

### Key Identifiers

Before making any API call, understand these four identifiers and how they relate to each other.

| Identifier            | Also Called        | Description                                                                                         | Where to Find It             |
| --------------------- | ------------------ | --------------------------------------------------------------------------------------------------- | ---------------------------- |
| `verificationId`      | groupId, sessionId | Unique ID for the entire KYC session. Shared across all operations (OCR, IDV, Liveness, FaceMatch). | SDK response - top level     |
| `transactionId`       | —                  | Unique ID for one attempt of one operation. Each retry creates a new `transactionId`.               | SDK response - per operation |
| `clientTransactionId` | groupId            | Same value as `verificationId`. Used specifically when calling the Evaluation API.                  | SDK response - top level     |
| `partnerTrxId`        | —                  | Your own system's reference ID, echoed back by VIDA in every response.                              | SDK response - per operation |

{% hint style="info" %}
**Critical: Liveness `transactionId` goes to a different API**

The `transactionId` inside `livenessDetails` must be used with the Liveness Service's own GET transaction API - **NOT** with `GET /api/v2/transaction?transactionId={UUID}`.

The My-Verify transaction API does not serve liveness records.
{% endhint %}

***

### What to Do Based on `overallStatus`

Once you call `GET /verify/status`, use `overallStatus` to drive your business logic.

<table><thead><tr><th width="179.59375">OverallStatus</th><th>Meaning</th><th>Recommended Action</th></tr></thead><tbody><tr><td><code>VERIFIED</code></td><td>All required checks passed with latest results verified.</td><td>Proceed with onboarding.</td></tr><tr><td><code>REVIEW</code></td><td>All checks completed, none failed, but one or more flagged.</td><td>Route to manual review queue.</td></tr><tr><td><code>ERROR</code></td><td>At least one check failed (may also indicate fraud detected).</td><td>Check <code>fraudResult</code> field; retry or reject.</td></tr><tr><td><code>IN_PROGRESS</code></td><td><p>At least one required operation has not been attempted yet. </p><p><strong>Note:</strong> If the SDK has already returned an error callback (containing <code>failedOperation</code>), this session will not transition to <code>VERIFIED</code>.</p></td><td>Wait and poll again (flow may still be running). Treat as not verified and prompt the user to restart. See Important Note below.</td></tr><tr><td><code>FAILED</code></td><td>Session timed out or was abandoned (terminal state).</td><td>Mark case as failed; prompt user to restart.</td></tr></tbody></table>

***

### Important: Interpreting KYC Status for Decision-Making

When using the GET KYC Status API to determine a user's KYC outcome, we recommend the following approach:

* **`VERIFIED`** → The user has successfully passed KYC. You may proceed with granting access or completing onboarding.
* **Any other status** (including `IN_PROGRESS` or `FAILED`) → The user has NOT successfully completed KYC. Your application should treat this as a non-verified outcome and handle accordingly (e.g., prompt the user to retry, or reject onboarding).

Additionally, use the SDK callback response as your primary signal for real-time decision-making:

* If the SDK returns a **success callback**, poll the GET KYC Status API to confirm the `VERIFIED` status.
* If the SDK returns an **error callback** (containing `failedOperation` in the operations array), the session is considered terminal. You may treat this as a failed verification without waiting for the GET KYC Status API to update.

#### Status Precedence

`FAILED` > `IN_PROGRESS` > `ERROR` > `REVIEW` > `VERIFIED`

{% hint style="info" %}
Once a case reaches `VERIFIED` or `FAILED`, it is terminal - no further operations are accepted. Any new request using that `verificationId` will be rejected with error code `5702`.
{% endhint %}