> 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/income-verification/api-reference/income-verification.md).

# Income Verification

## Income Verification API

<mark style="color:green;">`POST`</mark> `https://{vida.host}/verify/v1/income-verification/transaction`

#### 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>Authentication</strong> API</p> |
| Content-Type<mark style="color:red;">\*</mark>  |      | Format type of request body                                                                              |

#### Request Body

| Name         | Type    | Description                                                              |
| ------------ | ------- | ------------------------------------------------------------------------ |
| partnerTrxId | String  | Unique transaction reference number from the client                      |
| nik          | String  | <p>NIK number of the user.</p><p>Length: 16 digits</p>                   |
| incomePeriod | String  | Income period in format of MM/YYYY                                       |
| incomeValue  | Integer | On the API request parameter, this field consists the exact income value |
| companyName  | String  | The company where the income received on the specified period.           |

**JSON Payload (Mock Data)**

```
{
    "parameters": {
        "partnerTrxnId": "{{$guid}}",
        "nik": "350100xx04200002",
        "incomePeriod": "02/2024",
        "incomeValue": 1000000,
        "companyName": "COMPANYAAAC",
        "userConsent": {
            "userIp": "226.80.211.232",
            "country": "IDN",
            "obtained": true,
            "obtainedAt": "1680700959"
    }
    }
}
```

#### Response

#### Income Verification Successful

HTTP Status Code: `200`

**JSON Response**

```
{
   "data": {
       "result": {
           "fields": [
               {
                   "field": "nik",
                   "match": true
               },
               {
                   "field": "companyName",
                   "match": true
               },
               {
                   "field": "incomePeriod",
                   "value": "12/2021"
               },
               {
                   "field": "incomeRange",
                   "value": "8.5-12.5JT"
               }
           ]
       },
       "status": "success",
       "transaction_id": "de7e75cf-4122-4c30-9113-be338fb0f357"
   }
}

```

#### Income Verification Unsuccessful&#x20;

HTTP Status Code: `401`

**JSON Response**

```
{
   "Empty string body response"
}
```

HTTP Status Code: `400`

**JSON Response**

<pre><code><strong>{
</strong><strong>   "transaction_id":"cec714fe-2879-468a-a0db-c3fe08704786"
</strong>   "errors": [
       {
           "code": 2000,
           "title": "Bad Request",
           "detail": "NIK not found"
       }
   ]
}
</code></pre>

HTTP Status Code: `400`

**JSON Response**

```
{
   "errors": [
       {
           "code": 5000,
           "title": "parameters.nik",
           "detail": "size must be between 16 and 16"
       }
   ]
}
```

HTTP Status Code: `500`

**JSON Response**

```
{
   "transaction_id":"cec714fe-2879-468a-a0db-c3fe08704786"
   "errors": [
       {
           "code": 3004,
           "title": "Service internal error",
           "detail": "Internal Server Error"
       }
   ]
}
```

HTTP Status Code: `500`

**JSON Response**

```
{
   "errors": [
       {
           "code": 3000,
           "title": "Gateway error",
           "detail": "Gateway error"
       }
   ]
}
```

HTTP Status Code: `500`

**JSON Response**

```
{
   "errors": [
       {
           "code": 1000,
           "title": "An error occurred while processing request",
           "detail": "An error occurred while processing request"
       }
   ]
}
```