> 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/document-ai/ocr-and-document-verification/ocr-and-document-verification-v2/summary-endpoint/integration-overview.md).
# Integration Overview
This endpoint provides a concise version of the main response, ideal for clients who are not interested in detailed analysis or confidence scores but require a quick, boolean-like status for the request's success or failure. It is especially useful when only the essential information such as card details and verification status is needed, without the need for detailed image quality metrics or scores.
* The aggregate size of all the requests should be less than 10 mb.
* In the event that the request as a whole was accepted but there were errors processing part of the request (e.g., an incorrectly Base64 encoded image), the client will receive a `400` response code and will receive a response with combination of success and errors listed in the result.
## API Description
`POST` `https://{vida-host}/api/v2/verify/summary`
#### Headers
| Name | Type | Description |
|---|
| Authentication* | string | OAuth access token. Get the token by calling the 'Get access token' API. |
| Content-Type | application/JSON | Format type of request body |
{% hint style="info" %}
For details on the **recommended input image,** please refer to the [Broken mention](broken://pages/hYQqdPJXYt1PRzaqeipe).
{% endhint %}
***
## **Pre-Processing Steps**
Similar to the main API, the summary endpoint also follows validation steps before executing the requested operation. However, the response is minimal, focusing on overall success without detailed information on image quality or verification stages.
Below is the preprocessing steps:
### **Pre processor for OCR and ID verification for MyKad cards**
**Card classification check**
* Purpose: The purpose of this step is to get the card type for the idFrontSideImage and idBackSideImage \*(*if enabled)* provided in request.
* Conditions: This step will execute only for either of operations OCR or IdVerification, or both
**Image quality check**
* Purpose: The purpose of this step is to assess if the idFrontSideImage and idBackSideImage (*if enabled)* provided in request is as per quality standard. It will evaluate the image for three parameters.
* Glare: Checks if there is a Glare in the image captured
* Blurriness: Checks if the image has blurriness.
* Low Light: To check whether the image captured has under exposure
* Conditions: This step will execute only for either of operations OCR or IdVerification.
**Response Overview:**
The summary endpoint returns a concise response with a simple status code indicating the result of image quality checks and ID verification. Instead of providing detailed scores or positional data, the response focuses on high-level results.
**Success**
Image quality passes all parameter checks.
**Image Quality Result:** After the image quality check, an `imageQualityResult` object is provided in the response, containing statusCode `5000`. Here is a snippet of the response:
Sample API Response
```json
{
......[TRUNCATED]....
"imageQualityResult": {
"front": {
"statusCode": 5000
}
},
......[TRUNCATED]....
}
```
#### **Error**
If image Quality is fails either of any checks parameter
Sample API Response
{
"transactionId": "unique transaction id generated to identify this transaction",
"partnerTrxId": "partner transaction id submitted by customer in request",
"groupId": "partner group id submitted by customer in request",
"errors": [
{
"message": "Quality check failed. Image is too blurry.",
"code": 5202,
"operations": [
"idVerification"
]
}
}
{% hint style="info" %}
**Note**:
1. Image quality check is implemented only for Malaysian and KTP cards.
{% endhint %}
### **Pre processor for OCR and ID verification for KTP cards**
**Image quality check**
* Name: Document Image Quality Check
* Purpose: The purpose of this step is to assess if the idFrontSideImage provided in request is as per quality standard. It will evaluate the image for three parameters.
* Over Exposure: To check whether the image captured has Over exposure.
* Blurriness: Checks if the image has blurriness.
* Low Light: To check whether the image captured has under exposure.
* Card Dimension: Checks card width, height and card co-ordinates.
* Conditions: This step will execute only for either of operations OCR or IdVerification.
* Response:
* Success: If image quality is passed all checks parameter
{% hint style="info" %}
**Note**: For sample for KTP IQA response please refer to the API Reference docs.
{% endhint %}
### Request Body
Each request is compartmentalised into three critical components: operations, payload, and consent.
**Operations**:
This portion of the request specifies the actions or tasks to be executed for a particular request or transaction. Currently, the VIDA service supports four main operations - OCR (Optical Character Recognition) and ID Verification. The operation(s) chosen dictate what tasks will be carried out during the processing of the request.
Here are the fields required for the two supported operations:
| Operation | Required Fields |
|---|
| OCR | partnerTrxId, groupId, country, idType, idSubtype, idFrontSideImage, idBackSideImage (if enabled) |
| idVerification | partnerTrxId, groupId, country, idType, idSubtype, idFrontSideImage, idBackSideImage (if enabled) |
**Payload**:
The Payload encompasses the necessary data required to execute the operations specified in the request. The required parameters within the Payload are dynamic and depend on the chosen operations. If any of these parameters are missing, invalid, or incorrectly formatted, the service will reject the request. This rejection is indicated by an error code and a 400 HTTP response. As such, it is crucial to ensure the inclusion and validity of all necessary parameters in the Payload.
{% hint style="info" %}
Note: There are particular checks on the request body, for example: No duplicate value allowed for the partner transaction id, some checks on the country and idType, idSubType. The details are mentioned in the below table.
{% endhint %}
| Parameter | Description |
|---|
| partnerTrxId | Reference ID supplied by the customer, used for identifying the transaction and it can't be duplicated. |
| groupId | For each unique end user, partners must send a unique group ID that allows tracking of related transactions across different KYC steps.
Example: If a customer performs both OCR-IDV and Liveness-FaceMatch checks, the same groupId should be sent for both transactions. This allows the system to link them to the same end user.
The value can be duplicated and it must not be null or an empty string.
|
| country | Country code in ISO 3166 -1 alpha-3 format, indicating the origin of the ID document. |
| idType | The type of ID to be processed (currently, the supported type is "ID_CARD", "PASSPORT", "DRIVING_LICENSE"). |
| idSubtype | Subtype for idType (current possible values include "MyKad", "MyTentera", "MyKas", "MyPR", "KTP", "N/A"). |
| idFrontSideImage | Base64 encoded image of the front side of the ID |
| idBackSideImage | Base64 encoded image of the back side of the ID *(if enabled) |
**Consent**:
The Consent component contains data related to the end user's consent. This may include confirmation that the user has agreed to the terms of service, data processing agreements, or other necessary permissions.
| Parameter | Requirement |
| ---------- | ----------- |
| country | Required |
| obtained | Required |
| obtainedAt | Required |
| userIp | Optional |
These three parts form the body of a request and all must be properly structured and present for a request to be successfully processed.
#### Schema
Sample API Request
```json
{
"operations": ["operationName1", "operationName2"],
"payload": {
"partnerTrxId": "reference id supplied by customer",
"groupId" : "reference id to track complete KYC flow",
"idType": "current supported Idtype: ID_CARD",
"country": "country code",
"idSubtype": "This parameter is required for IdType, Current Possible Values are MyKad",
"idFrontSideImage": "Base64 encoded image of ID front side",
},
"userConsent": {
"userIp": "user IP Address",
"country": "Country Code",
"obtained": "Boolean",
"obtainedAt": "EPOCH Time"
}
}
```
### Response
Overview of the verification results. This response will include only essential transaction details and a boolean-style success or failure result for each operation.
**Response Structure:**
* **Transaction Details**: Contains identifiers related to the transaction.
* `transactionId`: A unique identifier generated for this request.
* `partnerTrxId`: Transaction ID supplied by the partner.
* `groupId`: A tracking ID that links multiple transactions for the KYC flow.
* **Errors**: This section provides details about any issues that occurred during processing. If there are no errors, this section will be omitted.
**Results:** Result blocks are generated for each operation included in the request, each associated with its respective operation. The mapping for these blocks is as follows:
* `ocr: ocrResult`
* `IQA : imageQualityResult`
* `Card details : card`
* `idVerification: idVerificationResult`
The response from the API follows this schema:
Sample API Response
```json
{
"transactionId": "unique transation id generated by vida for the request",
"partnerTrxId": "reference id supplied by customer",
"groupId": "reference id to track complete KYC flow",
"imageQualityResult": {
"front": {
"statusCode": 5000
},
"back": {
"statusCode": 5000
}
},
"card": {
"country": "MALAYSIA",
"type": "MyKad",
"isoAlpha3CountryCode": "MYS",
"isoAlpha2CountryCode": "MY"
},
"idVerificationResult": {
"front": {
"statusCode": 5000
},
"back": {
"statusCode": 5000
}
},
"ocrResult": {
"front": {
"idNumber": "ID Number from ID card",
"name": "Name",
"address": "Address",
"dob": "YYYY-MM-DD",
"citizenship": "Country",
"gender": "Gender from ID Card",
"religion": "Religion"
},
"back": {
"extendedIdNumber": "xxxxxx-xx-xxxx-xx-xx"
}
}
}
```
*This structure offers a concise overview of the verification process, without detailed warnings or extended operation-specific information, making it suitable for clients who want a high-level response.*
***
### Error Response Structure in Different Scenarios
The error response structure varies based on different scenarios. Here are the possible scenarios and their corresponding error response structures:
{% hint style="info" %}
Note: These examples are provided to illustrate different **error scenario responses**. There may be **additional scenarios** with a similar response structure but different **error messages**.
{% endhint %}
**If error is associated with invalid payload like missing comma, quotes making the JSON passed unreadable.**
API Response
{
"transactionId": "unique transaction id generated to identify this transaction",
"partnerTrxId": "partner transaction id submitted by customer in request",
"groupId": "partner group id submitted by customer in request",
"errors": [
{
"message": "Invalid request: Error occurred while parsing the request",
"code": 5003
}
]
}
**If error is associated with an empty operation field in payload.**
API Response
{
"transactionId": "unique transaction id generated to identify this transaction",
"partnerTrxId": "partner transaction id submitted by customer in request",
"groupId": "partner group id submitted by customer in request",
"errors": [
{
"message": "operations Operations cannot be empty",
"code": 5003,
"operations": [
"ocr",
"idVerification"
]
}
]
}
**If error is associated with partnerTrxId blank string is passed.**
API Response
```json
{
"transactionId": "unique transaction id generated to identify this transaction",
"partnerTrxId": "partner transaction id submitted by customer in request",
"groupId": "partner group id submitted by customer in request",
"errors": [
{
"message": "partnerTrxId must not be blank",
"code": 5001,
"fieldName": "payload.partnerTrxId",
"operations": [
"ocr",
"idVerification"
]
}
]
}
```
**If error is associated with groupId blank string is passed.**
API Response
```json
{
"transactionId": "unique transaction id generated to identify this transaction",
"partnerTrxId": "partner transaction id submitted by customer in request",
"groupId": "partner group id submitted by customer in request",
"errors": [
{
"message": "groupId must not be blank",
"code": 5001,
"fieldName": "payload.groupId",
"operations": [
"ocr",
"idVerification"
]
}
]
}
```
**If error is associated with operations calls**
In this scenario, the error is associated with an operation call, such as when no card is detected in an OCR operation:
API Response
```json
{
"errors": [
{
"message": "No Card Detected",
"code": 5101,
"operations": ["ocr"]
}
]
}
```
**If any error occurred which is not associated with any operation**
This type of error represents an internal server error, not associated with any specific operation:
API Response
```json
{
"errors": [
{
"message": "Internal Server Error",
"code": 5005
}
]
}
```
**If error is associated with duplicate partner transactionId**
API Response
```json
{
"transactionId": "unique transaction id generated to identify this transaction",
"partnerTrxId": "partner transaction id submitted by customer in request",
"groupId": "partner group id submitted by customer in request",
"errors": [
{
"message": "Invalid request: Duplicate partnerTrxId",
"code": 5003
}
]
}
```
{% hint style="info" %}
Refer to the[ HTTP Status and Error Codes page](/identity-stack/verify/document-ai/ocr-and-document-verification/ocr-and-document-verification-v2/http-status-and-error-codes.md) for detailed list of status and error codes.
{% endhint %}