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/v1/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

For details on the recommended input image, please refer to the .

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 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 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 Response

{
  ......[TRUNCATED]....
  "imageQualityResult": {
        "statusCode": 5000
    },
  ......[TRUNCATED]....
}

Error

If image Quality is fails either of any checks parameter

Sample Error Response

{
	"transactionId": "0f0454ad-abdf-4fae-84e8-ec03616ab80c",
	"partnerTrxId": "29e75e02-7808-4ec0-a2c0-026c42f57212",
	"groupId": "bccf1024-3480-4e1f-9a55-6bc36d97e478",
	"errors": [{
		"message": "Image Quality is too low, Kindly ensure the image is well lit and is placed in the right angle ",
		"code": 5014,
		"operations": [
			"idVerification"
		]
	}]
}

Note : Image quality check is implemented only for MyKad and KTP cards.

Pre processor for OCR and ID verification for KTP cards

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.

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 Response

{
  ......[TRUNCATED]....
  "imageQualityResult": {
        "statusCode": 5000
    },
  ......[TRUNCATED]....
}

Error

If image Quality is fails either of any checks parameter

Sample Error Response

{
	"transactionId": "0f0454ad-abdf-4fae-84e8-ec03616ab80c",
	"partnerTrxId": "29e75e02-7808-4ec0-a2c0-026c42f57212",
	"groupId": "bccf1024-3480-4e1f-9a55-6bc36d97e478",
	"errors": [{
		"message": "Image Quality is too low, Kindly ensure the image is well lit and is placed in the right angle ",
		"code": 5014,
		"operations": [
			"idVerification"
		]
	}]
}

Request Body

Each request is compartmentalized 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
idVerification	partnerTrxId, groupId,country, idType, idSubtype, idFrontSideImage

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.

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.

Parameter	Description
partnerTrxId	Reference ID supplied by the customer, used for identifying the transaction and it can't be duplicated.
groupId	It is a tracking id which can be used to link multiple transactions for KYC flow and can be duplicated and it can not be a null or 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

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 Schema

{
  "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 Schema Response

{
  "transactionId": "unique transation id generated by vida for the request",
  "partnerTrxId": "reference id supplied by customer",
  "groupId": "reference id to track complete KYC flow",
  "errors": [
    {
      "code": "error code",
      "message": "error message",
      "fieldName": "field name in case of any violation of payload",
      "operations": ["list of operation generated this exceptions"]
    }
  ],
   "imageQualityResult": {
        "statusCode": 5000
    },
    "card": {
    	"country": "Name of the country",
    	"type": "type of card",
    	"isoAlpha3CountryCode": "isoAlpha 3 Country code",
    	"isoAlpha2CountryCode": "isoAlpha 2 Country code"
    },
 
   "<operationName>Result":{
//For detailed response schema of each result refer Examples section//

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:

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.

If error is associated with invalid payload like missing comma, quotes making the JSON passed unreadable.

Sample Error Response

{
    "transactionId": null,
    "partnerTrxId": null,
    "groupId": null,
    "errors": [
        {
            "message": "Invalid request: Error occurred while parsing the request",
            "code": 5003
        }
    ]
}

If error is associated with an empty operation field in payload.

Sample Error Response

{
    "transactionId": null,
    "partnerTrxId": "b5d71292-be5d-416a-9b4c-75dd5500449b",
    "groupId": "113762e3-aa1a-41b1-8509-b6afb4e86427",
    "errors": [
        {
            "message": "operations Operations cannot be empty",
            "code": 5003,
            "operations": null
        }
    ]
}

If error is associated with partnerTrxId blank string is passed.

Sample Error Response

{
    "transactionId": "c73c7b04-349e-4f1e-afac-f0226b7e2d15",
    "partnerTrxId": null,
    "groupId": "1f0dd6ea-b496-4633-962f-abff400ef604",
    "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.

Sample Error Response

{
    "transactionId": "c73c7b04-349e-4f1e-afac-f0226b7e2d15",
    "partnerTrxId": "1f0dd6ea-b496-4633-962f-abff400ef604",
    "groupId": null,
    "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:

Sample Response

{
  "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:

Sample Response

{
  "errors": [
    {
      "message": "Internal Server Error",
      "code": 5005
    }
  ]
}

If error is associated with duplicate partner transactionId

Sample Response

{
    "transactionId": "14047f1d-dbda-4580-bdab-d5fcc755b012",
    "partnerTrxId": "70cc2026-60b4-4347-b06f-52e38ddf8b82",
    "groupId":"acde070d-8c4c-4f0d-9d8a-162843c10333",
    "errors": [
        {
            "message": "Invalid request: Duplicate partnerTrxId",
            "code": 5003
        }
    ]
}

Refer to the HTTP Status and Error Codes page for detailed list of status and error codes.