> 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/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 SDK finishes on the mobile device, it delivers a single JSON payload to the host app. Your app must forward this to your backend. This payload contains all the identifiers you need to call VIDA's backend APIs.

<details>

<summary><strong>Response Structure</strong></summary>

{% code expandable="true" %}

```json
{
  "verificationId"                ← Master ID for this KYC session
  "failedOperation"               ← Which operation failed; null on success

  "idCardVerificationDetails": {
    "frontCardVerificationDetails": {
      "transactionId"             ← Pass to GET /api/v2/transaction
      "partnerTrxId"              ← Your own reference for this operation
      "groupId"                   ← Same as verificationId
      "card"                      ← Document country and type
      "ocrResult"                 ← Extracted text (name, ID number, DOB...)
      "idVerificationResult"      ← Spoofing, landmark, forgery scores
      "imageQualityResult"        ← Blur and low-light scores
      "warnings"                  ← Non-blocking alerts (e.g. occlusion)
      "duplicateCheckResult"      ← Matches against previous submissions
      "attemptedTransactionIds"   ← All attempt IDs for this operation
    },
    "backCardVerificationDetails": { ... }   ← Same structure as front
  },

  "faceMatchDetails": {
    "transactionId"               ← Pass to GET /api/v2/transaction
    "partnerTrxId"                ← Your own reference for this operation
    "groupId"                     ← Same as verificationId
    "imageFaceMatchVerificationResult"
    "attemptedTransactionIds"
  },

  "livenessDetails": {
    "transactionId"               ← Use with Liveness Service API ONLY
    "sessionId"                   ← Same as verificationId
    "livenessScore"
    "manipulationScore"
    "imageData"                   ← Selfie image, base64
    "attemptedTransactionIds"
  }
}
```

{% endcode %}

</details>

{% hint style="info" %}
Fields are erased when they do not apply. For example, `warnings` only appears when there is something to report, and `backCardVerificationDetails` is absent for single-sided documents.
{% endhint %}

#### Understanding the Identifiers

The response contains four different IDs.

<table><thead><tr><th width="172.6796875">ID</th><th width="235.8359375">Scope</th><th>Use it for</th></tr></thead><tbody><tr><td>verificationId</td><td>The whole KYC session</td><td>All session-level backend calls. This is your main identifier.</td></tr><tr><td>groupId</td><td>The whole KYC session</td><td>Same value as verificationId. Returned inside each operation for convenience.</td></tr><tr><td>sessionId</td><td>The whole KYC session</td><td>Same value as verificationId. Returned inside livenessDetails.</td></tr><tr><td>transactionId</td><td>One operation</td><td>Fetching the result of that one operation from VIDA.</td></tr><tr><td>partnerTrxId</td><td>One operation</td><td>Your own tracing and reconciliation. Not used to call VIDA APIs.</td></tr></tbody></table>

#### What to Extract and Store

<table><thead><tr><th>Field</th><th width="227.99609375">Where to Find It</th><th>Used For</th></tr></thead><tbody><tr><td>verificationId</td><td>Top level</td><td><p>All backend API calls (</p><p><code>GET/api/v2/verify/status?verificationId=UUID</code>)</p></td></tr><tr><td>failedOperation</td><td>Top level</td><td>Diagnostic - identifies which operation triggered onError. Use to route error handling on your backend. Null when flow succeeded.</td></tr><tr><td>partnerTrxId</td><td>Per operation</td><td>Your own reference for tracing a single operation or attempt. Not returned at top level - use <code>verificationId</code> for session-level API calls.</td></tr><tr><td>frontCardVerificationDetails.transactionId</td><td>idCardVerificationDetails</td><td><code>GET</code> <code>/api/v2/transaction</code> - OCR/IDV front</td></tr><tr><td>backCardVerificationDetails.transactionId</td><td>idCardVerificationDetails</td><td><code>GET</code> <code>/api/v2/transaction</code> - OCR/IDV back</td></tr><tr><td>faceMatchDetails.transactionId</td><td>Top level</td><td><code>GET</code> <code>/api/v2/transaction</code> - Face Match</td></tr><tr><td>livenessDetails.transactionId</td><td>Top level</td><td>Liveness Service GET transaction (NOT My-Verify)</td></tr><tr><td>warnings[].code</td><td>Per card side</td><td>Alert logging - non-blocking.</td></tr></tbody></table>

{% hint style="info" %}
**Portrait image in ocrResult vs. documents API**

The portraitImage field inside `ocrResult` is populated on-device by the SDK only - it is not returned in API responses.

The actual portrait image (extracted from the ID card) is available via `GET` `/api/v2/transaction/{transactionId}?includeDocuments`=`true` as a presigned URL in documents.portrait. See the [*Transaction Details API*](/identity-stack/verify/kyc-mobile-sdk/integration-overview/backend-integration/transaction-details-api.md) page for details.
{% endhint %}

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

