Kartu Tanda Penduduk (KTP)

KTP is an identity card issued in Indonesia.

Before using the KTP OCR service, please review the OCR limitations that may affect text recognition accuracy.

KTP Object

Name
status
Type
string
Description
Enum code indicating the status of the reading result.
1. SUCCESS
2. NO_FILE
3. FILE_INVALID_FORMAT
4. FAILED
Name
reason
Type
string
Description
A human-readable message providing more details about the reading result.
Name
qualities
Type
object
Description
When the reading is successful, you don't need to care about qualities. When our engine thinks that there's a problem in the uploaded image, this qualities object will tell you what's wrong.
- Name
  is_blurred
  Type
  boolean
  Description
  If true, the image uploaded is too blurry. Try re-uploading with a less blurry image.
- Name
  is_bright
  Type
  boolean
  Description
  If true, the image uploaded is too bright. Try re-uploading with normal lighting.
- Name
  is_copy
  Type
  boolean
  Description
  If true, the image uploaded is from a photocopier. Try re-uploading the real one.
- Name
  is_cropped
  Type
  boolean
  Description
  If true, the image uploaded is cropped. Try re-uploading the whole image.
- Name
  is_dark
  Type
  boolean
  Description
  If true, the image uploaded is too dark. Try re-uploading with normal lighting.
- Name
  is_flash
  Type
  boolean
  Description
  If true, the image uploaded contains flash obstructing parts of the image. Try re-uploading with normal lighting.
- Name
  is_ktp
  Type
  boolean
  Description
  If true, the image uploaded is considered a KTP. That's good.
- Name
  is_rotated
  Type
  boolean
  Description
  If true, the image uploaded is rotated. Try re-uploading with portrait orientation.
- Name
  is_taken_from_screen
  Type
  boolean
  Description
  If true, the image uploaded is captured / taken from screen. Try re-uploading with image that captured real ktp.
Name
images
Type
object
Description
Contains the cropped image (in base64 format) of KTP's face and signature. This field may not be present in all responses.
- Name
  photo
  Type
  string
  Description
  Face in base64 format.
- Name
  sign
  Type
  string
  Description
  Signature in base64 format.
Name
read
Type
object
Description
Contains the reading for each KTP fields. Each field contains:
- confidence (number): Overall confidence score in percentage
- value (string): The processed/extracted value
- value_original (string): The original text as read from the document
- confidence_text (number): Text recognition confidence in percentage
- polygon (array): Array of coordinate pairs [x, y] representing the bounding box of the field
- page_index (number): Page number where the field was found (0-indexed)
The response format for the /ocr/v1/ktp endpoint may differ from other OCR endpoints. This endpoint returns additional metadata including polygon coordinates and page indices.
- Name
  agama
  Type
  object
  Description
  Religion
- Name
  alamat
  Type
  object
  Description
  Address.
- Name
  berlaku_hingga
  Type
  object
  Description
  Expiration date (may also appear as berlakuHingga in some responses).
- Name
  golongan_darah
  Type
  object
  Description
  Blood type (may also appear as golonganDarah in some responses).
- Name
  jenis_kelamin
  Type
  object
  Description
  Sex (may also appear as jenisKelamin in some responses).
- Name
  kecamatan
  Type
  object
  Description
  Prefecture.
- Name
  kelurahan_desa
  Type
  object
  Description
  District (may also appear as kelurahanDesa in some responses).
- Name
  kewarganegaraan
  Type
  object
  Description
  Nationality.
- Name
  kota_kabupaten
  Type
  object
  Description
  City (may also appear as kotaKabupaten in some responses).
- Name
  nama
  Type
  object
  Description
  Name.
- Name
  nik
  Type
  object
  Description
  ID number.
- Name
  pekerjaan
  Type
  object
  Description
  Job.
- Name
  provinsi
  Type
  object
  Description
  Province.
- Name
  rt_rw
  Type
  object
  Description
  Neighborhood number (may also appear as rtRw in some responses).
- Name
  status_perkawinan
  Type
  object
  Description
  Marital status (may also appear as statusPerkawinan in some responses).
- Name
  tanggal_lahir
  Type
  object
  Description
  Date of birth (may also appear as tanggalLahir in some responses).
- Name
  tempat_lahir
  Type
  object
  Description
  Place of birth (may also appear as tempatLahir in some responses).
- Name
  foto
  Type
  object
  Description
  Photo field containing the base64 encoded image of the photo. This field includes polygon coordinates but may not include confidence_text or value_original fields.
- Name
  tanda_tangan
  Type
  object
  Description
  Signature field containing the base64 encoded image of the signature. This field includes polygon coordinates but may not include confidence_text or value_original fields.

POST/ocr/v1/ktp

The response format for this endpoint (/ocr/v1/ktp) differs from other OCR endpoints. This endpoint returns additional metadata including polygon coordinates, page indices, original values, and text confidence scores for each field. The response format may change in future updates.

