Overview

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.

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.

End-to-End Flow

---

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

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 /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. Note: If the SDK has already returned an error callback (containing failedOperation), this session will not transition to VERIFIED.	Wait and poll again (flow may still be running). Treat as not verified and prompt the user to restart. See Important Note below.
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.