> 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/smart-kyc-fraud-api/api-integration/demographic-verification.md).

# Demographic Verification

This configuration performs demographic-only verification by validating submitted personal details such as full name, national ID number, date of birth, and place of birth. While the request also includes biometric input like a selfie, only the demographic information is processed and evaluated. This model supports use cases where biometric verification is managed separately by the client or an authorized registration authority.

## **Parameters**

<table><thead><tr><th width="172">Field</th><th width="117">Type</th><th>Description</th><th>Sample Value</th></tr></thead><tbody><tr><td>partnerTrxId<mark style="color:red;">*</mark></td><td>string</td><td>Generate a unique transaction ID in UUID format and include it in the request to link your transaction with the VIDA transaction.</td><td><p>Generated random UUID by the partner. </p><p></p><p>Example:</p><p><code>1000073-c00f-4008-8005-d2ec4d9be956</code></p></td></tr><tr><td>groupId</td><td>string</td><td><p>For each NIK, partners should send a unique group ID that can be used to track related transactions across multiple fraud assessment categories. </p><p></p><p>This is mandatory for customers using <a href="/pages/HCUIJlyn2RCJnps2H9bO">Multistage verification</a></p></td><td><p>Generated random UUID by the partner. </p><p></p><p>Example:</p><p><code>8000073-d00e-9008-9005-d2ce4b9ce956</code></p></td></tr><tr><td>transactionType<mark style="color:red;">*</mark></td><td>string</td><td>Type of the transaction</td><td>In the demographic verification below transaction type is applicable:<br><code>DATA_FRAUD_ASSESSMENT</code></td></tr><tr><td>govId<mark style="color:red;">*</mark></td><td>string</td><td>The user's government ID number</td><td>Example: (NIK - Nomor Induk Kependudukan), consisting of a 16-digit number: <code>3451222123456716</code></td></tr><tr><td>govIdType</td><td>string</td><td>The type of IDCard Document. </td><td>Supported values “<code>KTP"</code></td></tr><tr><td>fullName<mark style="color:red;">*</mark></td><td>string</td><td>Users Full Name which should same with registered ID</td><td><p>User full name as per KTP.</p><p></p><p>example: <code>Johnny Rudiantara Sembiring</code></p></td></tr><tr><td>dob<mark style="color:red;">*</mark></td><td>string</td><td>User's Date of Birth</td><td>Date of Birth in <code>yyyy-mm-dd</code> format<br><br><code>1989-01-01</code></td></tr><tr><td>mobile<mark style="color:red;">*</mark></td><td>string</td><td>The user's verified mobile number with the country code, provided in E.164 format without spaces or special characters. </td><td><p>Example: <code>+6281293671234</code>. </p><p></p><p>If the mobile number isn’t available, a verified email address can be passed, however, one of the two is mandatory</p></td></tr><tr><td>email</td><td>string</td><td>The user's valid email address</td><td>Example: <code>user@example.com</code></td></tr><tr><td>consent<mark style="color:red;">*</mark></td><td>object</td><td>A user’s consented timestamp value where they agreed to consent sharing data with VIDA</td><td><p>"consent": {</p><p>      "consentedAt": "1614089870",</p><p>     "consentGiven": true</p><p>    }</p></td></tr><tr><td>idCardPhoto</td><td>base64-encoded string</td><td>A plain base64-encoded string of the user ID card Photo (i.e. KTP)</td><td>Example: <code>"/9j/4AAQSkZJRgABAQAAJAAkAAD/4QhcR..."</code></td></tr><tr><td>selfiePhoto<mark style="color:red;">*</mark><br></td><td>base64-encoded string</td><td>A base64-encoded string of the user's selfie for facial recognition and face-match checks, adhering to specified image standards. </td><td>Example: <code>"/9j/4AAQSkZJRgABAQAAJAAkAAD/4QhcR..."</code></td></tr></tbody></table>

<mark style="color:red;">\*</mark>required

### **Extended Demographic Parameters**

Extended demographic parameters refer to additional identity-related fields that go beyond the standard personal information typically used in identity verification. These may include data such as address, nationality, gender, marital status, mother’s maiden name, and family card number. Including extended parameters can enhance the accuracy of verification, support higher assurance levels, or fulfill regulatory and business requirements for more detailed profiling.

