> 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/sync-api.md).

# Sync API

The Identity Verification API is a service provided by VIDA that allows partners to confirm the identity of their users. This is done by sending the user's details, such as their name, dob, and govt ID numbers, along with the user informations that need to be verified in a request to the API. When the API is invoked, it performs a set of checks and validations on the provided information to verify the user's identity. The checks and validations may include comparing the provided information against a set of official government records, checking for any discrepancies or inconsistencies, and performing a facial recognition analysis to compare the user's photo with their ID photo.

Once the verification process is complete, the API returns a unique transaction ID (`eventId`) which can be used to track the status of the verification process. The API also sends a response indicating the outcome of the verification, such as approval or rejection, along with any additional information or feedback that may be relevant.\
\
The API can be integrated with the partner's platform or application, allowing them to perform identity verification as part of their own user registration or onboarding process. This eliminates the need for users to visit a separate website or portal to verify their identity. Additionally, the API also support [webhook](#webhook), which can be configured to notify partners of the status of the verification process and any updates in real-time.

## API  Description

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

#### 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 for Main Parameters

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

#### 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 (if idCardType is KTP) |
| 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 Responses

### Verification Successful

The demographic verification, liveness verification, and face-match verification are successful for the provided user details.&#x20;

The e-certificate will be successfully issued if the following conditions are met:&#x20;

* The user demographic information is match with authoritative source.
* The user selfie photo information is match with authoritative source.
* The user selfie photo liveness score is equal to or less than its threshold score.&#x20;

**EventId**: When an identity verification request is received by VIDA, the VIDA system auto-generates a reference id that is also known as eventId. It is a unique id per request and that can be used to track the identity verification status and transaction details.

HTTP Status Code: `200`

<details>

<summary>JSON Response</summary>

```json
{
	"data": {
		"eventId": "1000073-c00f-4008-8005-29000000000f32",
		"fields": [
			{
				"score": 0.01113,
				"field": "liveness"
			}

		],
		"certificateIssued": 200
	}
}
```

</details>

### Demographic Parameter Mismatch

The demographic parameters is not match with Authoritative source.&#x20;

**Recommendation**: The partner must check all the demographic parameters before sending it.&#x20;

**Information**: If any of the provided demographic did not match with the authoritative source data, the demographic verification will fail. Therefore, the identity verification status will also be “False.”

HTTP Status Code: `200`

<details>

<summary>JSON Response</summary>

```json
{
	"data": {
		"eventId": "1000073-c00f-4008-8005-29000000000f32",
		"fields": [{
				"score": 0.01113,
				"field": "liveness"
			}

		],
		"certificateIssued": 444
	}
}
```

</details>

### Selfie Mismatch

`selfiePhoto` does not match with the authoritative source.&#x20;

**Recommendation**: The partner must send a correct selfie photo of the user.

HTTP Status Code: `200`

<details>

<summary>JSON Response</summary>

```json
{
	"data": {
		"eventId": "1000073-c00f-4008-8005-29000000000f32",
		"fields": [
			{
				"score": 0.01113,
				"field": "liveness"
			}

		],
		"certificateIssued": 444
	}
}
```

</details>

### Selfie - Not Live

The selfie is not a live image.&#x20;

**Recommendation**: The partner must check that the provided selfie is a live image and not a hacked image.

HTTP Status Code: `200`

<details>

<summary>JSON Response</summary>

```json
{
    "data": {
        "eventId": "be22451d-56a5-4798-ae01-afa2efcf7847",
        "fields": [
            {
                "score": 0.97,
                "field": "liveness"
            }
        ],
        "certificateIssued": 444
    }
}
```

</details>

### Face Occluded/Missing in Selfie

There is no face in the selfie image/face is occluded.&#x20;

**Recommendation**: The partner must check that the selfie should contain the user's face.

HTTP Status Code: `200`

<details>

<summary>JSON Response</summary>

```json
{
    "data": {
        "eventId": "5ec9b091-9142-4e21-88dc-0777f706fa67",
        "fields": [
            {
                "score": -100.0,
                "field": "liveness"
            }
        ],
        "certificateIssued": 444
    }
}
```

</details>

### Certificate Issuance Failed

Certificate issuance has failed. The `certificateIssued` parameter in the response will have `443`

HTTP Status Code: `200`

<details>

<summary>JSON Response</summary>

```json
{
    "data": {
        "eventId": "be22451d-56a5-4798-ae01-afa2efcf7847",
        "fields": [
            {
                "score": 0.97,
                "field": "liveness"
            }
        ],
        "certificateIssued": 443
    }
}
```

</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
{
    "errors": [
        {
            "code": 1006,
            "title": "Missing required parameter",
            "detail": "Incorrect values found in request body"
        }
    ]
}
```

</details>

### Bad Request - Missing Required Parameter&#x20;

The input request body is not well formatted.&#x20;

**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 - Invalid GovID&#x20;

The input format for GovID (NI) is invalid.&#x20;

**Recommendation:**

The partner must check that the GovID (NIK) must be 16 digits of a number.

HTTP Status Code: `400`

<details>

<summary>JSON Response</summary>

```json
{
    "errors": [
        {
            "code": 1006,
            "title": "Invalid GovID entered, must be 16 digit",
            "detail": "govId"
        }
    ]
}
```

</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.&#x20;

**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.&#x20;

**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.&#x20;

**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": "must not be blank",
            "detail": "govId"
        }
    ]
}
```

</details>

### Bad Request - Invalid Base64 String

The base64 string of the user selfie is not valid in the API request.&#x20;

**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.&#x20;

**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.&#x20;

**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.&#x20;

**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.&#x20;

**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>