---
title: "EkybChecks Modular Business Verification"
url: "https://developer.incode.com/api-reference/kyb/"
section: "api-reference"
group: "eKYB"
version: "v1.1"
status: "live"
endpoint: "POST /omni/kyb"
---
# EkybChecks Modular Business Verification

`POST /omni/kyb`

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

Composable KYB endpoint. Clients specify which modules they need and Incode routes to the correct vendor for the country. Available modules: identity, address, statusEntityType, personAssociation, webPresence, websiteAnalysis, industryInfo, financialIntelligence, groupStructure. Every response carries a referenceId, and every run ends with one EKYB_CHECKS_RESULT webhook carrying the final result (also pollable at GET /omni/verification/async/{referenceId}). webPresence/websiteAnalysis/industryInfo/financialIntelligence may not finish within the synchronous response's wait budget; those are listed in pendingModules and the webhook follows once they resolve.

## Path & query parameters

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

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `plugins` | array[string] |  |  |
| `country` | string | yes | ISO 3166-1 alpha-2 country code |
| `taxId` | string |  | Tax ID or company registration number |
| `businessName` | string |  | Registered legal name of the business |
| `street` | string |  | Street address |
| `city` | string |  | City |
| `state` | string |  | State / province |
| `postalCode` | string |  | Postal code / ZIP |
| `personNames` | array[string] |  | Names of persons to verify association with the business (PERSON_ASSOCIATION module). Each name is matched against the business officer/director registry; one result per name is returned. |
| `website` | string |  | Business website URL |
| `alternativeNames` | array[string] |  | Alternative or trade names for the business |
| `phoneNumber` | string |  | Business phone number |
| `email` | string |  | Business email address |
| `modules` | array[string] |  | Enum: `identity`, `address`, `statusEntityType`, `personAssociation`, `webPresence`, `websiteAnalysis`, `industryInfo`, `financialIntelligence`, `groupStructure` |

## Responses

### 200

OK