<table><thead><tr><th width="179.062255859375">Field</th><th width="117">Type</th><th>Description</th><th>Sample Value</th></tr></thead><tbody><tr><td>pob</td><td>string</td><td>User's Place of Birth</td><td><code>Jakarta</code></td></tr><tr><td>motherMaidenName</td><td>string</td><td>The user's mother’s maiden name as per IDCard.</td><td><code>Siti Elizabeth</code></td></tr><tr><td>gender</td><td>string</td><td>The user's gender</td><td><code>Laki-Laki</code></td></tr><tr><td>occupation</td><td>string</td><td>The user's listed occupation</td><td><code>Petani</code></td></tr><tr><td>maritalStatus</td><td>string</td><td>The user's marital status as per IDCard.</td><td><code>Belum Kawin</code></td></tr><tr><td>familyCardNo</td><td>string</td><td>The user's family card number (if idCardType is KTP)</td><td><code>3451222123456716</code></td></tr><tr><td>address</td><td>string</td><td>The user's residential address as per KTP (Alamat).</td><td><code>Jl. Pasti Cepat A7/66</code></td></tr><tr><td>village</td><td>string</td><td>The user's residential village as per KTP (Kelurahan/Desa).</td><td><code>Pegadungan</code></td></tr><tr><td>villageCode</td><td>string (4 digit)</td><td>The user's residential village code (Kelurahan/Desa).</td><td><code>1001</code></td></tr><tr><td>district</td><td>string</td><td>The user's residential district as per KTP (Kecamatan).</td><td><code>Kalideres</code></td></tr><tr><td>districtCode</td><td>string (2 digit)</td><td>The user's residential district code (Kecamatan).</td><td><code>10</code></td></tr><tr><td>city</td><td>string</td><td>The user's city of residence as per KTP (Kabupaten/Kota)</td><td><code>Jakarta Barat</code></td></tr><tr><td>cityCode</td><td>string (2 digit)</td><td>The user's city code of residence (Kabupaten/Kota)</td><td><code>13</code></td></tr><tr><td>province</td><td>string</td><td>The user's province of residence as per KTP (Provinsi).</td><td><code>DKI Jakarta</code></td></tr><tr><td>provinceCode</td><td>string (2 digit)</td><td>The user's province code of residence (Provinsi).</td><td><code>23</code></td></tr></tbody></table>

## **Sample Request**

<details>

<summary>Sample Request (Main Parameters Only)</summary>

```json
{
    "partnerTrxId": "{{random-UUID}}", //must be unique for every transaction.8705-29ca45b0ef32",
    "transactionType": "DATA_FRAUD_ASSESSMENT",
    "groupId": "{{UUID4}}", //Required for Multistage Verification
    "mobile": "+62857555754",
    "email": "useremail@emailprovider.com",
    "govId": "Gov ID from ID Card",
    "govIdType": "KTP",
    "fullName":"UserGDAA",
    "dob": "YYYY-MM-DD",
    "selfiePhoto": "{{selfieID}}", //recorded but not verified
    "consent": {
        "consentedAt": "1614089870",
        "consentGiven": true
    }
}
```

</details>

<details>

<summary>Sample Request (With Extended Demog)</summary>

```json
{
  // MANDATORY FIELDS
  "partnerTrxId": "{{random-UUID}}", //must be unique for every transaction
  "groupId": "{{UUID4}}", //Required for Multistage verification
  "transactionType": "DATA_FRAUD_ASSESSMENT",
  "govId": "{{GOV_ID}}",
  "govIdType": "KTP",
  "fullName": "{{FULL_NAME}}",
  "mobile": "{{MOBILE_E164}}",
  "email": "{{EMAIL}}",
  "dob": "{{DOB_YYYY_MM_DD}}",
  "selfiePhoto": "{{SELFIE_BASE64}}",
  "consent": { "consentedAt": {{UNIX_EPOCH_SECONDS}}, "consentGiven": true },
 
   //OPTIONAL FIELDS
  "address": "{{ADDRESS}}",
  "district": "{{DISTRICT_NAME}}",
  "districtCode": "{{DISTRICT_CODE}}",
  "village": "{{VILLAGE_NAME}}",
  "villageCode": "{{VILLAGE_CODE}}",
  "city": "{{CITY_NAME}}",
  "cityCode": "{{CITY_CODE}}",
  "province": "{{PROVINCE_NAME}}",
  "provinceCode": "{{PROVINCE_CODE}}",
  "familyCardNo": "{{FAMILY_CARD_NO}}",
  "maritalStatus": "{{MARITAL_STATUS}}",
  "gender": "{{GENDER}}",
  "occupation": "{{OCCUPATION}}",
  "motherMaidenName": "{{MOTHER_MAIDEN_NAME}}",
  "pob": "{{PLACE_OF_BIRTH}}"
  ,
}
```