#### How the value is created

The VIDA API does not accept the same partner transaction ID twice. Every operation must therefore receive a different value. How that value is built depends on whether you send one.

If you send `partnerTransactionId` when you start the SDK

The SDK uses your value as the base and adds a suffix (extra text added to the **end** of something. So `id_f_1` added to the end of your value) for the operation and the attempt. There is no separator between your value and the suffix.

| Operation     | Suffix   | Example              |
| ------------- | -------- | -------------------- |
| ID card front | `id_f_1` | `YOUR-REF-001id_f_1` |
| ID card back  | `id_b_1` | `YOUR-REF-001id_b_1` |
| Face match    | fm\_0    | `YOUR-REF-001fm_0`   |

{% hint style="info" %}
The value in the response is not the same as the value you sent. Do not match on it directly. Store your base value on your side when you start the flow, or strip the suffix before matching.
{% endhint %}

**If you do not send partnerTransactionId**

The SDK generates a UUID for each operation, because the field is required by the VIDA API and can never be empty. In this case the three values are separate, unrelated UUIDs. They do not share a base and they have no suffix, so you cannot use them to group a session.

**How to set it**

Set `partnerTransactionId` when you build the SDK request.&#x20;

**How to use it**

* To find all data for one session, use `verificationId`.
* To find one operation or one attempt, use `partnerTrxId` together with `attemptedTransactionIds`.

#### **`clientTransactionId` is not an SDK Response field**

`clientTransactionId` is a query parameter for the ID Fraud Shield (IDFS) GET API. It does not appear in the SDK response. When you call the IDFS API, use one of these values from the SDK response as your `clientTransactionId`:

<table><thead><tr><th width="242.6953125">SDK</th><th>Use this value</th></tr></thead><tbody><tr><td>KYC SDK</td><td><code>groupId</code> or <code>verificationId</code></td></tr><tr><td>Liveness SDK</td><td><code>sessionId</code>, <code>partnerTrxId</code>, or <code>verificationId</code></td></tr></tbody></table>

#### 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.

<table><thead><tr><th width="200.6171875">Check Type</th><th>Field</th><th>Passes When</th></tr></thead><tbody><tr><td>OCR extraction</td><td>name, idNumber, dob, address, etc.</td><td>score >= threshold (confidence in extracted value)</td></tr><tr><td>Anti-spoofing</td><td>spoofingResult.recapScore, colorPrint, etc.</td><td>score &#x3C; threshold (lower = less spoof-like)</td></tr><tr><td>Forgery detection</td><td>forgeryResult.summary</td><td>score &#x3C; threshold (lower = less forgery-like)</td></tr><tr><td>Image quality</td><td>imageQualityResult.blurriness, lowLight</td><td>score &#x3C; threshold (lower = better quality)</td></tr><tr><td>Landmark detection</td><td>landmarkResult.containerResult items</td><td>score > 0 (0 = not detected / occluded)</td></tr></tbody></table>

### Sample SDK Responses&#x20;

#### Sample 1 - partnerTransactionId passed (Malaysia MyKas)

The partner sent "Transaction ID". Note the suffix on each `partnerTrxId`, and the two failed liveness attempts.

<details>

<summary><strong>Sample Response</strong></summary>

{% code expandable="true" %}