Response body (`application/json`):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `identity` | IdentityModuleResult |  |  |
| `identity.taxId` | string |  | Enum: `verified`, `approximateMatch`, `unverified`, `notFound` |
| `identity.name` | string |  | Enum: `verified`, `approximateMatch`, `unverified`, `notFound` |
| `identity.registryName` | string |  |  |
| `identity.registryNames` | array[string] |  |  |
| `identity.tinMatchType` | string |  |  |
| `identity.tinMatchMessage` | string |  |  |
| `identity.error` | EkybChecksError |  |  |
| `identity.error.status` | string |  | Enum: `verified`, `approximateMatch`, `unverified`, `notFound` |
| `identity.error.message` | string |  |  |
| `address` | AddressModuleResult |  |  |
| `address.addressVerification` | string |  | Enum: `verified`, `approximateMatch`, `unverified`, `notFound` |
| `address.registryAddress` | string |  |  |
| `address.registryAddresses` | array[string] |  |  |
| `address.officeType` | string |  |  |
| `address.otherAddresses` | array[OtherAddress] |  |  |
| `address.otherAddresses.address` | string |  |  |
| `address.otherAddresses.type` | string |  |  |
| `address.error` | EkybChecksError |  |  |
| `address.error.status` | string |  | Enum: `verified`, `approximateMatch`, `unverified`, `notFound` |
| `address.error.message` | string |  |  |
| `statusEntityType` | StatusEntityTypeModuleResult |  |  |
| `statusEntityType.registrationStatus` | string |  |  |
| `statusEntityType.entityType` | string |  |  |
| `statusEntityType.incorporationDate` | string |  |  |
| `statusEntityType.companySize` | string |  |  |
| `statusEntityType.otherInfo` | OtherInfo |  |  |
| `statusEntityType.otherInfo.vatNo` | string |  |  |
| `statusEntityType.otherInfo.otherNames` | array[OtherName] |  |  |
| `statusEntityType.otherInfo.otherNames.name` | string |  |  |
| `statusEntityType.otherInfo.otherNames.businessNameType` | string |  |  |
| `statusEntityType.otherInfo.leiNumber` | string |  |  |
| `statusEntityType.otherInfo.panNumber` | string |  |  |
| `statusEntityType.otherInfo.panName` | string |  |  |
| `statusEntityType.otherInfo.allGSTINs` | array[Gstin] |  |  |
| `statusEntityType.otherInfo.allGSTINs.gstin` | string |  |  |
| `statusEntityType.otherInfo.allGSTINs.state` | string |  |  |
| `statusEntityType.otherInfo.allGSTINs.status` | string |  |  |
| `statusEntityType.error` | EkybChecksError |  |  |
| `statusEntityType.error.status` | string |  | Enum: `verified`, `approximateMatch`, `unverified`, `notFound` |
| `statusEntityType.error.message` | string |  |  |
| `personAssociation` | PersonAssociationModuleResult |  |  |
| `personAssociation.personMatches` | array[EkybChecksPersonMatch] |  |  |
| `personAssociation.personMatches.checkedName` | string |  |  |
| `personAssociation.personMatches.status` | string |  | Enum: `verified`, `approximateMatch`, `unverified`, `notFound` |
| `personAssociation.personMatches.matchedName` | string |  |  |
| `personAssociation.personMatches.matchedPerson` | EkybChecksPersonResult |  |  |
| `personAssociation.personMatches.matchedPerson.name` | string |  |  |
| `personAssociation.personMatches.matchedPerson.titles` | array[string] |  |  |
| `personAssociation.personMatches.matchedPerson.percentSharesHeld` | number (double) |  |  |
| `personAssociation.people` | array[EkybChecksPersonResult] |  |  |
| `personAssociation.people.name` | string |  |  |
| `personAssociation.people.titles` | array[string] |  |  |
| `personAssociation.people.percentSharesHeld` | number (double) |  |  |
| `personAssociation.error` | EkybChecksError |  |  |
| `personAssociation.error.status` | string |  | Enum: `verified`, `approximateMatch`, `unverified`, `notFound` |
| `personAssociation.error.message` | string |  |  |
| `webPresence` | WebPresenceModuleResult |  |  |
| `webPresence.socialProfiles` | array[SocialProfile] |  |  |
| `webPresence.socialProfiles.platform` | string |  |  |
| `webPresence.socialProfiles.username` | string |  |  |
| `webPresence.socialProfiles.url` | string |  |  |
| `webPresence.socialProfiles.confidence` | string |  |  |
| `webPresence.socialProfiles.followers` | integer (int64) |  |  |
| `webPresence.socialProfiles.bio` | string |  |  |
| `webPresence.socialProfiles.businessWebsite` | string |  |  |
| `webPresence.socialProfiles.verified` | boolean |  |  |
| `webPresence.websites` | array[string] |  |  |
| `webPresence.phoneNumbers` | array[string] |  |  |
| `webPresence.emailAddresses` | array[string] |  |  |
| `webPresence.error` | EkybChecksError |  |  |
| `webPresence.error.status` | string |  | Enum: `verified`, `approximateMatch`, `unverified`, `notFound` |
| `webPresence.error.message` | string |  |  |
| `websiteAnalysis` | WebsiteAnalysisModuleResult |  |  |
| `websiteAnalysis.url` | string |  |  |
| `websiteAnalysis.domainAgeMonths` | integer (int32) |  |  |
| `websiteAnalysis.domainCreatedAt` | string |  |  |
| `websiteAnalysis.domainExpiresAt` | string |  |  |
| `websiteAnalysis.registrar` | string |  |  |
| `websiteAnalysis.parked` | boolean |  |  |
| `websiteAnalysis.buildStatus` | string |  |  |
| `websiteAnalysis.ssl` | Ssl |  |  |
| `websiteAnalysis.ssl.isValid` | boolean |  |  |
| `websiteAnalysis.ssl.issuer` | string |  |  |
| `websiteAnalysis.ssl.certificateType` | string |  |  |
| `websiteAnalysis.ssl.tlsVersion` | string |  |  |
| `websiteAnalysis.ssl.expiryDate` | string |  |  |
| `websiteAnalysis.ssl.daysUntilExpiry` | integer (int32) |  |  |
| `websiteAnalysis.ssl.isWildcard` | boolean |  |  |
| `websiteAnalysis.ssl.isSelfSigned` | boolean |  |  |
| `websiteAnalysis.ssl.isRevoked` | boolean |  |  |
| `websiteAnalysis.structureMetrics` | StructureMetrics |  |  |
| `websiteAnalysis.structureMetrics.depth` | string |  |  |
| `websiteAnalysis.structureMetrics.breadth` | string |  |  |
| `websiteAnalysis.error` | EkybChecksError |  |  |
| `websiteAnalysis.error.status` | string |  | Enum: `verified`, `approximateMatch`, `unverified`, `notFound` |
| `websiteAnalysis.error.message` | string |  |  |
| `industryInfo` | IndustryInfoModuleResult |  |  |
| `industryInfo.naicsCode` | string |  |  |
| `industryInfo.title` | string |  |  |
| `industryInfo.accuracy` | number (double) |  |  |
| `industryInfo.riskLevel` | string |  |  |
| `industryInfo.industryCode` | string |  |  |
| `industryInfo.classification` | string |  |  |
| `industryInfo.industryDesc` | string |  |  |
| `industryInfo.activityDesc` | string |  |  |
| `industryInfo.error` | EkybChecksError |  |  |
| `industryInfo.error.status` | string |  | Enum: `verified`, `approximateMatch`, `unverified`, `notFound` |
| `industryInfo.error.message` | string |  |  |
| `financialIntelligence` | FinancialIntelligenceModuleResult |  |  |
| `financialIntelligence.liens` | array[Lien] |  |  |
| `financialIntelligence.liens.filingNumber` | string |  |  |
| `financialIntelligence.liens.filingType` | string |  |  |
| `financialIntelligence.liens.filingDate` | string |  |  |
| `financialIntelligence.liens.status` | string |  |  |
| `financialIntelligence.liens.lienAmount` | number (double) |  |  |
| `financialIntelligence.liens.matchLevel` | string |  |  |
| `financialIntelligence.litigation` | array[Litigation] |  |  |
| `financialIntelligence.litigation.docketNumber` | string |  |  |
| `financialIntelligence.litigation.court` | string |  |  |
| `financialIntelligence.litigation.state` | string |  |  |
| `financialIntelligence.litigation.title` | string |  |  |
| `financialIntelligence.litigation.caseType` | string |  |  |
| `financialIntelligence.litigation.dateFiled` | string |  |  |
| `financialIntelligence.litigation.matchLevel` | string |  |  |
| `financialIntelligence.litigation.riskLevel` | string |  |  |
| `financialIntelligence.bankruptcy` | array[Bankruptcy] |  |  |
| `financialIntelligence.bankruptcy.bankruptcyType` | string |  |  |
| `financialIntelligence.bankruptcy.docketNumber` | string |  |  |
| `financialIntelligence.bankruptcy.court` | string |  |  |
| `financialIntelligence.bankruptcy.title` | string |  |  |
| `financialIntelligence.bankruptcy.dateFiled` | string |  |  |
| `financialIntelligence.bankruptcy.riskLevel` | string |  |  |
| `financialIntelligence.bankruptcy.matchLevel` | string |  |  |
| `financialIntelligence.creditRating` | string |  |  |
| `financialIntelligence.creditRatingDescription` | string |  |  |
| `financialIntelligence.creditLimit` | Amount |  |  |
| `financialIntelligence.creditLimit.currency` | string |  |  |
| `financialIntelligence.creditLimit.value` | number (double) |  |  |
| `financialIntelligence.probabilityOfDefault` | number (double) |  |  |
| `financialIntelligence.turnover` | Turnover |  |  |
| `financialIntelligence.turnover.currency` | string |  |  |
| `financialIntelligence.turnover.value` | number (double) |  |  |
| `financialIntelligence.turnover.range` | string |  |  |
| `financialIntelligence.employeeCount` | string |  |  |
| `financialIntelligence.negativeInformation` | object |  |  |
| `financialIntelligence.error` | EkybChecksError |  |  |
| `financialIntelligence.error.status` | string |  | Enum: `verified`, `approximateMatch`, `unverified`, `notFound` |
| `financialIntelligence.error.message` | string |  |  |
| `groupStructure` | GroupStructureModuleResult |  |  |
| `groupStructure.ultimateParent` | GroupCompany |  |  |
| `groupStructure.ultimateParent.name` | string |  |  |
| `groupStructure.ultimateParent.country` | string |  |  |
| `groupStructure.ultimateParent.status` | string |  |  |
| `groupStructure.ultimateParent.registrationNumber` | string |  |  |
| `groupStructure.ultimateParent.level` | string |  |  |
| `groupStructure.immediateParent` | GroupCompany |  |  |
| `groupStructure.immediateParent.name` | string |  |  |
| `groupStructure.immediateParent.country` | string |  |  |
| `groupStructure.immediateParent.status` | string |  |  |
| `groupStructure.immediateParent.registrationNumber` | string |  |  |
| `groupStructure.immediateParent.level` | string |  |  |
| `groupStructure.subsidiaryCompanies` | array[GroupCompany] |  |  |
| `groupStructure.subsidiaryCompanies.name` | string |  |  |
| `groupStructure.subsidiaryCompanies.country` | string |  |  |
| `groupStructure.subsidiaryCompanies.status` | string |  |  |
| `groupStructure.subsidiaryCompanies.registrationNumber` | string |  |  |
| `groupStructure.subsidiaryCompanies.level` | string |  |  |
| `groupStructure.affiliatedCompanies` | array[GroupCompany] |  |  |
| `groupStructure.affiliatedCompanies.name` | string |  |  |
| `groupStructure.affiliatedCompanies.country` | string |  |  |
| `groupStructure.affiliatedCompanies.status` | string |  |  |
| `groupStructure.affiliatedCompanies.registrationNumber` | string |  |  |
| `groupStructure.affiliatedCompanies.level` | string |  |  |
| `groupStructure.relatedEntities` | array[GroupCompany] |  |  |
| `groupStructure.relatedEntities.name` | string |  |  |
| `groupStructure.relatedEntities.country` | string |  |  |
| `groupStructure.relatedEntities.status` | string |  |  |
| `groupStructure.relatedEntities.registrationNumber` | string |  |  |
| `groupStructure.relatedEntities.level` | string |  |  |
| `groupStructure.error` | EkybChecksError |  |  |
| `groupStructure.error.status` | string |  | Enum: `verified`, `approximateMatch`, `unverified`, `notFound` |
| `groupStructure.error.message` | string |  |  |
| `scores` | array[EkybChecksScore] |  |  |
| `scores.type` | string |  |  |
| `scores.score` | number (double) |  |  |
| `scores.rating` | string |  |  |
| `pendingModules` | array[string] |  | Enum: `identity`, `address`, `statusEntityType`, `personAssociation`, `webPresence`, `websiteAnalysis`, `industryInfo`, `financialIntelligence`, `groupStructure` |
| `referenceId` | string |  |  |
| `empty` | boolean |  |  |

