> 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-mobile-sdk/integration-overview/backend-integration/overview.md).

# Overview

{% hint style="info" %}
**Platform Note**

This section applies to both iOS and Android integrations. The backend API calls are identical regardless of which mobile SDK your client app uses. There is no need for a separate backend section per platform.
{% endhint %}

After the KYC SDK completes on the user's device, 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 mobile 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 explaining how end-to-end flow KYC Backend works.

<figure><img src="/files/PZz7iDETiT5PRkxZhfyF" alt=""><figcaption></figcaption></figure>

<details>

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

{% code expandable="true" %}

````mmd
```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 /verify/status?verificationId={id}
    GX-->>BE: overallStatus + per-operation breakdown
    BE->>GX: GET /api/v1/transaction/{transactionId}
    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
```
````

{% endcode %}

</details>

### Quick Reference: Which API to Call

| Trigger                     | API Endpoint                                | Purpose                                                                                   |
| --------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| SDK response received       | `GET` `/verify/status`                      | Get the overall KYC decision and per-operation status breakdown                           |
| Need full operation payload | `GET` `/api/v2/transaction/{transactionId}` | 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.

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

{% 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}`.

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.

| OverallStatus | Meaning                                                      | Recommended Action                                  |
| ------------- | ------------------------------------------------------------ | --------------------------------------------------- |
| `VERIFIED`    | All required checks passed with latest results verified      | Proceed with onboarding                             |
| `REVIEW`      | All checks completed, none failed, but one or more flagged   | Route to manual review queue                        |
| `ERROR`       | At least one check failed (may also indicate fraud detected) | Check fraudResult field; retry or reject            |
| `IN_PROGRESS` | At least one required operation has not been attempted yet   | Wait and poll again - the flow may still be running |
| `FAILED`      | Session timed out or was abandoned (terminal state)          | Mark case as failed; prompt user to restart         |

{% hint style="info" %}
**Status Precedence**

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

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 %}