---
title: "eKYC Income verification"
url: "https://developer.incode.com/api-reference/externalverification-income/"
section: "api-reference"
group: "eKYC"
version: "v1.1"
status: "live"
endpoint: "POST /omni/externalVerification/income"
---
# 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

| 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` | AdditionalVerificationInfo |  |  |
| `additionalVerificationInfo.creditFileDetails` | CreditFileDetails |  |  |
| `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 |

## Code samples

Generated from this endpoint's method, path, and the conventional Incode headers. The base URL is the Incode demo environment; replace `<YOUR_API_KEY>` with a key for your region.

### cURL

```bash
curl -X POST https://demo-api.incodesmile.com/omni/externalVerification/income \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "api-version: 1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "taxId": "",
    "country": ""
  }'
```

### Node

```js
const res = await fetch("https://demo-api.incodesmile.com/omni/externalVerification/income", {
  method: "POST",
  headers: {
      "x-api-key": "<YOUR_API_KEY>",
      "api-version": "1.0",
      "Content-Type": "application/json",
  },
    body: JSON.stringify({
      "taxId": "",
      "country": ""
    }),
});
const data = await res.json();
```

### Python

```python
import requests

headers = {
    "x-api-key": "<YOUR_API_KEY>",
    "api-version": "1.0",
    "Content-Type": "application/json",
}
res = requests.post("https://demo-api.incodesmile.com/omni/externalVerification/income", headers=headers, json={
  "taxId": "",
  "country": ""
})
data = res.json()
```

### Java

```java
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://demo-api.incodesmile.com/omni/externalVerification/income"))
    .header("x-api-key", "<YOUR_API_KEY>")
    .header("api-version", "1.0")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"taxId\": \"\",\n  \"country\": \"\"\n}"))
    .build();
HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
```

### Example response

```json
{
  "success": true,
  "status": "OK"
}
```