--- title: "eKYB" url: "https://developer.incode.com/api-reference/externalverification-ekyb/" section: "api-reference" group: "eKYB" version: "v1.1" status: "live" endpoint: "POST /omni/externalVerification/ekyb" --- # 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 | 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 | ## 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` | EkybSourceInfo | | | | `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. | | `status` | string | | Only present on a 202 async dispatch: PENDING until the verification finishes and the result is delivered via the EKYB_VERIFICATION_RESULT webhook. Enum: `PENDING`, `COMPLETED`, `FAILED` | | `referenceId` | string | | Only present on a 202 async dispatch: id correlating the webhook notification and the result-poll endpoint with this request. | ### 202 Async verification is enabled for the organization; the request is processed in the background and the result is delivered via the EKYB_VERIFICATION_RESULT webhook. Body carries only referenceId and status=PENDING. 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` | EkybSourceInfo | | | | `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. | | `status` | string | | Only present on a 202 async dispatch: PENDING until the verification finishes and the result is delivered via the EKYB_VERIFICATION_RESULT webhook. Enum: `PENDING`, `COMPLETED`, `FAILED` | | `referenceId` | string | | Only present on a 202 async dispatch: id correlating the webhook notification and the result-poll endpoint with this request. | ### 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 | ## Code samples Generated from this endpoint's method, path, and the conventional Incode headers. The base URL is the Incode demo environment; replace `` with a key for your region. ### cURL ```bash curl -X POST https://demo-api.incodesmile.com/omni/externalVerification/ekyb \ -H "x-api-key: " \ -H "api-version: 1.0" \ -H "Content-Type: application/json" \ -d '{ "plugins": [], "businessName": "", "addressLine1": "", "street": "", "houseNo": "", "addressLine2": "", "city": "", "state": "", "postalCode": "", "country": "", "taxId": "", "uboName": "", "uboNames": [], "directors": [] }' ``` ### Node ```js const res = await fetch("https://demo-api.incodesmile.com/omni/externalVerification/ekyb", { method: "POST", headers: { "x-api-key": "", "api-version": "1.0", "Content-Type": "application/json", }, body: JSON.stringify({ "plugins": [], "businessName": "", "addressLine1": "", "street": "", "houseNo": "", "addressLine2": "", "city": "", "state": "", "postalCode": "", "country": "", "taxId": "", "uboName": "", "uboNames": [], "directors": [] }), }); const data = await res.json(); ``` ### Python ```python import requests headers = { "x-api-key": "", "api-version": "1.0", "Content-Type": "application/json", } res = requests.post("https://demo-api.incodesmile.com/omni/externalVerification/ekyb", headers=headers, json={ "plugins": [], "businessName": "", "addressLine1": "", "street": "", "houseNo": "", "addressLine2": "", "city": "", "state": "", "postalCode": "", "country": "", "taxId": "", "uboName": "", "uboNames": [], "directors": [] }) data = res.json() ``` ### Java ```java HttpRequest req = HttpRequest.newBuilder() .uri(URI.create("https://demo-api.incodesmile.com/omni/externalVerification/ekyb")) .header("x-api-key", "") .header("api-version", "1.0") .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString("{\n \"plugins\": [],\n \"businessName\": \"\",\n \"addressLine1\": \"\",\n \"street\": \"\",\n \"houseNo\": \"\",\n \"addressLine2\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"postalCode\": \"\",\n \"country\": \"\",\n \"taxId\": \"\",\n \"uboName\": \"\",\n \"uboNames\": [],\n \"directors\": []\n}")) .build(); HttpResponse res = HttpClient.newHttpClient() .send(req, HttpResponse.BodyHandlers.ofString()); ``` ### Example response ```json { "success": true, "status": "OK" } ```