---
title: "KYB API Reference"
url: "https://developer.incode.com/general-reference/kyb-api-reference/"
section: "general-reference"
group: "KYB Modules Reference"
version: "v1.1"
status: "live"
---
# KYB API Reference
Runs the requested checks for one business, returning a single response with one result for each check requested.

:::note
This is not the same as eKYB [Verification](/general-reference/ekyb-verification-api-reference/) or [Prefill](/general-reference/ekyb-prefill-api-reference/) API Reference.
:::



All endpoints require authentication headers. See the Incode API Documentation for details.









## Endpoint

`POST /omni/kyb`




| | |
|---|---|
| Authentication | Session Token (X-Incode-Hardware-Id) and x-api-key |
| Content type | application/json |
| Result delivery | Synchronous response, plus one KYB_RESULTS webhook per run |
| Related | KYB Results Webhook, KYB Coverage |

## Request

| Field | Type | Required | Description |
|---|---|---|---|
| country | string | Yes | ISO 3166-1 alpha-2 country code, for example US, GB, DE |
| modules | string[] | Yes | Modules to run. See Modules below |
| taxId | string | Per country and module | Tax ID, company registration number or VAT number. Outside the US this is how the business is found. See Tax ID formats |
| businessName | string | Per country and module | Registered legal name of the business |
| street | string | No | Street address |
| city | string | Per country and module | City |
| state | string | Per country and module | State or province. For the US, the two-letter state code |
| postalCode | string | No | Postal code or ZIP |
| personNames | string[] | No | Full names of people to check against the business's officers and directors (personAssociation). One result is returned per name |
| website | string | No | Business website URL |
| alternativeNames | string[] | No | Trade names or other names the business uses |
| phoneNumber | string | No | Business phone number |
| email | string | No | Business email address |

## Modules

`identity`, `address`, `statusEntityType`, `personAssociation`, `webPresence`, `websiteAnalysis`, `industryInfo`, `financialIntelligence`, `groupStructure`.

A module the country’s source does not support is skipped and is absent from the response. An unknown module name rejects the request.

## Validation

**United States**

| Rule | Error message |
|---|---|
| identity requires taxId and businessName | Missing mandatory fields: taxId, businessName |
| address, webPresence, websiteAnalysis and industryInfo require businessName, city and state | Missing mandatory fields: businessName, city, state |
| statusEntityType, personAssociation and financialIntelligence must be requested together with address | Missing required module address for modules: statusEntityType |
| taxId, when sent, is 1 to 20 letters, numbers, spaces or hyphens | Invalid taxId: must be 1 to 20 characters of letters, numbers, spaces or hyphens |

The error message lists every missing field at once. A `website` does not replace `businessName`, `city` and `state`: `websiteAnalysis` always starts from the business’s discovered web presence, and the submitted `website` is used when one is sent.

**Other countries**

The business is found by `taxId`. Without a taxId, or when no business matches it, every requested module carries an `error` with status `notFound` (see Errors inside a module below). `address` is compared only when at least one of `street`, `city` or `postalCode` is sent; otherwise the address module is left out of the response.

**Example request**





















```json Node
{
  "country": "US",
  "modules": ["identity", "address", "statusEntityType", "personAssociation", "webPresence"],
  "taxId": "12-3456789",
  "businessName": "Acme Corp",
  "street": "123 Main Street",
  "city": "Austin",
  "state": "TX",
  "postalCode": "78701",
  "personNames": ["John Smith"],
  "website": "https://acmecorp.com"
}
```

**Response**

`200 OK`. Only the checks that were requested and are supported for the country are present. Read each check by name and treat an absent check as “not checked”. `null` fields are omitted.

