> For the complete documentation index, see [llms.txt](https://docs.kredibel.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kredibel.io/api-references/text-recognition/national-identity.md).

# National Identity

{% hint style="info" %}
This endpoint only supports Indonesian identity cards (KTP)
{% endhint %}

{% embed url="<https://youtu.be/8aZIGgGsmu0>" %}

## Endpoints

| Method | URL                           |
| ------ | ----------------------------- |
| POST   | `$vision`**`/v1/ocr/id/ktp`** |

### Headers

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

### **Request**

{% hint style="info" %}
The OCR inference time may vary. It depends on many factors, one of them is the **image size**. We recommend you to **resize** the image before sending it to Kredibel system.
{% endhint %}

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

| Field                                                       | Type                                                                | Description                                                                                                                                                                                           |
| ----------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p>image</p><p><strong><code>(Required)</code></strong></p> | \<base64:image>                                                     | <p>Image binary encoded in base64 without \<data:image/png;>.<br>- <strong>Supports:</strong> JPG, JPEG, PNG<br>- <strong>Max Size:</strong> 2MB<br>- <strong>Recommended size:</strong> 1024x768</p> |
| cardDetect                                                  | <p>Boolean</p><p><strong><code>(Default: true)</code></strong></p>  | Use card detection model                                                                                                                                                                              |
| passCardDetect                                              | <p>Boolean</p><p><strong><code>(Default: true)</code></strong></p>  | If `false`, when identity card is not detected on the image it will return an **error message**                                                                                                       |
| flipImage                                                   | <p>Boolean</p><p><strong><code>(Default: false)</code></strong></p> | If `true`, the system will flip your image                                                                                                                                                            |
| checkFlipImage                                              | <p>Boolean</p><p><strong><code>(Default: false)</code></strong></p> | If `true`, the system will check whether your image is flipped or not                                                                                                                                 |
| validateResult                                              | <p>Boolean</p><p><strong><code>(Default: false)</code></strong></p> | If `true`, you will get format validation information about result.                                                                                                                                   |
| {% endtab %}                                                |                                                                     |                                                                                                                                                                                                       |

{% tab title="Example (Recommendation)" %}
You just need to declare image field in order to use this service.

```
{
  "image": "/9j/..."
}
```

{% endtab %}

{% tab title="Example (Verbose)" %}

```
{
  "image": "string",
  "cardDetect": true,
  "passCardDetect": true,
  "flipImage": true,
  "checkFlipImage": true,
  "validateResult": true
}
```

{% endtab %}
{% endtabs %}

### **Response**

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

| Field         | Type                                                                       | Description       |
| ------------- | -------------------------------------------------------------------------- | ----------------- |
| identityId    | `String`                                                                   | Identity id (NIK) |
| fullName      | `String`                                                                   | Full name         |
| birthPlace    | `String`                                                                   | Place of birth    |
| birthDate     | <p><code>Date</code> </p><p><strong><code>(dd-mm-yyyy)</code></strong></p> | Date of birth     |
| gender        | `String`                                                                   | Gender            |
| address       | `String`                                                                   | Address           |
| province      | `String`                                                                   | Province          |
| city          | `String`                                                                   | City              |
| district      | `String`                                                                   | District          |
| village       | `String`                                                                   | Village           |
| rtrw          | `String`                                                                   | RT/RW             |
| religion      | `String`                                                                   | Religion          |
| maritalStatus | `String`                                                                   | Marital status    |
| occupation    | `String`                                                                   | Occupation        |
| nationality   | `String`                                                                   | Nationality       |

`information`

<table><thead><tr><th width="196.41311856857652">Field</th><th width="190.62541806020067">Type</th><th>Description</th></tr></thead><tbody><tr><td>tilt</td><td><code>Float</code></td><td>Tilt degree (0-360) on identity card. If it is upside-down, then the value is 180.</td></tr><tr><td>cardDetected</td><td><code>Boolean</code></td><td>Return true if out system detected identity card on the image.</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```
{
  "message": "string",
  "data": {
    "id": "string",
    "result": {
      "identityId": "string",
      "fullName": "string",
      "birthPlace": "string",
      "birthDate": "string",
      "gender": "string",
      "address": "string",
      "province": "string",
      "city": "string",
      "district": "string",
      "village": "string",
      "rtrw": "string",
      "religion": "string",
      "maritalStatus": "string",
      "occupation": "string",
      "nationality": "string"
    },
    "information": {
        "tilt": float,
        "cardDetected": boolean
    }
  }
}
```

{% 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" %}

<table><thead><tr><th width="261">Error Type</th><th width="352.3333333333333">Description</th><th>Is charged?</th></tr></thead><tbody><tr><td>invalid_base64_encoding</td><td>Invalid base64 encoding.</td><td><strong>false</strong></td></tr><tr><td>card_not_found</td><td>There is no identity card found in the image. This error only raised if you set <code>passCardDetect = False</code>.</td><td><strong>true</strong></td></tr><tr><td>text_not_found</td><td>There is no text found in the image.</td><td><strong>true</strong></td></tr><tr><td>invalid_document_type</td><td>The document sent does not appear to be the right identity type.</td><td><strong>true</strong></td></tr><tr><td>parsing_failed</td><td>System fail to parse identity card.</td><td><strong>true</strong></td></tr></tbody></table>
{% endtab %}

{% tab title="Structure" %}
In general, the error response structure is as belo&#x77;**:**

```
{
   "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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.kredibel.io/api-references/text-recognition/national-identity.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.