> 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/indonesia-verification/integration/api/api-reference/async-api.md).

# Async API

This API initiates the verification process asynchronously and returns `eventId` for which the status can be checked later.

{% hint style="info" %}
Identity verification async API can be enabled on the requirement, please contact the [VIDA support team](mailto:vida.support.id) to enable it.
{% endhint %}

## API Description

<mark style="color:green;">`POST`</mark> [`https://services-sandbox.vida.id/main/v3/services/kyc`](https://services-sandbox.vida.id/main/v3/services/kyc)

**Headers**

| Name                                            | Type             | Value                                                                                                                                                                                                                                                                                 |
| ----------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> |                  | <p>OAuth access token. Get the token by calling the</p><p><a href="https://github.com/vidaid-infraops/gitbook-imports/blob/main/VIP%20-%20Verify,%20Sign,%20Auth/verify/e-kyc/integration/api/api-reference/broken-reference/README.md"><strong>Get Access Token</strong></a> API</p> |
| Content-Type<mark style="color:red;">\*</mark>  | application/json | Format type of request body                                                                                                                                                                                                                                                           |

**Request Body for Main Parameters**

| Name                                           | Type    | Description                                                                                                                                                                                                                                                                   |
| ---------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| mobile<mark style="color:red;">\*</mark>       | String  | <p>User mobile number with country code without space.</p><p>1. \[+] \[country code] \[ user phone number]</p><p>2. No special characters.</p><p>3. Provide phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164 format</a>.</p><p>example: +6281293671234</p> |
| email<mark style="color:red;">\*</mark>        | String  | <p>User valid email address</p><p>example: <everest@gmail.com></p>                                                                                                                                                                                                            |
| govId<mark style="color:red;">\*</mark>        | String  | <p>(Government Id - User NIK number)</p><p>16 digit number of Nomor Induk Kependudukan (Government Issued Id- NIK)</p>                                                                                                                                                        |
| fullName<mark style="color:red;">\*</mark>     | String  | <p>User full name as per KTP.</p><p>example: Johnny Rudiantara Sembiring</p>                                                                                                                                                                                                  |
| dob<mark style="color:red;">\*</mark>          | String  | <p>User date of birth as per KTP.</p><p>Provide user date of birth In YYYY-MM-DD format.</p><p>example: 1975-08-16</p>                                                                                                                                                        |
| selfiePhoto<mark style="color:red;">\*</mark>  | String  | <p>Format: base64 string</p><p>Provide the user selfie for whom face recognition should be performed. The image is also sent for face-match checks.</p><p><strong>Face-match check</strong>: Verifying the user selfie with authoritative source record image.</p>            |
| consent<mark style="color:red;">\*</mark>      | object  | <p>"consent": {</p><p>"consentedAt": "1614089870",</p><p>"consentGiven": true</p><p>}</p>                                                                                                                                                                                     |
| ConsentGiven<mark style="color:red;">\*</mark> | Boolean | <p>Consent provided by the partner to record and verify the user details.</p><p>Possible values: True, False</p>                                                                                                                                                              |
| consentedAt<mark style="color:red;">\*</mark>  | String  | This value represents the time at which the user consented to do their identity verification. The value is [Epoch time](https://www.epoch101.com/) in seconds                                                                                                                 |
| partnerTrxId                                   | String  | Reference ID supplied by the customer, used for identifying the transaction and ***it can't be duplicated.***                                                                                                                                                                 |

#### Request Body for Extended Parameters

| Name             | Type   | Description                                                      |
| ---------------- | ------ | ---------------------------------------------------------------- |
| motherMaidenName | String | User mother’s maiden name as per KTP.                            |
| familyCardNo     | String | User's family card number as per family card (KK/Kartu Keluarga) |
| pob              | String | User's place of birth as per KTP                                 |
| address          | String | User residential address as per KTP                              |
| village          | String | User residential village as per KTP                              |
| district         | String | User residential district as per KTP                             |
| city             | String | User residential city as per KTP                                 |
| province         | String | User residential province as per KTP                             |

## **API Sample Request**

<details>

<summary>Sample Request</summary>

```json
{
    "partnerTrxId": "8705-29ca45b0ef32",
    "mobile": "+62123456788",
    "govId": "3511000101806300",
    "govIdType": "KTP",
    "fullName": "Userbcde", 
    "dob": "1989-01-01",
    "selfiePhoto": "/9j/4AAQSkZJRgAB...",
    "consent": {
        "consentedAt": "1614089870",
        "consentGiven": true
    }
}
```

</details>

## **API Response**

### Verification Request Created

Asynchronous Identity Verification request is created and `eventId` is returned to get the verification request details.

HTTP Status Code: `200`

<details>

<summary>JSON Response</summary>

```json
{
    "data": {
        "eventId": "99a173f7-b1fd-4495-8787-59940b9a1efc"
    }
}
```

</details>

### UnAuthorised - Invalid Credentials

The client secret key parameter or its value is either missing or incorrect. The partner must check the client's secret key before sending the request.

HTTP Status Code: `401`

<details>

<summary>JSON Response</summary>

```json
{
    "data": {
        "eventId": "99a173f7-b1fd-4495-8787-59940b9a1efc"
    }
}
```

</details>

### Bad Request - Missing Required Parameter

The input request body is not well formatted.

**Recommendation:**

The partner must check that the API request body is well-formatted before sending the request.

HTTP Status Code: `400`

<details>

<summary>JSON Response</summary>

```json
{
    "errors": [
        {
            "code": 1006,
            "title": "Missing required parameter",
            "detail": "Incorrect values found in request body"
        }
    ]
}
```

</details>

### Bad Request - Request Parameter Not Allowed

When a partner tries to send a parameter in the request that is not configured, a similar error message will appear.

**Example:** Here, Place of birth (pob) parameter is not configured for the partner.

HTTP Status Code: `400`

<details>

<summary>JSON Response</summary>

```json
{
    "errors": [
        {
            "code": 1006,
            "title": "Invalid request data",
            "detail": "Field(s) pob not allowed"
        }
    ]
}
```

</details>

### Bad Request - Invalid Request Parameter

The phone number parameter value is either missing or in an incorrect format in the API request body.

**Recommendation**: The partner must send a valid mobile parameter and its value in the API request body. To know more, see the parameter required format in the request body table.

HTTP Status Code: `400`

<details>

<summary>JSON Response</summary>

```json
{
    "errors": [
        {
            "code": 1006,
            "title": "Invalid phone number",
            "detail": "mobile"
        }
    ]
}
```

</details>

### Bad Request - Mandatory Request Parameter Missing

The Mandatory parameter is missing in the request body.

**Recommendation :** The partner must send all the mandatory details in the request along with other required details.

HTTP Status Code: `400`

**Example** : The govId (NIK) is a mandatory field. The partner must send the user govId (NIK) details in the request along with other required details.

<details>

<summary>JSON Response</summary>

```json
{
    "errors": [
        {
            "code": 1006,
            "title": "Invalid phone number",
            "detail": "mobile"
        }
    ]
}
```

</details>

### Bad Request - Invalid Base64 String

The base64 string of the user selfie is not valid in the API request.

**Recommendation**: The partner must check the user selfie base64 string value before sending the request.

HTTP Status Code: `400`

<details>

<summary>JSON Response</summary>

```json
{
    "errors": [
        {
            "code": 1006,
            "title": "Invalid image base64 String",
            "detail": "selfiePhoto"
        }
    ]
}
```

</details>

### Bad Request - Invalid Format

Date of birth request body parameter value is in incorrect format.

**Recommendation**: The partner must send the date of birth in the required format as mentioned in the request body.

HTTP Status Code: `400`

<details>

<summary>JSON Response</summary>

```json
{
    "errors": [
        {
            "code": 1006,
            "title": "Missing required parameter",
            "detail": "Incorrect Date value"
        }
    ]
}
```

</details>

### Bad Request - One or More Mandatory Parameters Missing

One or more required parameters are missing. The configuration mandates to send all the mandatory parameters in the request.

**Recommendation**: The partner must send all the mandatory parameters in the request body.

HTTP Status Code: `400`

<details>

<summary>JSON Response</summary>

```json
{
    "errors": [
        {
            "code": 1006,
            "title": "Invalid request data",
            "detail": "All of the fields email,dob,fullName,mobile,selfiePhoto,address,familyCardNo,motherMaidenName,village,district,city,province should be provided"
        }
    ]
}
```

</details>

### URL Not Found

The API endpoint URL is not valid.

**Recommendation**: The partner must send a valid endpoint URL.

HTTP Status Code: `404`

<details>

<summary>JSON Response</summary>

```json
{
    "timestamp": "2022-11-07T10:43:44.429+00:00",
    "status": 404,
    "error": "Not Found",
    "message": "",
    "path": "/services/kyc"
}
```

</details>

### Internal Server Error

An internal server occurred, please try after some time.

**Recommendation**: The partner should send the API request after some time.

HTTP Status Code: `500`

<details>

<summary>JSON Response</summary>

```json
{
    "errors": [
        {
            "code": 1000,
            "title": "Verification failed",
            "detail": "An internal error occurred. Please try again"
        }
    ]
}
```

</details>

## Get Verification Status and Verification Data

You can obtain the transaction status and details through a separate API call after the request has been processed.

To get the verification status please follow the[ Verification Status API](https://github.com/vidaid-infraops/gitbook-imports/blob/main/VIP%20-%20Verify,%20Sign,%20Auth/verify/e-kyc/integration/api/api-reference/broken-reference/README.md) and to get verification data please follow the [Verification Data API](https://github.com/vidaid-infraops/gitbook-imports/blob/main/VIP%20-%20Verify,%20Sign,%20Auth/verify/e-kyc/integration/api/api-reference/broken-reference/README.md).