| Field | Type | Description |
|---|---|---|
| identity | object | Identity |
| address | object | Address |
| statusEntityType | object | Status and entity type |
| personAssociation | object | Person association |
| webPresence | object | Web presence |
| websiteAnalysis | object | Website analysis |
| industryInfo | object | Industry info |
| financialIntelligence | object | Financial intelligence |
| groupStructure | object | Group structure |
| scores | object[] | KYB or risk scores, when the source returns them: type, score, rating |
| pendingModules | string[] | Modules still running. Their results arrive with the webhook |
| referenceId | string | Identifies this run in the webhook and the polling endpoint |

Match statuses are `Verified`, `Approximate Match`, `Unverified` and `Not Found`.

**Identity**

| Field | Type | Description |
|---|---|---|
| taxId | match status | Match result for the submitted tax ID |
| name | match status | Match result for the submitted business name against the registered names |
| registryName | string | Registered name of the business |
| registryNames | string[] | All registered names the submitted name was compared against |
| tinMatchType | string | US only. EIN or state registration number |
| tinMatchMessage | string | US only. IRS name + TIN result: Tax ID and business name combination found or Tax ID and business name combination not found |
| error | object | See Errors inside a module |

**Address**

| Field | Type | Description |
|---|---|---|
| addressVerification | match status | Match result for the submitted address |
| registryAddress | string | Registered address of the business |
| registryAddresses | string[] | All addresses on file the submitted address was compared against |
| officeType | string | Type of the registered office, for example headOffice |
| otherAddresses | object[] | Other addresses on file: address, type |
| error | object | See Errors inside a module |

**Status and entity type**

| Field | Type | Description |
|---|---|---|
| registrationStatus | string | Active, Inactive or Unknown |
| entityType | string | Legal entity type, as reported by the registry |
| incorporationDate | string | Date of incorporation |
| companySize | string | Company size band |
| otherInfo | object | vatNo, leiNumber, otherNames[] (name, businessNameType). India only: panNumber, panName, allGSTINs[] (gstin, state, status) |
| error | object | See Errors inside a module |

**Person association**

| Field | Type | Description |
|---|---|---|
| personMatches | object[] | One entry per name in personNames: checkedName, status (match status), matchedName, matchedPerson |
| people | object[] | Every officer, director or shareholder on record: name, titles[], percentSharesHeld |
| error | object | See Errors inside a module |

**Web presence**

| Field | Type | Description |
|---|---|---|
| socialProfiles | object[] | platform (for example facebook, x, linked_in:company), username, url, confidence (high, medium, low), followers, bio, businessWebsite, verified |
| websites | string[] | Websites associated with the business |
| phoneNumbers | string[] | Phone numbers associated with the business |
| emailAddresses | string[] | Email addresses associated with the business |
| error | object | See Errors inside a module |

**Website analysis**

| Field | Type | Description |
|---|---|---|
| url | string | Website that was analyzed |
| domainAgeMonths | integer | Age of the domain in months |
| domainCreatedAt / domainExpiresAt | string | ISO-8601 dates |
| registrar | string | Domain registrar |
| parked | boolean | true when the domain is parked or a placeholder |
| buildStatus | string | For example active |
| ssl | object | isValid, issuer, certificateType (DV, OV, EV), tlsVersion, expiryDate, daysUntilExpiry, isWildcard, isSelfSigned, isRevoked |
| structureMetrics | object | depth, breadth |
| error | object | See Errors inside a module |

**Industry info**

| Field | Type | Description |
|---|---|---|
| naicsCode / title | string | NAICS code and title (US) |
| accuracy | number | Confidence of the NAICS prediction, 0.0 to 1.0 (US) |
| riskLevel | string | low, medium or high (US) |
| industryCode / classification | string | Local industry code and its classification system, for example SIC07, WZ2008 |
| industryDesc / activityDesc | string | Industry and activity descriptions |
| error | object | See Errors inside a module |

**Financial intelligence**

