# eKYC Income verification

`POST /omni/externalVerification/income`

Base URL: `https://demo-api.incodesmile.com` — Incode demo environment

This endpoint performs an eKYC income check

## Path & query parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `api-version` | header | string | yes |  |

## Request body

**Example** Check income: ``` { "country": "br", "taxId": "32757350803" // cpf 76433943853. 32757350803 } ```

Content-Type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `taxId` | string | yes | 11 digit CPF |
| `country` | string | yes | Two letter Alpha-2 country code. (Must be BR). |

## Responses

### 200

Example:
```
{
    "income": [
        {
            "key": "employment_type",
            "status": "success",
            "sub_label": "Type",
            "message": "ENTREPRENEUR | BUSINESS OWNER"
        },
        {
            "key": "employment_sector",
            "status": "success",
            "sub_label": "Sector",
            "message": "PRIVATE - 4639701 - COMERCIO ATACADISTA DE PRODUTOS ALIMENTICIOS EM GERAL"
        },
        {
            "key": "income_range",
            "status": "success",
            "sub_label": "Estimated Income Range",
            "message": "9240-13200"
        }
    ]
}
```

Response body (`application/json`):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kyc` | array[EkycVerification] |  |  |
| `kyc.key` | string |  | Indicates a type of risk, such as addressRiskLevel. The overallLevel key name is an aggregate risk score for all risk types. It can be used to obtain a single risk score for a whole result set. |
| `kyc.status` | string |  | Explains the risk level, ie "low", "medium", or "high". When doing a social security number check, the API will return status values of nomatch, fuzzy or exact. Fuzzy means there is plausible match between the name and the social security number, like Dave and David both resolve to the same SSN. |
| `kyc.sub_label` | string |  | Additional info on the status. |
| `kyc.message` | string |  |  |
| `kyc.reasonCodes` | array[string] |  |  |
| `income` | array[EkycVerification] |  |  |
| `income.key` | string |  | Indicates a type of risk, such as addressRiskLevel. The overallLevel key name is an aggregate risk score for all risk types. It can be used to obtain a single risk score for a whole result set. |
| `income.status` | string |  | Explains the risk level, ie "low", "medium", or "high". When doing a social security number check, the API will return status values of nomatch, fuzzy or exact. Fuzzy means there is plausible match between the name and the social security number, like Dave and David both resolve to the same SSN. |
| `income.sub_label` | string |  | Additional info on the status. |
| `income.message` | string |  |  |
| `income.reasonCodes` | array[string] |  |  |
| `additionalVerificationInfo` | object |  |  |
| `additionalVerificationInfo.creditFileDetails` | object |  |  |
| `additionalVerificationInfo.creditFileDetails.creditFileNumber` | string |  |  |
| `additionalVerificationInfo.creditFileDetails.creditFileCreationDate` | string |  |  |

### 400

Example:
```
{
    "timestamp": 1722948860110,
    "status": 400,
    "error": "Both country and taxId are mandatory fields must be submitted for successful request",
    "message": "Both country and taxId are mandatory fields must be submitted for successful request",
    "path": "/omni/externalVerification/income"
}
```

Response body (`application/json`):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `timestamp` | integer (int64) |  | UTC timestamp in milliseconds |
| `status` | integer (int32) |  | Custom error code or HTTP status code |
| `error` | string |  | HTTP status error |
| `message` | string |  | Custom error message |
| `path` | string |  | Endpoint path |
| `details` | object |  | Custom error details |