# Biometric Verification

{% hint style="info" %}
This module only support biometric verification for indonesian identity card (KTP)
{% endhint %}

![](/files/4MXbZc0nryTfyYByi1TW)

## Endpoints

| Method | URL                                                  |
| ------ | ---------------------------------------------------- |
| POST   | `$synapses`**`/v1/identity/verification/biometric`** |

### Headers

| Header          | Value                                           |
| --------------- | ----------------------------------------------- |
| `Content-Type`  | `application/json`                              |
| `Authorization` | `Bearer` [`YOUR_API_KEY`](/authentication-1.md) |

### **Request**

{% tabs %}
{% tab title="Description" %}

| Field                                                            | Type                                                                  | Description                     |
| ---------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------- |
| <p>identityId</p><p><strong><code>(required)</code></strong></p> | <p><code>String</code><br><strong><code>(len: 16)</code></strong></p> | Nomor induk kependudukan (NIK). |
| <p>faceImage </p><p><strong><code>(required)</code></strong>     |                                                                       |                                 |

</p> | `Base64`                                                              | <p>Image binary encoded in base64 without &#x3C;data:image/png;>.<br>- Supports: JPG, JPEG, PNG, SVG<br>- Max Size: 1MB</p> |
{% endtab %}

{% tab title="Example" %}

```
{
    "identityId": "1234567890123456",
    "faceImage": "<base64>"
}
```

{% endtab %}
{% endtabs %}

#### **Testing**

{% hint style="info" %}
In the sandbox environment, we only response api call with dummy data. To get valid response data, you can use our production environment instead.
{% endhint %}

{% tabs %}
{% tab title="Face Match" %}
You can use identityId = `1234567890123456` to produce face not match result.

**Example:**

```
{
    "identityId": "1234567890123456",
    "faceImage": "<base64>"
}
```

```
{
    "message": "Identity biometric verification succeeded.",
    "data": {
        "id": "64d07984-81a8-4e79-ad16-a439f5885075",
        "identityId": "1234567890123456",
        "isValid": true,
        "isActive": true,
        "response": {
            "face": true,
            "faceSimilarity": 1.0
        }
    }
}
```

{% endtab %}

{% tab title="Face Not Match" %}
You can use any identityId except `1234567890123456` to produce face not match result.

**Example:**

```
{
    "identityId": "1234567890111111",
    "faceImage": "<base64>"
}
```

```
{
    "message": "Identity biometric verification succeeded.",
    "data": {
        "id": "cfe1732d-bd89-4e97-94c1-b3790a2952c4",
        "identityId": "1234567890111111",
        "isValid": true,
        "isActive": true,
        "response": {
            "face": false,
            "faceSimilarity": 0.24
        }
    }
}
```

{% endtab %}

{% tab title="Wrong Identity" %}
You can use any identityId except `1234567890123456` and `1234567890111111` to produce identity not valid result.

```
{
    "identityId": "1234567890123444",
    "faceImage": "<base64>"
}
```

```
{
    "message": "Identity biometric verification succeeded.",
    "data": {
        "id": "f989eae0-59a3-4a04-baac-6f16c8e7b7fd",
        "identityId": "1234567890123444",
        "isValid": false,
        "isActive": false,
        "response": {}
    }
}
```

{% endtab %}
{% endtabs %}

### **Response**

{% tabs %}
{% tab title="Description" %}

| Field                        | Type                                                             | Description                                                                                                      |
| ---------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| id                           | `String`                                                         | Unique identifier.                                                                                               |
| identityId                   | `String`                                                         | Nomor induk kependudukan (NIK).                                                                                  |
| isValid                      | `Boolean`                                                        | Return true if identityId is **exist** in the Dukcapil database.                                                 |
| isActive&#xD;                | `Boolean`                                                        | Return true if identityId is **active** in the Dukcapil database.                                                |
| response:face                | `Boolean`                                                        | <p>Return true if input face match with the face in dukcapil database.<br>- Default threshold: >= 0.75: True</p> |
| response:faceSimilarity&#xD; | <p><code>Float</code><br><strong><code>(0-1)</code></strong></p> | Similarity between the input face and the face in Dukcapil database.                                             |
| {% endtab %}                 |                                                                  |                                                                                                                  |

{% tab title="Example" %}

```
{
    "message": "Identity biometric verification succeeded.",
    "data": {
        "id": "7d7cb73b-c55a-4e93-b3d0-972058bd9ccd",
        "identityId": "1234567890123456",
        "isValid": false,
        "isActive": false,
        "response": {
            "face": false,
            "faceSimilarity": 0.36
        }
    }
}
```

{% endtab %}
{% endtabs %}

### **Errors**

{% hint style="info" %}
Please read this [page \<Responses & Errors>](/responses-and-errors.md) to know more about response.
{% endhint %}

**Error 4XX**

{% tabs %}
{% tab title="Error Type" %}

| Error Type                | Description                                                             | Is charged? |
| ------------------------- | ----------------------------------------------------------------------- | ----------- |
| invalid\_base64\_encoding | Invalid base64 encoding.                                                | False       |
| image\_too\_large         | Input image is greater than the maximum size allowed.                   | False       |
| no\_face\_detected        | No face was detected from the input image or the input image is blurry. | True        |
| request\_error            | Cannot get response from Dukcapil server.                               | False       |
| {% endtab %}              |                                                                         |             |

{% tab title="Structure" %}

```
{
   "errors":{
      "errorId": <log_id:uuid>,
      "errorType": <error_type:str>
   },
   "message": <message:str>
}
```

{% endtab %}
{% endtabs %}

**Error 5XX**

**F**or every 5XX http code response, there will be no charge.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kredibel.io/api-references/identity-verification/biometric-verification.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.