| Field | Type | Description |
|---|---|---|
| liens | object[] | US. filingNumber, filingType, filingDate, status, lienAmount, matchLevel |
| litigation | object[] | US. docketNumber, court, state, title, caseType, dateFiled, matchLevel, riskLevel |
| bankruptcy | object[] | US. bankruptcyType, docketNumber, court, title, dateFiled, riskLevel, matchLevel |
| creditRating / creditRatingDescription | string | Credit rating A to E and its description |
| creditLimit | object | currency, value |
| probabilityOfDefault | number | Probability of default |
| turnover | object | currency, value, or only a range band where the registry reports no figure (Germany) |
| employeeCount | string | A figure or a band, for example 3-5 |
| negativeInformation | object | Negative information as reported by the source |
| error | object | See Errors inside a module |

For `liens`, `litigation` and `bankruptcy`, an empty list means the search ran and found nothing; an absent list means that search did not complete.

**Group structure**

| Field | Type | Description |
|---|---|---|
| ultimateParent / immediateParent | object | name, country, status, registrationNumber |
| subsidiaryCompanies / affiliatedCompanies | object[] | Same shape as a parent |
| relatedEntities | object[] | Italy only. A flat list where each entry also carries a level |
| error | object | See Errors inside a module |

**Example response**

```json Node
{
  "identity": {
    "taxId": "Verified",
    "name": "Verified",
    "registryName": "ACME CORP",
    "tinMatchType": "EIN",
    "tinMatchMessage": "Tax ID and business name combination found"
  },
  "address": {
    "addressVerification": "Verified",
    "registryAddress": "123 Main Street, Austin, TX 78701"
  },
  "statusEntityType": {
    "registrationStatus": "Active",
    "entityType": "Corporation"
  },
  "personAssociation": {
    "personMatches": [
      {
        "checkedName": "John Smith",
        "status": "Verified",
        "matchedName": "JOHN SMITH",
        "matchedPerson": { "name": "JOHN SMITH", "titles": ["CEO"] }
      }
    ],
    "people": [
      { "name": "JOHN SMITH", "titles": ["CEO"] },
      { "name": "MARY JONES", "titles": ["Director"] }
    ]
  },
  "pendingModules": ["webPresence"],
  "referenceId": "6650f2c1a9b8e45d2c3f1a77"
}
```

## Errors

**Errors inside a module**

A module that ran but could not produce a result carries an `error` object, and the rest of the response is unaffected. The request still answers `200`.

| Field | Description |
|---|---|
| status | notFound when the business or the data was not found, unverified when the source failed or could not complete the check |
| message | The reason |

| Message | Meaning |
|---|---|
| Business Not Found | No business matched the request (US) |
| Incorrect Tax ID/Registration Number | No business matched the submitted taxId |
| Tax ID and business name combination not found | The IRS did not confirm the name + TIN pair (US) |
| No information available | The business was found, but the source holds no data for this module |
| Verification could not be completed: the provider request failed or the provider is unavailable | The source failed. The request can be retried |
| Web presence unavailable, Website analysis unavailable, Industry info unavailable, Liens unavailable, Litigation and bankruptcy unavailable | That background check did not complete |

```json Node
{
  "identity": {
    "error": { "status": "notFound", "message": "Incorrect Tax ID/Registration Number" }
  },
  "statusEntityType": {
    "error": { "status": "notFound", "message": "Incorrect Tax ID/Registration Number" }
  },
  "referenceId": "6650f2c1a9b8e45d2c3f1a78"
}
```

**Request errors**

`400 Bad Request`. The request was rejected before any source was called, or the source could not be reached at all. Nothing is billed for a request rejected by validation.

| Message | Cause |
|---|---|
| Missing mandatory fields: … | A field the requested modules need is missing or blank |
| Missing required module address for modules: … | A module that depends on address was requested without it |
| Invalid taxId: … | taxId does not have a valid format |
| No provider configured for country XX | This module is not enabled for this country for the organization |
| Company report unavailable for XX | The business was found but its report could not be retrieved |

```json Node
{
  "timestamp": 1760600000000,
  "status": 400,
  "error": "Missing mandatory fields: taxId, businessName",
  "message": "Missing mandatory fields: taxId, businessName",
  "path": "/omni/kyb"
}
```

</br>