> 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-ktp/api-reference/async.md).

# Async

This API extracts information from the user’s KTP card image via OCR. This API initiates the OTP extraction process **asynchronously** and  returns a transaction id for which status can be checked later. 

### API  Description

<mark style="color:green;">`POST`</mark> `https://services.vida.id/verify/v1/ktp/ocr`

#### Headers

| Name                                            | Type             | Description                                                                                                |
| ----------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> |                  | <p>OAuth access token. </p><p>Get the token by calling the</p><p><strong>Get Access Token</strong> API</p> |
| Content-Type<mark style="color:red;">\*</mark>  | application/json | Format type of request body                                                                                |

#### Request Body

<table><thead><tr><th width="146.83203125">Name</th><th width="153.97265625">Type</th><th>Description</th></tr></thead><tbody><tr><td>ktp_image<mark style="color:red;">*</mark></td><td>String</td><td><p>Data URI scheme, Base64 encoded KTP image.</p><p><br>Supported image formats: JPG/JPEG.</p></td></tr></tbody></table>

#### Sample request json

<details>

<summary>Sample Request</summary>

```json
{
    "parameters": {
        "ktp_image": "base64 encoded..."
}
}
```

</details>

### **API Response**

#### OCR Request Successful

HTTP Status Code: `200`

<details>

<summary>JSON Response</summary>

```json
{
    "data": {
        "transaction_id": "faa24b24-0e1f-4ae0-9ca4-891c8a919d42"
    }
}
```

</details>

## Get Transaction Status

To retrieve the details of an OCR API request, you can use the following API provided by the VIDA Identity API. The VIDA Identity API follows an asynchronous model, where you can obtain the transaction status and details through a separate API call after the request has been processed by the verifiers or processors within the VIDA system.

### API Description

<mark style="color:green;">`POST`</mark> `https://services.vida.id/verify/v1/transaction/{transaction_id}`

#### Path Parameters

| Name                                              | Type   | Description                                         |
| ------------------------------------------------- | ------ | --------------------------------------------------- |
| transaction\_id<mark style="color:red;">\*</mark> | String | Transaction ID that is produced on KTP OCR request. |

#### Headers

| Name                                            | Type             | Description                                                                                                |
| ----------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> |                  | <p>OAuth access token. </p><p>Get the token by calling the</p><p><strong>Get Access Token</strong> API</p> |
| Content-Type<mark style="color:red;">\*</mark>  | application/json | Format type of request body                                                                                |

### **API Response**

### Transaction Status : COMPLETED

{% hint style="info" %}
KTP OCR Asynchronous API status is `COMPLETED`
{% endhint %}

HTTP Status Code: `200`

<details>

<summary>JSON Response</summary>

```json
{
	"data": {
		"result": {
			"provinsi": "JAWA BARAT",
			"kabupaten_kota": "KOTA BANDUNG",
			"golongan_darah": "",
			"agama": "ISLAM",
			"alamat": "SARIMANIS 13 TOWN HOUSE B3",
			"berlaku_hingga": "SEUMUR HIDUP",
			"kewarganegaraan": "WNI",
			"nik": "1234567890123456",
			"nama": "TEST NAME",
			"pekerjaan": "KARYAWAN SWASTA",
			"tempat_lahir": "BUKIT TINGGI",
			"kecamatan": "SUKASARI",
			"jenis_kelamin": "",
			"rt_rw": "002/006",
			"tanggal_lahir": "01-01-2001",
			"status_perkawinan": "KAWIN",
			"kelurahan_desa": "SARIJADI"

		},
		"status": "success",
		"transaction_id": "1fa03f48-12db-4abc-9c4b-c25bb7d98eab"
	}
}
```

</details>

### Transaction Status : ON Progress

{% hint style="info" %}
KTP OCR Asynchronous API status is ON Progress
{% endhint %}

HTTP Status Code: `200`

<details>

<summary>JSON Response</summary>

```json
{
    "data": {
        "transaction_id": "b00ce4b5-51e5-4823-9c36-95c6cabfc4d6"
    }
}
```

</details>

### Invalid KTP Image

Invalid image format due to below reasons:&#x20;

* The KTP object resolution is less than 300x400 pixels
* The KTP object resolution is greater than 3000x4000 pixels&#x20;
* No text in the KTP image&#x20;

**Recommendation**: Ensure to give KTP image input as the specific recommendation

HTTP Status Code: `400`

<details>

<summary>JSON Response</summary>

```json
{
	"errors": [{
		"code": 2000,
		"title": "Bad Request",
		"detail": "Invalid image format"
	}]
}
```

</details>

### Image File Size Error

{% hint style="info" %}
The image file size is greater than 2 MB.&#x20;
{% endhint %}

**Recommendation**: ensure to give image file size less than 2 MB

HTTP Status Code: `400`

<details>

<summary>JSON Response</summary>

```json
{
    "errors": [
        {
            "code": 2000,
            "title": "Bad Request",
            "detail": "Please recheck your image file size"
        }
    ]
}
```

</details>