Overview

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.

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.

End-to-end Flow

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

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	Retrieve the complete result for a single attempt — used for audit, billing, or dispute resolution. Add includeDocuments=true (optional) to also get presigned URLs for the submitted documents (default: false).
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 Fraud Shield API.	SDK response - top level
partnerTrxId	-	Your own system's reference ID, echoed back by VIDA in every response.	SDK response - per operation

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.

What to Do Based on overallStatus

Once you call GET /api/v2/verify/status?verificationId=UUID, 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. Note: If the SDK has already returned an error callback (containing failedOperation), this session will not transition to VERIFIED. Treat as not verified and prompt the user to restart. See Important Note below	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

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

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.