# eKYB

`POST /omni/externalVerification/ekyb`

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

This endpoint performs an eKYB check for the business specified

## Path & query parameters

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

## Request body

Content-Type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `plugins` | array[string] |  |  |
| `businessName` | string |  | Name of the business |
| `addressLine1` | string |  | Address line 1 of the business |
| `street` | string |  | Street name of the business address |
| `houseNo` | string |  | The exterior number of the business address |
| `addressLine2` | string |  | Address line 2 of the business |
| `city` | string |  | City of the business address. |
| `state` | string |  | State of the business address. |
| `postalCode` | string |  | Postal code of the business address. |
| `country` | string |  | Two-letter country code of the business address |
| `taxId` | string |  | The tax id of the business |
| `uboName` | string |  | Ultimate Beneficial Owner name. Deprecated — use uboNames instead. |
| `uboNames` | array[string] |  | Ultimate Beneficial Owners names |
| `directors` | array[string] |  | Names of the directors of the business |

Example — US:

```json
{
  "plugins": [
    "ekyb"
  ],
  "businessName": "Incode Technologies, Inc.",
  "addressLine1": "575 Market St",
  "addressLine2": "Fl 4",
  "city": "San Francisco",
  "state": "CA",
  "postalCode": "94105"
}
```

Example — BR:

```json
{
  "plugins": [
    "ekyb"
  ],
  "businessName": "RENATA DISTR. DE SUPLEMENTOS LTDA",
  "street": "Rua Curupaiti",
  "houseNo": "225",
  "addressLine2": "",
  "city": "Rio De Janeiro",
  "state": "RJ",
  "postalCode": "20735320",
  "country": "BR",
  "taxId": "41111051548164",
  "uboNames": [
    "MICHEL RODRIGUES",
    "ERIC SANTOS",
    "MICHELLE MUNHOZ"
  ]
}
```

## Responses

### 200

Status codes for business name:
- status: Success, sub_label: Verified, label: Match identified to the submitted Business Name
- status: Warning, sub_label: Similar Match, label: Similar match identified to the submitted Business Name
- status: Failure, sub_label: Unverified, label: Unable to identify a match to the submitted Business Name
- status: Failure, sub_label: Alternate Name, label: We believe the submitted TIN is associated with "name"

Status codes for address verification:
- status: Success, sub_label: Verified, label: Match identified to the submitted Business Name
- status: Warning, sub_label: Similar Match, label: Similar match identified to the submitted Business Name
- status: Failure, sub_label: Unverified, label: Unable to identify a match to the submitted Business Name
- status: Failure, sub_label: Alternate Name, label: We believe the submitted TIN is associated with "name"

Status codes for address property type:
- status: Success, sub_label: Commercial, label: Submitted Office Address is a Commercial property
- status: Warning, sub_label: Residential, label: Submitted Office Address is a Residential property

Status codes for address deliverability:
- status: Success, sub_label: Deliverable, label: The USPS is able to deliver mail to the submitted Office Address
- status: Failure, sub_label: Undeliverable, label: The USPS is unable to deliver mail to the submitted Office Address

Example:
```
{
    "kyb": [
        {
            "key": "name",
            "status": "success",
            "sub_label": "Verified",
            "message": "Match identified to the submitted Business Name"
        },
        {
            "key": "address_verification",
            "status": "success",
            "sub_label": "Verified",
            "message": "Match identified to the submitted Office Address"
        },
        {
            "key": "address_deliverability",
            "status": "success",
            "sub_label": "Deliverable",
            "message": "The USPS is able to deliver mail to the submitted Office Address"
        },
        {
            "key": "address_property_type",
            "status": "success",
            "sub_label": "Commercial",
            "message": "Submitted Office Address is a Commercial property"
        }
    ]
}
```

Response body (`application/json`):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kyb` | array[EkybVerification] |  |  |
| `kyb.key` | string |  | The name of test |
| `kyb.status` | string |  | Whether the test ows passed. |
| `kyb.sub_label` | string |  | Additional info on the status. |
| `kyb.message` | string |  | Human readable description of the status. |
| `kybSource` | object |  |  |
| `kybSource.uboNames` | array[UboName] |  |  |
| `kybSource.uboNames.id` | string |  |  |
| `kybSource.uboNames.uboName` | string |  |  |
| `businessClassification` | array[EkybVerification] |  |  |
| `businessClassification.key` | string |  | The name of test |
| `businessClassification.status` | string |  | Whether the test ows passed. |
| `businessClassification.sub_label` | string |  | Additional info on the status. |
| `businessClassification.message` | string |  | Human readable description of the status. |

### 400

Bad Request

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 |