> Toden documentation. For the full index fetch /llms.txt. Every page is available as Markdown by appending .md to its URL. Identity verification uses /api/kyc, Risk Intelligence uses /api/v1; they are separate contracts with different error shapes. Never invent an endpoint, field or enum value: read the API reference page for the operation first.

# Business verification

> Integrate entity, identity, key-person and workflow lifecycle events.

These events connect a completed KYC or KYB journey to the durable entity, identity and workflow records created for it. They can arrive independently of `verification.completed`, so deduplicate each event by envelope `id` and join records by the IDs in `data`.

## Events and handling

| Event                       | When it fires                                                                    | Recommended handling                                              |
| --------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `entity.created`            | A successful Toden verification creates an entity.                               | Store the entity ID against your customer.                        |
| `entity.imported`           | An externally verified entity is created through an import or Identity API call. | Store its provenance and follow the import job if `jobId` exists. |
| `identity.resolved`         | An entity is linked to a global identity.                                        | Add the identity ID without replacing the entity ID.              |
| `entity.reverification_due` | The entity reaches its re-verification due date.                                 | Start a new check before `dueAt`.                                 |
| `workflow.run.completed`    | A workflow reaches a terminal customer outcome.                                  | Persist the version, outcome and tags.                            |
| `workflow.run.failed`       | A workflow stops because of an engine fault.                                     | Keep the journey retryable and inspect the run.                   |
| `workflow.action`           | A configured workflow webhook action executes.                                   | Route the action by `nodeId`; do not infer a final outcome.       |
| `key_person.completed`      | A director or beneficial-owner verification resolves.                            | Update that person inside the parent business review.             |

## Complete entity example

```json
{
  "version": "2026-08-11",
  "id": "evt_entity_created_01",
  "type": "entity.created",
  "createdAt": "2026-08-15T13:06:44.002Z",
  "deliveryId": "del_entity_created_01",
  "data": {
    "entityId": "ent_2405a1d091cf154b1ecfc9689e75f37b",
    "orgId": "org_01j9myaza",
    "environment": "SANDBOX",
    "externalUserId": "business_1048",
    "type": "business",
    "kycProvenance": "MYAZA_VERIFIED",
    "verificationId": "ver_business_1048",
    "createdAt": "2026-08-15T13:06:43.711Z"
  }
}
```

## Event-specific `data` contracts

Insert each object below into the shared V2 envelope. Optional fields appear only when the producing operation has them.

```json
[
  { "type": "entity.imported", "data": { "entityId": "ent_imported_01", "identityId": "idn_01", "externalUserId": "customer_882", "environment": "SANDBOX", "jobId": "imp_01" } },
  { "type": "identity.resolved", "data": { "entityId": "ent_imported_01", "identityId": "idn_01", "environment": "SANDBOX", "matchedExisting": true } },
  { "type": "entity.reverification_due", "data": { "entityId": "ent_2405a1d091cf154b1ecfc9689e75f37b", "externalUserId": "business_1048", "environment": "PRODUCTION", "dueAt": "2026-09-15T00:00:00.000Z" } },
  { "type": "workflow.run.completed", "data": { "runId": "wfr_01", "workflowId": "wf_kyb_01", "workflowVersion": 7, "verificationId": "ver_business_1048", "entityId": "ent_2405a1d091cf154b1ecfc9689e75f37b", "environment": "SANDBOX", "outcome": "APPROVE", "tags": ["registry-match", "screening-clear"], "completedAt": "2026-08-15T13:06:44.002Z" } },
  { "type": "workflow.run.failed", "data": { "runId": "wfr_02", "workflowId": "wf_kyb_01", "workflowVersion": 7, "verificationId": "ver_business_1049", "environment": "SANDBOX", "error": "A workflow action could not be completed.", "failedAt": "2026-08-15T13:11:04.192Z" } },
  { "type": "workflow.action", "data": { "runId": "wfr_01", "workflowId": "wf_kyb_01", "verificationId": "ver_business_1048", "entityId": "ent_2405a1d091cf154b1ecfc9689e75f37b", "nodeId": "node_notify_legal", "note": "Notify the compliance operations queue", "environment": "SANDBOX" } },
  { "type": "key_person.completed", "data": { "keyPersonId": "kp_01", "verificationId": "ver_business_1048", "personVerificationId": "ver_person_01", "role": "DIRECTOR", "isApplicant": false, "status": "VERIFIED", "environment": "SANDBOX" } }
]
```

## Field reference

| Field                                           | Type            |                 Nullable | Meaning                                                             |
| ----------------------------------------------- | --------------- | -----------------------: | ------------------------------------------------------------------- |
| `entityId`, `identityId`                        | string          | `identityId` can be null | Organisation-scoped entity and resolved global identity IDs.        |
| `externalUserId`                                | string          |          No when present | Your stable customer reference.                                     |
| `type`                                          | string          |                       No | `individual` or `business`.                                         |
| `kycProvenance`                                 | string          |                       No | Verification provenance, for example `MYAZA_VERIFIED`.              |
| `workflowId`, `runId`, `verificationId`         | string          |          Event-dependent | IDs for the exact journey.                                          |
| `workflowVersion`                               | integer         |          Event-dependent | Published workflow version that ran.                                |
| `outcome`                                       | string          |          Event-dependent | Terminal workflow outcome such as `APPROVE`, `DECLINE` or `REVIEW`. |
| `tags`                                          | string\[]       |         No on completion | Workflow-generated classification tags.                             |
| `role`                                          | string          |        No for key people | Business relationship, for example `DIRECTOR`.                      |
| `status`                                        | string          |        No for key people | Result status, for example `VERIFIED` or `FAILED`.                  |
| `environment`                                   | string          |                       No | `SANDBOX` or `PRODUCTION`.                                          |
| `createdAt`, `completedAt`, `failedAt`, `dueAt` | ISO 8601 string |          Event-dependent | Resource lifecycle time.                                            |

Business verification result fields such as registry records, directors and ownership remain on the verification resource. Behaviour and reauthentication events are documented under [Event Monitoring](/integrate/webhooks/events/event-monitoring).

## Related APIs and events

Use entity, verification and workflow-run read APIs for current state. Related events include `verification.completed`, `screening.completed`, `credits.deducted` and `risk.assessment.completed`. They are not guaranteed to arrive in that order.