SDK Response

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.

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.

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 page for the full error structure.

Response Structure

{
  "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)
  }
}

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 - types: passiveLiveness, imageManipulation, colorCaptcha