### 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 `<YOUR_API_KEY>` with a key for your region.

### cURL

```bash
curl -X POST https://demo-api.incodesmile.com/omni/kyb \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "X-Incode-Hardware-Id: <YOUR_INCODE_HARDWARE_ID>" \
  -H "api-version: 1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "<country>"
  }'
```

### Node

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

### Python

```python
import requests

headers = {
    "x-api-key": "<YOUR_API_KEY>",
    "X-Incode-Hardware-Id": "<YOUR_INCODE_HARDWARE_ID>",
    "api-version": "1.0",
    "Content-Type": "application/json",
}
res = requests.post("https://demo-api.incodesmile.com/omni/kyb", headers=headers, json={
  "country": "<country>"
})
data = res.json()
```

### Java

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

### Ruby

```
require "net/http"
require "json"

uri = URI("https://demo-api.incodesmile.com/omni/kyb")
req = Net::HTTP::Post.new(uri)
req["x-api-key"] = "<YOUR_API_KEY>"
req["X-Incode-Hardware-Id"] = "<YOUR_INCODE_HARDWARE_ID>"
req["api-version"] = "1.0"
req["Content-Type"] = "application/json"
req.body = '{
  "country": "<country>"
}'

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
```

### PHP

```
$ch = curl_init("https://demo-api.incodesmile.com/omni/kyb");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "x-api-key: <YOUR_API_KEY>",
    "X-Incode-Hardware-Id: <YOUR_INCODE_HARDWARE_ID>",
    "api-version: 1.0",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{
  "country": "<country>"
}');

$data = json_decode(curl_exec($ch), true);
curl_close($ch);
```