</details>

## Sample Response

HTTP Status Code: `200`

**JSON Response**

<details>

<summary>Sample Response (Main Parameters Only)</summary>

```json
{
    "data": {
        "authenticationLevel": "IAL2", 
        "certificate": {
            "level": 2,
            "detail": "Certificate with long term validity is issued and its utilization is bound to the certificate requesting client"
        },
        //authenticationLevel & certificate field should NOT be used programmatically
        //authenticationLevel & certificate result depends on verification data availability & its RA level
        //Instead, customer should define successful transaction based on Status Check API, score & fraudAssessment status,
        
        "transactionType": "DATA_FRAUD_ASSESSMENT",
        "transactionId": "514d736c-c23a-4f2f-bd35-f92535559c3c",
        "groupId": "{{UUID4}}" //Same value as the one sent in the request
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "full_name",
                "result": 1.0
            },
            {
                "name": "dob",
                "result": 1.0
            },
            {
                "name": "nik",
                "result": 1.0
            }
        ]
    }
}
```

</details>

<details>

<summary>Sample Response (With Extended Demog)</summary>

```json
{
    "data": {
        "authenticationLevel": "IAL2",
        "certificate": {
            "level": 2,
            "detail": "Certificate with long term validity is issued and its utilization is bound to the certificate requesting client"
        },
        //authenticationLevel & certificate field should NOT be used programmatically
        //authenticationLevel & certificate result depends on verification data availability & its RA level
        //Instead, customer should define successful transaction based on Status Check API, score & fraudAssessment status,
        
        "transactionType": "DATA_FRAUD_ASSESSMENT",
        "transactionId": "57f1a7b7-1503-4d92-b742-0be7ca4270b9",
        "groupId": "{{UUID4}}" //Same value as the one sent in the request
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "full_name",
                "result": 1.0
            },
            {
                "name": "dob",
                "result": 1.0
            },
            {
                "name": "mother_maiden_name",
                "result": 1.0
            },
            {
                "name": "pob",
                "result": 1.0
            },
            {
                "name": "address",
                "result": 1.0
            },
            {
                "name": "family_card_no",
                "result": 1.0
            },
            {
                "name": "village",
                "result": 1.0
            },
            {
                "name": "district",
                "result": 1.0
            },
            {
                "name": "city",
                "result": 1.0
            },
            {
                "name": "province",
                "result": 1.0
            },
            {
                "name": "nik",
                "result": 1.0
            }
        ]
    }
}
```

</details>

#### Sample Response Value Explanation

<table><thead><tr><th width="181.95330810546875">Parameters</th><th>Description</th></tr></thead><tbody><tr><td><strong>full_name</strong></td><td>Degree of match between the provided full name and stored data.</td></tr><tr><td><strong>dob</strong></td><td>Degree of match between the provided date of birth (DOB) and stored data.</td></tr><tr><td><strong>fraudAssessment</strong></td><td>Indicates whether the fraud assessment process is completed.</td></tr><tr><td><strong>authenticationLevel</strong></td><td> <a href="/pages/imLVFT18M11v0vr29Nau">Assurance level </a>of the authentication process. <br><br>authenticationLevel field should not be used programatically to determine a successful transaction. Instead, customer should define successful transaction based on Status Check API, score &#x26; fraudAssessment status</td></tr><tr><td><strong>certificate</strong></td><td>Details regarding the certificate's trustworthiness for digital signatures.</td></tr><tr><td><strong>groupId</strong></td><td>Returned only for <a href="/pages/HCUIJlyn2RCJnps2H9bO">Multistage Verification</a>. The groupId passed on the request body</td></tr></tbody></table>

## 1. Accept Responses

HTTP Status Code: `200`

Status : `SUCCESS`

### Main Parameters

<details>

<summary>JSON Response</summary>

```json
{
    "data": {
        "authenticationLevel": "IAL2",
        "certificate": {
            "level": 2,
            "detail": "Certificate with long term validity is issued and its utilization is bound to the certificate requesting client"
        },
        "transactionType": "DATA_FRAUD_ASSESSMENT",
        "transactionId": "unique transaction id(UUID) generated to identify this transaction",
        "groupId": "{{as received in request}}",
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "full_name",
                "result": 1.0
            },
            {
                "name": "dob",
                "result": 1.0
            },
            {
                "name": "nik",
                "result": 1.0
            }
        ]
    }
}
```

