KYB API Reference

Runs the requested checks for one business, returning a single response with one result for each check requested.

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

Endpoint

POST /omni/kyb

Request

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

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

{
  "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.

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

Identity

Address

Status and entity type

Person association

Web presence

Website analysis

Industry info

Financial intelligence

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

Example response

{
  "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.

{
  "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.

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