> 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/sdk-response.md). # SDK Response {% hint style="info" %} **Purpose Of This Page** Explains the structure of the SDK JSON payload, what each field means, and which values to extract before making backend API calls. {% endhint %} ### Step 1 - Parse the SDK Response When the KYC Web SDK finishes in the browser, it delivers a single JSON payload to your host app through the `onComplete` callback. Your app must forward this to your backend. This payload contains all the identifiers you need to call VIDA's backend APIs. {% hint style="info" %} **Note**: On failure, the SDK invokes `onError` instead, which returns an errors array (plus any results completed before the failure). The Web SDK does not use a top-level `failedOperation` field - use the errors array to route error handling on your backend. See the [*Callback Methods*](/identity-stack/verify/kyc-web-sdk/customization/callback-methods.md) page for the full error structure. {% endhint %}
Response Structure {% code expandable="true" %} ```json { "verificationId" ← Master ID for this KYC session (derived from backend groupId) "failedOperation" ← Which operation failed; null on success "docVerificationResult": { "verificationId", ← Same as top-level verificationId "transactionId", ← Pass to GET /api/v2/transaction?transactionId=UUID "partnerTrxId" ← Your own reference for this operation "card", ← Document country and type "imageQualityResult": { ← Blur and low-light scores "front", "back" }, "idVerificationResult": { ← Spoofing, landmark, forgery scores "front", "back" }, "ocrResult": { ← Extracted text (name, ID number, DOB...) "front", "back" }, "attemptedTransactionIds" ← All attempt IDs (only present when retries occurred) }, "faceMatchVerificationResult": { "code", "message", "score", ← Face match similarity score "transactionId" ← Pass to GET /api/v2/transaction?transactionId=UUID }, "livenessVerificationResult": { "score", ← Liveness score "liveImage", ← Boolean — true if a live photo "message", "code", "transactionId", ← Use with Liveness Service ONLY (NOT My-Verify) "base64Image", ← Captured selfie (on-device only) "livenessScores" ← Per-method scores — color flash only (see Response Variations) } } ``` {% endcode %}
#### What to Extract and Store | Field | Where to Find It | Used For | | -------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | verificationId | Top level | All backend API calls (`GET` `/api/v2/verify/status?verificationId=UUID`, `GET` `/api/v1/evaluation`) | | failedOperation | Top level | Identifies which operation triggered onError. When this field is NOT null, the SDK session is considered terminal for this `verificationId` - no further retries or resume are possible. Use this as your primary signal for real-time failure detection. There is no need to poll the GET KYC Status API for failure cases; the API may continue to show IN\_PROGRESS until the backend timeout expires. Null when the flow succeeded. | | partnerTrxId | Per operation | Your own reference for tracing a single operation or attempt. Not returned at top level - use `verificationId` for session-level API calls. | | docVerificationResult.transactionId | docVerificationResult (default mode) | `GET` `/api/v2/transaction?transactionId=UUID` - `OCR/IDV` | | docFrontSideVerificationResult.transactionId | Top level (per-side mode) | `GET` /api/v2/transaction?transactionId=UUID - OCR/IDV front | | docBackSideVerificationResult.transactionId | Top level (per-side mode) | `GET` `/api/v2/transaction?transactionId=UUID` - OCR/IDV back | | faceMatchVerificationResult.transactionId | Top level | `GET` `/api/v2/transaction?transactionId=UUID` - Face Match | | livenessVerificationResult.transactionId | Top level | Liveness Service `GET` transaction (NOT My-Verify) | | warnings\[].code | Per card side/ faceMatchVerificationResult.warnings | Alert logging - non-blocking | #### partnerTrxId in detail It is per operation, not per session. `verificationId` is the ID for the whole KYC session. `partnerTrxId` is the ID for one operation inside that session. You will find `partnerTrxId` in three places: * `frontCardVerificationDetails` * `backCardVerificationDetails` * `faceMatchDetails` It is not returned in `livenessDetails`. *** #### Portrait Image: `ocrResult` vs. Documents API The `portrait image` and `base64Image` fields returned in the SDK payload are populated on-device by the SDK only — they are **not** returned in API responses. To retrieve the actual portrait image (extracted from the ID card), call: `GET` `/api/v2/transaction?transactionId={UUID}&includeDocuments=true` The portrait is returned as a presigned URL in `documents.portrait`. Document URLs are not included by default — you must pass `&includeDocuments=true` to receive them. See the Transaction Details API page for details. *** #### Using SDK Response for KYC Decision-Making The SDK callback response is your primary signal for real-time decision-making: #### Success Callback (`failedOperation` is null) * The SDK flow completed successfully. * Call `GET /api/v2/verify/status?verificationId=UUID` to confirm the `VERIFIED` status. * The API should return `overallStatus: VERIFIED`. #### Error Callback (`failedOperation` is NOT null) * The SDK session is terminal for this `verificationId`. * You may treat this as a failed verification immediately. * There is no need to wait for the GET KYC Status API to update. * The `IN_PROGRESS` status on this `verificationId` will auto-expire to `FAILED` after the configured timeout, but you should not wait for this transition to make your decision. #### Understanding Scores Each OCR field, verification check, and image quality check includes a score and a threshold. Use the table below to determine what constitutes a passing result. | Check Type | Field | Passes When | | ---------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | OCR extraction | name, idNumber, dob, address, etc. | score >= threshold (confidence in extracted value) | | Anti-spoofing | spoofingResult.recapScore, colorPrint, etc. | score < threshold (lower = less spoof-like) | | Forgery detection | forgeryResult.summary | score < threshold (lower = less forgery-like) | | Image quality | imageQualityResult.blurriness, lowLight | score < threshold (lower = better quality) | | Landmark detection | landmarkResult.containerResult items | score > 0 (0 = not detected / occluded) | | Liveness (Color Flash) | livenessScores\[].score per method | See [*Callback Methods*](/identity-stack/verify/kyc-web-sdk/customization/callback-methods.md) - types: passiveLiveness, imageManipulation, colorCaptcha |