```json
{
  "idCardVerificationDetails": {
    "frontCardVerificationDetails": {
      "transactionId": "Transaction ID",
      "partnerTrxId": "Partner Trx ID",
      "groupId": "Group ID",
      "card": {
        "country": "MALAYSIA",
        "type": "MyKas",
        "isoAlpha3CountryCode": "MYS",
        "isoAlpha2CountryCode": "MY"
      },
      "ocrResult": {
        "front": {
          "data": {
            "portraitImage": "/9j/4AAQSkZJRgABAQAA",
            "idNumber": { "value": "960124-12-0015", "score": 0.998675, "threshold": 0.95 },
            "name": { "value": "SAGAR CHANDRAKANT", "score": 0.993971, "threshold": 0.95 },
            "dob": { "value": "19960124", "score": 0.998675, "threshold": 0.95 },
            "gender": { "value": "M", "score": 1, "threshold": 0.95 },
            "dateOfExpiry": { "value": "Tarikh Luput 06 Jun 2027", "score": 0.979896, "threshold": 0.95 },
            "citizenship": { "value": "BUKAN WARGANEGARA", "score": 1, "threshold": 0.95 },
            "address": { "value": "KAMPUNG TERUSAN BARU 90002 SEMPORNA SABAH", "score": 0.99412, "threshold": 0.95 }
          }
        }
      },
      "idVerificationResult": {
        "front": {
          "spoofingResult": {
            "message": "Success",
            "code": 5000,
            "recapScore": { "score": 0.102359, "threshold": 0.95 },
            "blackWhite": { "score": 0.005039, "threshold": 0.95 },
            "colorPrint": { "score": 0.450691, "threshold": 0.95 }
          },
          "landmarkResult": {
            "message": "Success",
            "code": 5000,
            "containerResult": [
              { "name": "malaysia_flag", "score": 0.9984 },
              { "name": "card_logo", "score": 0.9975 },
              { "name": "chip", "score": 0.9967 },
              { "name": "portrait", "score": 0.9966 },
              { "name": "id_number", "score": 0.9954 },
              { "name": "kad_pengenalan_header", "score": 0.9911 },
              { "name": "name", "score": 0.9894 }
            ]
          }
        }
      },
      "imageQualityResult": {
        "front": {
          "blurriness": { "score": 0.000751, "threshold": 0.95 },
          "lowLight": { "score": 0, "threshold": 0.95 }
        }
      },
      "duplicateCheckResult": { "docReferences": [], "idNumberReferences": [] },
      "attemptedTransactionIds": {
        "success": ["325d8923-8d99-4800-8c43-04faccd4d28e"]
      }
    },
    "backCardVerificationDetails": {
      "transactionId": "Transaction ID",
      "partnerTrxId": "Partner Trx ID",
      "groupId": "Group ID",
      "ocrResult": {
        "back": {
          "data": {
            "extendedIdNumber": { "value": "960124-12-0015-01", "score": 0.999561, "threshold": 0.95 }
          }
        }
      },
      "idVerificationResult": {
        "back": {
          "spoofingResult": {
            "message": "Success",
            "code": 5000,
            "recapScore": { "score": 0.108842, "threshold": 0.95 },
            "blackWhite": { "score": 0.024161, "threshold": 0.95 },
            "colorPrint": { "score": 0.297198, "threshold": 0.95 }
          },
          "landmarkResult": {
            "message": "Success",
            "code": 5000,
            "containerResult": [
              { "name": "my_logo", "score": 0.9933 },
              { "name": "coat_of_arm", "score": 0.9923 },
              { "name": "id_number", "score": 0.9835 },
              { "name": "state_registrar", "score": 0.9532 }
            ]
          }
        }
      },
      "imageQualityResult": {
        "back": {
          "blurriness": { "score": 0.000034, "threshold": 0.95 },
          "lowLight": { "score": 0, "threshold": 0.95 }
        }
      },
      "duplicateCheckResult": { "docReferences": [], "idNumberReferences": [] },
      "attemptedTransactionIds": {
        "success": ["5fad1038-f06a-47a0-9001-ef85f2ea084e"]
      }
    }
  },
  "faceMatchDetails": {
    "transactionId": "Transaction ID",
    "partnerTrxId": "Partner Trx ID",
    "groupId": "Group ID",
    "imageFaceMatchVerificationResult": {
      "data": {
        "code": 1042,
        "message": "Selfie photo matches with reference photo",
        "score": 0.940716
      }
    },
    "attemptedTransactionIds": {
      "success": ["1b80c9aa-2e0e-4a40-8d78-24927ff28ef4"]
    }
  },
  "livenessDetails": {
    "imageData": "/9j/4QCRRXhpZgAATU0A",
    "livenessScore": 0.5151107,
    "manipulationScore": 0.14462223,
    "transactionId": "Transaction ID",
    "sessionId": "Session ID",
    "attemptedTransactionIds": {
      "failed": [
        "abf7a355-feb1-459b-8be5-d429b00146bd",
        "ef1be206-5722-4cf0-af6b-0ac132a7fd61"
      ],
      "success": ["9a78a609-d18a-4063-b908-c4b28daef22b"]
    }
  },
  "verificationId": "Verification ID"
}
```

{% endcode %}

</details>

#### Sample 2 - partnerTransactionId not passed (Malaysia MyKas)

The partner sent nothing, so the SDK generated a UUID for each operation. The three `partnerTrxId` values are unrelated to each other. This sample also shows a warning on the back card.

<details>

<summary><strong>Sample Response</strong></summary>

{% code expandable="true" %}

