---
title: "KYB Results Webhook"
url: "https://developer.incode.com/general-reference/kyb-results-webhook/"
section: "general-reference"
group: "Webhooks Overview"
version: "v1.1"
status: "live"
---
# 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.

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

## Configure webhook

[Configure this webhook](/dashboard-platform-administration/configuration-webhooks-tab/) 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 |

```json Node
{
  "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 |

```json Node
{
  "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.