Detects a valid KTP image and returns the information as text with bounding box coordinates and confidence scores.

Required parameter

Name
image
Type
file (.png, .jpg, .jpeg, .pdf, .tiff)
Description
The image file for the KTP.

Sample Request

POST

/ocr/v1/ktp


    1
2
3
4
5
6

    import { Vision } from '@glair/vision';

const vision = new Vision({ apiKey: 'api-key', username: 'username', password: 'password' });

// Image can be a file path, base64 string, or Blob/File object
await vision.ocr.ktp({ image: '/path/to/image/KTP.jpg' });

Sample Response


    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249

    {
    "status": "SUCCESS",
    "reason": "File Successfully Read",
    "read": {
        "provinsi": {
            "confidence": 89.44,
            "polygon": [
                [172, 15],
                [368, 15],
                [368, 31],
                [172, 31]
            ],
            "value": "JAWA BARAT",
            "page_index": 0,
            "confidence_text": 99.95,
            "value_original": "PROVINSI JAWA BARAT"
        },
        "nik": {
            "confidence": 90.18,
            "polygon": [
                [110, 60],
                [334, 60],
                [334, 79],
                [110, 79]
            ],
            "value": "3201241107690002",
            "page_index": 0,
            "confidence_text": 97.13,
            "value_original": "3201241107690002"
        },
        "alamat": {
            "confidence": 86.65,
            "polygon": [
                [120, 135],
                [322, 135],
                [322, 148],
                [120, 148]
            ],
            "value": "JL RAYA CISEENG NO. 12 BLOK A",
            "page_index": 0,
            "confidence_text": 99.23,
            "value_original": "JL RAYA CISEENG NO. 12 BLOK A"
        },
        "rt_rw": {
            "confidence": 86.17,
            "polygon": [
                [120, 150],
                [168, 150],
                [168, 162],
                [120, 162]
            ],
            "value": "001/002",
            "page_index": 0,
            "confidence_text": 100,
            "value_original": "001/002"
        },
        "agama": {
            "confidence": 84.95,
            "polygon": [
                [120, 193],
                [160, 193],
                [160, 205],
                [120, 205]
            ],
            "value": "ISLAM",
            "page_index": 0,
            "confidence_text": 100,
            "value_original": "ISLAM"
        },
        "nama": {
            "confidence": 86.83,
            "polygon": [
                [121, 87],
                [223, 87],
                [223, 100],
                [121, 100]
            ],
            "value": "LUKMAN WIJAYA",
            "page_index": 0,
            "confidence_text": 99.85,
            "value_original": "LUKMAN WIJAYA"
        },
        "kecamatan": {
            "confidence": 86.2,
            "polygon": [
                [121, 178],
                [179, 178],
                [179, 190],
                [121, 190]
            ],
            "value": "CISEENG",
            "page_index": 0,
            "confidence_text": 99.96,
            "value_original": "CISEENG"
        },
        "jenis_kelamin": {
            "confidence": 85.69,
            "polygon": [
                [121, 132],
                [121, 119],
                [182, 119],
                [182, 132]
            ],
            "value": "LAKI-LAKI",
            "page_index": 0,
            "confidence_text": 99.99,
            "value_original": "LAKI-LAKI"
        },
        "foto": {
            "confidence": 96.56,
            "polygon": [
                [361, 60],
                [482, 60],
                [482, 211],
                [361, 211]
            ],
            "value": "iVBORw0KGgoAAAANSUhEUgAAAHkAAACXCAIAAAC+...",
            "page_index": 0
        },
        "status_perkawinan": {
            "confidence": 89.62,
            "polygon": [
                [120, 207],
                [209, 207],
                [209, 220],
                [120, 220]
            ],
            "value": "BELUM KAWIN",
            "page_index": 0,
            "confidence_text": 96.52,
            "value_original": "BELUM KAWIN"
        },
        "pekerjaan": {
            "confidence": 89.37,
            "polygon": [
                [120, 223],
                [206, 223],
                [206, 235],
                [120, 235]
            ],
            "value": "WIRASWASTA",
            "page_index": 0,
            "confidence_text": 99.98,
            "value_original": "WIRASWASTA"
        },
        "kewarganegaraan": {
            "confidence": 86.56,
            "polygon": [
                [120, 238],
                [146, 238],
                [146, 250],
                [120, 250]
            ],
            "value": "WNI",
            "page_index": 0,
            "confidence_text": 100,
            "value_original": "WNI"
        },
        "berlaku_hingga": {
            "confidence": 89.25,
            "polygon": [
                [121, 253],
                [185, 253],
                [185, 266],
                [121, 266]
            ],
            "value": "11-07-2019",
            "page_index": 0,
            "confidence_text": 99.98,
            "value_original": "11-07-2019"
        },
        "tanggal_lahir": {
            "confidence": 87.47,
            "polygon": [
                [120, 104],
                [239, 104],
                [239, 117],
                [120, 117]
            ],
            "value": "13-03-1989",
            "page_index": 0,
            "confidence_text": 99.97,
            "value_original": "BOGOR, 13-03-1989"
        },
        "tempat_lahir": {
            "confidence": 87.47,
            "polygon": [
                [120, 104],
                [239, 104],
                [239, 117],
                [120, 117]
            ],
            "value": "BOGOR",
            "page_index": 0,
            "confidence_text": 99.97,
            "value_original": "BOGOR, 13-03-1989"
        },
        "golongan_darah": {
            "confidence": 69.09,
            "polygon": [
                [322, 118],
                [333, 118],
                [333, 130],
                [322, 130]
            ],
            "value": "O",
            "page_index": 0,
            "confidence_text": 89.55,
            "value_original": "0"
        },
        "kelurahan_desa": {
            "confidence": 90.59,
            "polygon": [
                [121, 164],
                [194, 164],
                [194, 176],
                [121, 176]
            ],
            "value": "CIBENTANG",
            "page_index": 0,
            "confidence_text": 99.99,
            "value_original": "CIBENTANG"
        },
        "kota_kabupaten": {
            "confidence": 89.65,
            "polygon": [
                [180, 33],
                [351, 33],
                [351, 49],
                [180, 49]
            ],
            "value": "KABUPATEN BOGOR",
            "page_index": 0,
            "confidence_text": 100,
            "value_original": "KABUPATEN BOGOR"
        },
        "tanda_tangan": {
            "confidence": 83.04,
            "polygon": [
                [367, 248],
                [468, 248],
                [468, 296],
                [367, 296]
            ],
            "value": "iVBORw0KGgoAAAANSUhEUgAAAGUAAAAwCAIAAACHXSPcAAAjzElEQVR4nD27+fMlx3EfmFdV9fW+1wxmcBMET4EyRUskLW9shFfy...",
            "page_index": 0
        }
    }
}