```json
{
  "idCardVerificationDetails": {
    "frontCardVerificationDetails": {
      "transactionId": "Transaction ID",
      "partnerTrxId": "Partner Trx ID",
      "groupId": "Group ID",
      "card": {
        "country": "MALAYSIA",
        "type": "MyKas",
        "isoAlpha3CountryCode": "MYS",
        "isoAlpha2CountryCode": "MY"
      },
      "ocrResult": {
        "front": {
          "data": {
            "portraitImage": "/9j/4AAQSkZJRgABAQAA",
            "idNumber": { "value": "960124-12-0015", "score": 0.981462, "threshold": 0.95 },
            "name": { "value": "SAGAR CHANDRAKANT", "score": 0.990929, "threshold": 0.95 },
            "dob": { "value": "19960124", "score": 0.981462, "threshold": 0.95 },
            "gender": { "value": "M", "score": 1, "threshold": 0.95 },
            "dateOfExpiry": { "value": "Tarikh Luput 06 Jun 2027", "score": 0.977433, "threshold": 0.95 },
            "citizenship": { "value": "BUKAN WARGANEGARA", "score": 1, "threshold": 0.95 },
            "address": { "value": "KAMPUNG TERUSAN BARU 80002 SEMPORNA SABAH", "score": 0.997653, "threshold": 0.95 }
          }
        }
      },
      "idVerificationResult": {
        "front": {
          "spoofingResult": {
            "message": "Success",
            "code": 5000,
            "recapScore": { "score": 0.207713, "threshold": 0.95 },
            "blackWhite": { "score": 0.004726, "threshold": 0.95 },
            "colorPrint": { "score": 0.105061, "threshold": 0.95 }
          },
          "landmarkResult": {
            "message": "Success",
            "code": 5000,
            "containerResult": [
              { "name": "card_logo", "score": 0.9967 },
              { "name": "id_number", "score": 0.9952 },
              { "name": "portrait", "score": 0.9948 },
              { "name": "chip", "score": 0.9947 },
              { "name": "malaysia_flag", "score": 0.9945 },
              { "name": "kad_pengenalan_header", "score": 0.9908 },
              { "name": "name", "score": 0.9907 }
            ]
          }
        }
      },
      "imageQualityResult": {
        "front": {
          "blurriness": { "score": 0.001599, "threshold": 0.95 },
          "lowLight": { "score": 0, "threshold": 0.95 }
        }
      },
      "duplicateCheckResult": { "docReferences": [], "idNumberReferences": [] },
      "attemptedTransactionIds": {
        "success": ["9a6738d1-75f3-41db-a66f-e65ce59ce886"]
      }
    },
    "backCardVerificationDetails": {
      "transactionId": "Transaction ID",
      "partnerTrxId": "Partner Trx ID",
      "groupId": "Group ID",
      "warnings": [
        {
          "message": "Image has Occlusion, please check [state_registrar] from landmarkResult for more details",
          "code": 10429,
          "operations": ["idVerification"]
        }
      ],
      "ocrResult": {
        "back": {
          "data": {
            "extendedIdNumber": { "value": "960124-12-0015-01", "score": 0.999633, "threshold": 0.95 }
          }
        }
      },
      "idVerificationResult": {
        "back": {
          "spoofingResult": {
            "message": "Success",
            "code": 5000,
            "recapScore": { "score": 0.099637, "threshold": 0.95 },
            "blackWhite": { "score": 0.012981, "threshold": 0.95 },
            "colorPrint": { "score": 0.380484, "threshold": 0.95 }
          },
          "landmarkResult": {
            "message": "Success",
            "code": 5000,
            "containerResult": [
              { "name": "coat_of_arm", "score": 0.9948 },
              { "name": "my_logo", "score": 0.9945 },
              { "name": "id_number", "score": 0.9846 },
              { "name": "state_registrar", "score": 0 }
            ]
          }
        }
      },
      "imageQualityResult": {
        "back": {
          "blurriness": { "score": 0.000005, "threshold": 0.95 },
          "lowLight": { "score": 0, "threshold": 0.95 }
        }
      },
      "duplicateCheckResult": { "docReferences": [], "idNumberReferences": [] },
      "attemptedTransactionIds": {
        "success": ["a70b08e3-ba71-4098-b756-e6aebd38dc44"]
      }
    }
  },
  "faceMatchDetails": {
    "transactionId": "Transaction ID",
    "partnerTrxId": "Partner Trx ID",
    "groupId": "Group ID",
    "imageFaceMatchVerificationResult": {
      "data": {
        "code": 1042,
        "message": "Selfie photo matches with reference photo",
        "score": 0.914764
      }
    },
    "attemptedTransactionIds": {
      "success": ["8e155d7f-1b14-44ad-9a60-730124dc6c21"]
    }
  },
  "livenessDetails": {
    "imageData": "/9j/4QCRRXhpZgAATU0A",
    "livenessScore": 0.48649344,
    "manipulationScore": 0.08861544,
    "transactionId": "7294b7f7-296e-41ce-81d2-e64729dfe782",
    "sessionId": "75b7ee88-6e49-32f3-95f2-da04ca2670c7",
    "attemptedTransactionIds": {
      "success": ["7294b7f7-296e-41ce-81d2-e64729dfe782"]
    }
  },
  "verificationId": "Verification ID"
}
```

{% endcode %}

</details>

<br>