KYB Results Webhook

Every run returns a referenceId and ends with exactly one KYB_RESULTS webhook. Use the webhook, or poll with the referenceId, to read the final result of a run, including checks that were still running when POST /omni/kyb answered.

How results are delivered

Most checks answer within the request. Four checks query sources that can take longer:

webPresence
websiteAnalysis
industryInfo
financialIntelligence

These run in parallel and the request waits for them up to a fixed budget (20 seconds by default). Then:

Situation	POST /omni/kyb response	Webhook
Every requested check finished in time	Full result, no pendingModules	Sent right away with the same result
Some checks are still running	Result of the checks that finished, plus pendingModules listing the rest	Sent once every pending check finishes, with the full result

Only the United States runs checks in the background. For other countries, every check answers within the request.

A background check that never finishes is closed after a timeout and reported with an error (for example Web presence unavailable), so a run always ends with a webhook.

{
  "identity": { "taxId": "verified", "name": "verified", "registryName": "ACME CORP" },
  "address": { "addressVerification": "verified" },
  "pendingModules": ["webPresence", "industryInfo"],
  "referenceId": "6650f2c1a9b8e45d2c3f1a77"
}

Configure webhook

Configure this webhook URL for the KYB_RESULTS event in Dashboard at Configuration > Webhooks.

Field	Type	Description
referenceId	string	The referenceId returned by POST /omni/kyb
result	object	The final result, with the same shape as the POST /omni/kyb response. pendingModules and referenceId are not set inside result

{
  "referenceId": "6650f2c1a9b8e45d2c3f1a77",
  "result": {
    "identity": { "taxId": "verified", "name": "verified", "registryName": "ACME CORP" },
    "address": { "addressVerification": "verified" },
    "webPresence": {
      "socialProfiles": [
        { "platform": "linked_in:company", "url": "https://www.linkedin.com/company/acmecorp", "confidence": "high" }
      ],
      "websites": ["https://acmecorp.com"]
    },
    "industryInfo": {
      "naicsCode": "541511",
      "title": "Custom Computer Programming Services",
      "accuracy": 0.92,
      "riskLevel": "low"
    }
  }
}

The webhook is sent once per run. Use referenceId to match it with the request.

Poll the result

GET /omni/verification/async/{referenceId}

Authentication is the same as for POST /omni/kyb. Use polling as a fallback when the webhook is not configured or did not arrive.

Field	Type	Description
referenceId	string	The requested referenceId
status	string	PENDING while checks are still running, COMPLETED when the result is final, FAILED when the run could not be finalized
type	string	KYB_RESULTS
result	object	The final result once COMPLETED, otherwise null

{
  "referenceId": "6650f2c1a9b8e45d2c3f1a77",
  "status": "COMPLETED",
  "type": "KYB_RESULTS",
  "result": {
    "identity": { "taxId": "verified", "name": "verified" },
    "webPresence": { "websites": ["https://acmecorp.com"] }
  }
}

Returns 404 when the referenceId is unknown or belongs to another organization.