POST/ocr/v1/ktp/qualities

Read KTP with Qualities

Returns the qualities of KTP image and the KTP information as text.

Required parameter

Name
image
Type
file (.png, .jpg, .jpeg, .pdf, .tiff)
Description
The image file for the KTP.

Sample Request

POST

/ocr/v1/ktp/qualities


    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

    // Minimum Node 18. Save the code as 'index.mjs' and run it by executing 'node index.mjs'
import { readFileSync } from "fs";

const url = 'https://api.vision.glair.ai/ocr/v1/ktp/qualities';
const basicAuth = 'Basic ' + Buffer.from('USERNAME' + ':' + 'PASSWORD').toString('base64');
const apiKey = 'API_KEY';

const formData = new FormData();
formData.append('image', new Blob([readFileSync('/path/to/image/KTP.jpeg')]));

const config = {
  method: 'POST',
  headers: {
    Authorization: basicAuth,
    'x-api-key': apiKey,
  },
  body: formData,
};

const response = await fetch(url, config);
console.log(await response.json());

Sample Response


    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

    {
    "status": "SUCCESS",
    "reason": "File Successfully Read",
    "qualities": {
        "is_blurred": false,
        "is_bright": false,
        "is_copy": false,
        "is_cropped": false,
        "is_dark": false,
        "is_flash": false,
        "is_ktp": true,
        "is_rotated": false,
        "is_taken_from_screen": false
    },
    "images": {
        "photo": "/9j/4AAQSkZJRgABAQAAAQABAAD/...",
        "sign": "/9j/4AAQSkZJRgABAQAAAQABAAD/..."
    },
    "read": {
      // KTP fields
    }
}

Request ID

An associated request identifier is generated for every request made to this endpoint. This value can be found in the response headers under Request-Id

Responses

Various responses for this endpoint, in addition to general responses specified in Errors.

`200 - OK`

Request with readable KTP image

Response


    1
2
3
4
5

    {
  "status": "SUCCESS",
  "reason": "File Successfully Read",
  //...,
}

`200 - OK`

Request with non KTP File

Response


    1
2
3
4
5

    {
  "status": "SUCCESS",
  "reason": "File successfully read. Some fields are invalid.",
  //...,
}

`200 - Unrecognized Document Type`

(With Qualities Only) Request with unrecognized document type

Response


    1
2
3
4
5

    {
  "status": "UNRECOGNIZED_DOCUMENT_TYPE",
  "reason": "Unrecognized document type detected.",
  //...,
}

`200 - Multiple Documents`

(With Qualities Only) Request with multiple documents

Response


    1
2
3
4
5

    {
  "status": "MULTIPLE_DOCUMENTS_DETECTED",
  "reason": "Multiple documents detected.",
  //...,
}

`400 - Bad Request`

Request without form-data image

Response


    1
2
3
4
5

    {
  "status": "NO_FILE",
  "reason": "No file in request body",
  //...,
}

`415 - Unsupported Media Type`

Request with non-image file format

Response


    1
2
3
4
5

    {
  "status": "FILE_INVALID_FORMAT",
  "reason": "Failed to process invalid request",
  //...,
}