> 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/full-details-endpoint/ocr/deduplication-check.md).
# Deduplication Check
## Purpose
VIDA's 1:N Deduplication prevents duplicate accounts by searching new applicants against a reference gallery for:
1. **Same ID** — duplicate ID Number
2. **Same Face** — duplicate portrait image across prior onboardings in the database
This prevents fraud (repeat sign-ups for promos / credit abuse, synthetic or mule recycling) and reduces Ops workload by automatically denying or routing suspicious repeats.
The feature ensures that each ID Number (`idNumber`) is uniquely associated with a single face image. It helps prevent duplicate enrollments or multiple identities being tied to the same face or ID number.
## Supported Cards
Deduplication Check is available for the following ID cards only:
| Country | ID Card | Sides Required |
| --------- | --------- | -------------- |
| Indonesia | KTP | Front |
| Malaysia | MyKAD | Front + Back |
| Malaysia | MyPR | Front + Back |
| Malaysia | MyKAS | Front + Back |
| Malaysia | MyTentera | Front + Back |
## Flow
1. **Trigger Condition**\
The duplication check is executed after all other verification operations (such as OCR and ID verification) have completed successfully — that is, no prior step should return an error. The **OCR operation is mandatory** to trigger this check.
2. **Data Used**
* The ID Number and face portrait are obtained from the OCR operation results.
* Both values are required to perform the 1:N de-duplication check.
For Indonesian KTP, the ID Number used is the NIK returned by the KTP OCR operation.
3. **Execution Steps**
The system searches for existing records with either:
1. The same face image (mapped to multiple ID Numbers), or
2. The same ID Number (mapped to multiple face images).
If a duplicate is detected, a relevant warning or error response is returned.
## API Description
`POST` `https://{vida-host}/api/v2/verify`
### Headers
Name
Type
Description
Content-Type
application/json
Format type of request body
Authentication*
String
Bearer <Token>
### Request Body
#### Malaysian ID Card (Front Side & Back Side)
Request for Front Side and Back Side
```json
{
"operations": ["ocr"],
"payload": {
"partnerTrxId": "random-uuid",
"groupId": "random-uuid",
"idType": "ID_CARD",
"country": "MYS",
"idSubtype": "MyKad",
"idFrontSideImage": "Base64 encoded image of ID front side",
"idBackSideImage": "Base64 encoded image of ID back side" //if enabled
},
"userConsent": {
"userIP": "0.0.0.0",
"country": "MYS",
"obtained": true,
"obtainedAt": "1680700959"
}
}
```
### Indonesian ID Card (Front Side Only
Request for Front Side and Back Side
```json
{
"operations": ["ocr"],
"payload": {
"partnerTrxId": "random-uuid",
"groupId": "random-uuid",
"idType": "ID_CARD",
"country": "ID",
"idSubtype": "KTP",
"idFrontSideImage": "Base64 encoded image of ID front side",
},
"userConsent": {
"userIP": "0.0.0.0",
"country": "MYS",
"obtained": true,
"obtainedAt": "1680700959"
}
}
```
{% hint style="info" %}
KTP is a single-sided document, so `idBackSideImage` is not required. The response will also contain a `front` object only inside `imageQualityResult` and `ocrResult`.
{% endhint %}
### Success Response
HTTP Status Code : `200`
#### Malaysia
Success JSON Response for Front Side and Back Side - No Duplicate Found
```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",
"card": {
"country": "MALAYSIA",
"type": "MyKad",
"isoAlpha3CountryCode": "MYS",
"isoAlpha2CountryCode": "MY"
},
"imageQualityResult": {
"front": {
"glare": {
"score": 0,
"threshold": 0.95
},
"blurriness": {
"score": 0.0008,
"threshold": 0.95
},
"lowLight": {
"score": 0.076793,
"threshold": 0.95
}
},
"back": {
"blurriness": {
"score": 0.003535,
"threshold": 0.95
},
"lowLight": {
"score": 0,
"threshold": 0.95
}
}
},
"ocrResult": {
"front": {
"data": {
"idNumber": {
"value": "ID Number from ID Card",
"score": 0.993373,
"threshold": 0.95
},
"name": {
"value": "Name",
"score": 0.999926,
"threshold": 0.95
},
"address": {
"value": "Address",
"score": 0.997141,
"threshold": 0.95
},
"dob": {
"value": "YYYY-MM-DD",
"score": 0.993373,
"threshold": 0.95
},
"citizenship": {
"value": "Citizenship",
"score": 1,
"threshold": 0.95
},
"gender": {
"value": "Gender from ID Card",
"score": 1,
"threshold": 0.95
},
"religion": {
"value": "Religion",
"score": 1,
"threshold": 0.95
},
"portraitImage": "Base64 encoded...."
}
},
"back": {
"data": {
"extendedIdNumber": {
"value": "xxxxxx-xx-xxxx-xx-xx",
"score": 0.988594,
"threshold": 0.95
}
}
}
},
"duplicateCheckResult": {
"docReferences": [
],
"idNumberReferences": []
}
}
```
Success JSON Response for Front Side and Back Side - With Warning
```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",
"warnings": [
{
"message": "Face from card associated with multiple ID Numbers.",
"code": 10502,
"operations": [
"ocr"
]
}
],
"card": {
"country": "MALAYSIA",
"type": "MyKad",
"isoAlpha3CountryCode": "MYS",
"isoAlpha2CountryCode": "MY"
},
"imageQualityResult": {
"front": {
"glare": {
"score": 0,
"threshold": 0.95
},
"blurriness": {
"score": 0.0008,
"threshold": 0.95
},
"lowLight": {
"score": 0.076793,
"threshold": 0.95
}
},
"back": {
"blurriness": {
"score": 0.003535,
"threshold": 0.95
},
"lowLight": {
"score": 0,
"threshold": 0.95
}
}
},
"ocrResult": {
"front": {
"data": {
"idNumber": {
"value": "ID Number from ID Card",
"score": 0.993373,
"threshold": 0.95
},
"name": {
"value": "Name",
"score": 0.999926,
"threshold": 0.95
},
"address": {
"value": "Address",
"score": 0.997141,
"threshold": 0.95
},
"dob": {
"value": "YYYY-MM-DD",
"score": 0.993373,
"threshold": 0.95
},
"citizenship": {
"value": "Citizenship",
"score": 1,
"threshold": 0.95
},
"gender": {
"value": "Gender from ID Card",
"score": 1,
"threshold": 0.95
},
"religion": {
"value": "Religion",
"score": 1,
"threshold": 0.95
},
"portraitImage": "Base64 encoded...."
}
},
"back": {
"data": {
"extendedIdNumber": {
"value": "xxxxxx-xx-xxxx-xx-xx",
"score": 0.988594,
"threshold": 0.95
}
}
}
},
"duplicateCheckResult": {
"docReferences": [
{
"documentId": "286c4e00-ffd2-4ec0-8d83-1f814f3bf800",
"matchScore": 0.9017925
}
],
"idNumberReferences": [
]
}
}
```
#### Indonesia
Success JSON Response - No Duplicate Found
```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",
"card": {
"country": "INDONESIA",
"type": "KTP",
"isoAlpha3CountryCode": "ID",
"isoAlpha2CountryCode": "ID"
},
"imageQualityResult": {
"front": {
"glare": { "score": 0, "threshold": 0.95 },
"blurriness": { "score": 0.0008, "threshold": 0.95 },
"lowLight": { "score": 0.076793, "threshold": 0.95 }
}
},
"ocrResult": {
"front": {
"data": {
"idNumber": { "value": "NIK from KTP", "score": 0.993373, "threshold": 0.95 },
"name": { "value": "Name", "score": 0.999926, "threshold": 0.95 },
"portraitImage": "Base64 encoded...."
// Other KTP OCR fields are returned as usual — see the KTP OCR page for the full field list
}
}
},
"duplicateCheckResult": {
"docReferences": [],
"idNumberReferences": []
}
}
```
Success JSON Response - With Warning
```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",
"warnings": [
{
"message": "Face from card associated with multiple ID Numbers.",
"code": 10502,
"operations": ["ocr"]
}
],
"card": {
"country": "INDONESIA",
"type": "KTP",
"isoAlpha3CountryCode": "ID",
"isoAlpha2CountryCode": "ID"
},
"imageQualityResult": {
"front": {
"glare": { "score": 0, "threshold": 0.95 },
"blurriness": { "score": 0.0008, "threshold": 0.95 },
"lowLight": { "score": 0.076793, "threshold": 0.95 }
}
},
"ocrResult": {
"front": {
"data": {
"idNumber": { "value": "NIK from KTP", "score": 0.993373, "threshold": 0.95 },
"name": { "value": "Name", "score": 0.999926, "threshold": 0.95 },
"portraitImage": "Base64 encoded...."
// Other KTP OCR fields are returned as usual — see the KTP OCR page for the full field list
}
}
},
"duplicateCheckResult": {
"docReferences": [
{
"documentId": "286c4e00-ffd2-4ec0-8d83-1f814f3bf800",
"matchScore": 0.9017925
}
],
"idNumberReferences": []
}
}
```
{% hint style="info" %}
Returned when the face on the KTP is already associated with a different ID Number. The transaction still succeeds, but the client should route it for review.
{% endhint %}
### Error Response
HTTP Status Code : `400`
#### Malaysia
Error JSON Response for Front Side and Back Side - With Error
```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": "Verification failed: ID Number from card associated with multiple faces.",
"code": 5803,
"operations": [
"ocr"
]
}
],
"card": {
"country": "MALAYSIA",
"type": "MyKad",
"isoAlpha3CountryCode": "MYS",
"isoAlpha2CountryCode": "MY"
},
"imageQualityResult": {
"front": {
"glare": {
"score": 0,
"threshold": 0.95
},
"blurriness": {
"score": 0.0008,
"threshold": 0.95
},
"lowLight": {
"score": 0.076793,
"threshold": 0.95
}
},
"back": {
"blurriness": {
"score": 0.003535,
"threshold": 0.95
},
"lowLight": {
"score": 0,
"threshold": 0.95
}
}
},
"ocrResult": {
"front": {
"data": {
"idNumber": {
"value": "ID Number from ID Card",
"score": 0.993373,
"threshold": 0.95
},
"name": {
"value": "Name",
"score": 0.999926,
"threshold": 0.95
},
"address": {
"value": "Address",
"score": 0.997141,
"threshold": 0.95
},
"dob": {
"value": "YYYY-MM-DD",
"score": 0.993373,
"threshold": 0.95
},
"citizenship": {
"value": "Citizenship",
"score": 1,
"threshold": 0.95
},
"gender": {
"value": "Gender from ID Card",
"score": 1,
"threshold": 0.95
},
"religion": {
"value": "Religion",
"score": 1,
"threshold": 0.95
},
"portraitImage": "Base64 encoded...."
}
},
"back": {
"data": {
"extendedIdNumber": {
"value": "xxxxxx-xx-xxxx-xx-xx",
"score": 0.988594,
"threshold": 0.95
}
}
}
},
"duplicateCheckResult": {
"docReferences": [],
"idNumberReferences": [
{
"documentId": "e8b1145e-3873-4acb-a8a1-2925e31f876f",
"matchScore": 0.521376
}
]
}
}
```
#### Indonesia
{% hint style="info" %}
Returned when the ID Number is already associated with a different face. Verification fails.
{% endhint %}
Error JSON Response - With Error
{% code expandable="true" %}
```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": "Verification failed: ID Number from card associated with multiple faces.",
"code": 5803,
"operations": ["ocr"]
}
],
"card": {
"country": "INDONESIA",
"type": "KTP",
"isoAlpha3CountryCode": "ID",
"isoAlpha2CountryCode": "ID"
},
"imageQualityResult": {
"front": {
"glare": { "score": 0, "threshold": 0.95 },
"blurriness": { "score": 0.0008, "threshold": 0.95 },
"lowLight": { "score": 0.076793, "threshold": 0.95 }
}
},
"ocrResult": {
"front": {
"data": {
"idNumber": { "value": "NIK from KTP", "score": 0.993373, "threshold": 0.95 },
"name": { "value": "Name", "score": 0.999926, "threshold": 0.95 },
"portraitImage": "Base64 encoded...."
// Other KTP OCR fields are returned as usual — see the KTP OCR page for the full field list
}
}
},
"duplicateCheckResult": {
"docReferences": [],
"idNumberReferences": [
{
"documentId": "e8b1145e-3873-4acb-a8a1-2925e31f876f",
"matchScore": 0.521376
}
]
}
}
```
{% endcode %}