### Example response

```json
{
  "identity": {
    "taxId": "verified",
    "name": "verified",
    "registryName": "string",
    "registryNames": [
      "string"
    ],
    "tinMatchType": "string",
    "tinMatchMessage": "string",
    "error": {
      "status": "verified",
      "message": "string"
    }
  },
  "address": {
    "addressVerification": "verified",
    "registryAddress": "string",
    "registryAddresses": [
      "string"
    ],
    "officeType": "string",
    "otherAddresses": [
      {
        "address": "string",
        "type": "string"
      }
    ],
    "error": {
      "status": "verified",
      "message": "string"
    }
  },
  "statusEntityType": {
    "registrationStatus": "string",
    "entityType": "string",
    "incorporationDate": "string",
    "companySize": "string",
    "otherInfo": {
      "vatNo": "string",
      "otherNames": [
        {
          "name": "string",
          "businessNameType": "string"
        }
      ],
      "leiNumber": "string",
      "panNumber": "string",
      "panName": "string",
      "allGSTINs": [
        {
          "gstin": "string",
          "state": "string",
          "status": "string"
        }
      ]
    },
    "error": {
      "status": "verified",
      "message": "string"
    }
  },
  "personAssociation": {
    "personMatches": [
      {
        "checkedName": "string",
        "status": "verified",
        "matchedName": "string",
        "matchedPerson": {
          "name": "string",
          "titles": [
            "string"
          ],
          "percentSharesHeld": 0
        }
      }
    ],
    "people": [
      {
        "name": "string",
        "titles": [
          "string"
        ],
        "percentSharesHeld": 0
      }
    ],
    "error": {
      "status": "verified",
      "message": "string"
    }
  },
  "webPresence": {
    "socialProfiles": [
      {
        "platform": "string",
        "username": "string",
        "url": "string",
        "confidence": "string",
        "followers": 0,
        "bio": "string",
        "businessWebsite": "string",
        "verified": true
      }
    ],
    "websites": [
      "string"
    ],
    "phoneNumbers": [
      "string"
    ],
    "emailAddresses": [
      "string"
    ],
    "error": {
      "status": "verified",
      "message": "string"
    }
  },
  "websiteAnalysis": {
    "url": "string",
    "domainAgeMonths": 0,
    "domainCreatedAt": "string",
    "domainExpiresAt": "string",
    "registrar": "string",
    "parked": true,
    "buildStatus": "string",
    "ssl": {
      "isValid": true,
      "issuer": "string",
      "certificateType": "string",
      "tlsVersion": "string",
      "expiryDate": "string",
      "daysUntilExpiry": 0,
      "isWildcard": true,
      "isSelfSigned": true,
      "isRevoked": true
    },
    "structureMetrics": {
      "depth": "string",
      "breadth": "string"
    },
    "error": {
      "status": "verified",
      "message": "string"
    }
  },
  "industryInfo": {
    "naicsCode": "string",
    "title": "string",
    "accuracy": 0,
    "riskLevel": "string",
    "industryCode": "string",
    "classification": "string",
    "industryDesc": "string",
    "activityDesc": "string",
    "error": {
      "status": "verified",
      "message": "string"
    }
  },
  "financialIntelligence": {
    "liens": [
      {
        "filingNumber": "string",
        "filingType": "string",
        "filingDate": "string",
        "status": "string",
        "lienAmount": 0,
        "matchLevel": "string"
      }
    ],
    "litigation": [
      {
        "docketNumber": "string",
        "court": "string",
        "state": "string",
        "title": "string",
        "caseType": "string",
        "dateFiled": "string",
        "matchLevel": "string",
        "riskLevel": "string"
      }
    ],
    "bankruptcy": [
      {
        "bankruptcyType": "string",
        "docketNumber": "string",
        "court": "string",
        "title": "string",
        "dateFiled": "string",
        "riskLevel": "string",
        "matchLevel": "string"
      }
    ],
    "creditRating": "string",
    "creditRatingDescription": "string",
    "creditLimit": {
      "currency": "string",
      "value": 0
    },
    "probabilityOfDefault": 0,
    "turnover": {
      "currency": "string",
      "value": 0,
      "range": "string"
    },
    "employeeCount": "string",
    "negativeInformation": {},
    "error": {
      "status": "verified",
      "message": "string"
    }
  },
  "groupStructure": {
    "ultimateParent": {
      "name": "string",
      "country": "string",
      "status": "string",
      "registrationNumber": "string",
      "level": "string"
    },
    "immediateParent": {
      "name": "string",
      "country": "string",
      "status": "string",
      "registrationNumber": "string",
      "level": "string"
    },
    "subsidiaryCompanies": [
      {
        "name": "string",
        "country": "string",
        "status": "string",
        "registrationNumber": "string",
        "level": "string"
      }
    ],
    "affiliatedCompanies": [
      {
        "name": "string",
        "country": "string",
        "status": "string",
        "registrationNumber": "string",
        "level": "string"
      }
    ],
    "relatedEntities": [
      {
        "name": "string",
        "country": "string",
        "status": "string",
        "registrationNumber": "string",
        "level": "string"
      }
    ],
    "error": {
      "status": "verified",
      "message": "string"
    }
  },
  "scores": [
    {
      "type": "string",
      "score": 0,
      "rating": "string"
    }
  ],
  "pendingModules": [
    "identity"
  ],
  "referenceId": "string",
  "empty": true
}
```