</details>

### Extended Demography Parameters

<details>

<summary>JSON Response</summary>

```json
{
    "data": {
        "authenticationLevel": "IAL2",
        "certificate": {
            "level": 2,
            "detail": "Certificate with long term validity is issued and its utilization is bound to the certificate requesting client"
        },
        "transactionType": "DATA_FRAUD_ASSESSMENT",
        "transactionId": "unique transaction id (UUID) generated to identify this transaction",
        "groupId": "{{as received in request}}",
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "full_name",
                "result": 1.0
            },
            {
                "name": "dob",
                "result": 1.0
            },
            {
                "name": "mother_maiden_name",
                "result": 1.0
            },
            {
                "name": "pob",
                "result": 1.0
            },
            {
                "name": "address",
                "result": 1.0
            },
            {
                "name": "family_card_no",
                "result": 1.0
            },
            {
                "name": "village",
                "result": 1.0
            },
            {
                "name": "district",
                "result": 1.0
            },
            {
                "name": "city",
                "result": 1.0
            },
            {
                "name": "province",
                "result": 1.0
            },
            {
                "name": "nik",
                "result": 1.0
            }
        ]
    }
}
```

</details>

### motherMaidenName as Additional Parameter

<details>

<summary>JSON Response</summary>

```json
{
    "data": {
        "authenticationLevel": "IAL2",
        "certificate": {
            "level": 2,
            "detail": "Certificate with long term validity is issued and its utilization is bound to the certificate requesting client"
        },
        "transactionType": "DATA_FRAUD_ASSESSMENT",
        "transactionId": "unique transaction id(UUID) generated to identify this transaction",
        "groupId": "{{as received in request}}",
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "full_name",
                "result": 1.0
            },
            {
                "name": "dob",
                "result": 1.0
            },
            {
                "name": "mother_maiden_name",
                "result": 1.0
            },
            {
                "name": "nik",
                "result": 1.0
            }
        ]
    }
}
```

</details>

## 2. Reject Responses

HTTP Status Code: `200`

Status : `SUCCESS`

### Demographic Parameters

<details>

<summary>JSON Response</summary>

```json
{
    "data": {
        "transactionType": "DATA_FRAUD_ASSESSMENT",
        "transactionId": "b7c5309b-7172-4538-9b68-b5aa6896c968",
        "groupId": "{{as received in request}}",
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "full_name",
                "result": 0.375
            },
            {
                "name": "dob",
                "result": 1.0
            },
            {
                "name": "nik",
                "result": 1.0
            }
        ]
    }
}
```

</details>

### Extended Demographic Parameters

<details>

<summary>JSON Response</summary>

```json
{
    "data": {
        "transactionType": "DATA_FRAUD_ASSESSMENT",
        "transactionId": "0d964e9d-5e38-4493-8eb2-535ea77cb134",
        "groupId": "{{as received in request}}",
        "assessmentResults": [
            {
                "name": "full_name",
                "result": 1.0
            },
            {
                "name": "dob",
                "result": 1.0
            },
            {
                "name": "mother_maiden_name",
                "result": 0.42799999999999994
            },
            {
                "name": "nik",
                "result": 1.0
            }
        ],
        "fraudAssessment": "COMPLETED",
        "authenticationLevel": "AAL1",
        "certificate": {
            "level": 1,
            "detail": "The certificate has not been issued."
        }
    }
}
```

</details>

## 3. Error Responses

### 3.1 Required parameters are missing

This error occurs when one or more mandatory fields are not provided in the request. The response includes details of the missing parameter in the detail field.

HTTP Status Code: `400`

Status : `ERROR`

**JSON Response**

{% tabs %}
{% tab title="Missing DOB" %}

```json
{
    "errors": [
        {
            "code": 1006,
            "title": "must not be blank",
            "detail": "dob"
        }
    ]
}
```

{% endtab %}

{% tab title="Missing fullName" %}

```json
{
    "errors": [
        {
            "code": 1006,
            "title": "must not be blank",
            "detail": "fullName"
        }
    ]
}
```

{% endtab %}

{% tab title="Missing (dob and fullName)" %}

```json
{
    "errors": [
        {
            "code": 1006,
            "title": "must not be blank",
            "detail": "dob"
        },
        {
            "code": 1006,
            "title": "must not be blank",
            "detail": "fullName"
        }
        
    ]
}
```

{% endtab %}
{% endtabs %}