Onboarding document events

These events use the v1.onboarding.document.* prefix and report changes to documents submitted during business onboarding.

Overview

During onboarding, accounts must submit supporting documents (e.g. trade licenses, passports, bank statements) for review. Documents go through automated validation and manual review. Whenever a document reaches a decision point, we emit a webhook so your system can react in real-time: notify the customer, update your UI, or trigger follow-up actions.

---

Event catalogue

Event	When it triggers
v1.onboarding.document.approved	Document has been reviewed and accepted.
v1.onboarding.document.declined	Document has been reviewed and not accepted. See declinedReason for the category of issue.
v1.onboarding.document.validation_warnings	Automated validation flagged concerns. Customer must acknowledge the warning or re-upload the file.

Trigger these in sandbox

In sandbox you can fire document.approved and document.declined yourself, without waiting for compliance review, via the sandbox onboarding endpoints. See Simulating onboarding decisions. The same endpoints also fire the v1.rfi.document.* family when called against an RFI document.

Event flow

1. The customer submits a document. It goes through automated validation.
2. If validation passes cleanly, the document moves straight to review: no event is fired at this point.
3. If validation finds concerns, you receive a document.validation_warnings event. Present the validationMessage to the customer and let them either acknowledge the warning (the document proceeds to review) or re-upload a corrected file (validation runs again).
4. Once review is complete, you receive either document.approved or document.declined.
5. If declined, the customer can re-upload and the cycle starts again.

---

Additional data

Each document.* event includes the following properties in the data object:

Field	Type	Events	Description
documentId	UUID	All	The document's unique identifier.
documentType	string	All	Specific type, e.g. TRADE_LICENSE, PASSPORT. See Document requirements.
documentCategory	string	All	BUSINESS_DOCUMENT or PERSON_DOCUMENT. 1
status	string	All	The document status after the transition. See Document statuses.
declinedReason	string	declined	Why the document was not accepted. See Decline reasons.
declinedCustomerDisplayReason	string	declined	Free-text reason safe to show the customer. Written by the reviewer.
validationStatus	string	validation_warnings	The specific warning category from automated review. See Validation status.
validationMessage	string	validation_warnings	Human-readable warning message. Safe to show the end customer directly.

---

Payload examples

document.approved

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event": "v1.onboarding.document.approved",
  "accountId": "f5e6d7c8-b9a0-4321-8765-0fedcba98765",
  "createdAt": "2026-04-14T10:15:31Z",
  "data": {
    "documentId": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
    "documentType": "TRADE_LICENSE",
    "documentCategory": "BUSINESS_DOCUMENT",
    "status": "APPROVED"
  },
  "relatedObject": {
    "id": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
    "type": "onboarding.document"
  }
}

document.declined

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event": "v1.onboarding.document.declined",
  "accountId": "f5e6d7c8-b9a0-4321-8765-0fedcba98765",
  "createdAt": "2026-04-14T10:15:31Z",
  "data": {
    "documentId": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
    "documentType": "PASSPORT",
    "documentCategory": "PERSON_DOCUMENT",
    "status": "DECLINED",
    "declinedReason": "QUALITY",
    "declinedCustomerDisplayReason": "Document image is blurry: please re-upload a clearer photo."
  },
  "relatedObject": {
    "id": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
    "type": "onboarding.document"
  }
}

document.validation_warnings

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event": "v1.onboarding.document.validation_warnings",
  "accountId": "f5e6d7c8-b9a0-4321-8765-0fedcba98765",
  "createdAt": "2026-04-14T10:15:31Z",
  "data": {
    "documentId": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
    "documentType": "TRADE_LICENSE",
    "documentCategory": "BUSINESS_DOCUMENT",
    "status": "VALIDATION_WARNINGS",
    "validationStatus": "WARNING_QUALITY_INSUFFICIENT",
    "validationMessage": "The image is blurry and some text is hard to read. Please re-upload a clearer version."
  },
  "relatedObject": {
    "id": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
    "type": "onboarding.document"
  }
}

See Event format for the webhook envelope schema.

---

Footnotes

1. Files with documentCategory = RFI_DOCUMENT are emitted via the separate v1.rfi.document.* family, not this family. The onboarding family is reserved for files uploaded during initial KYB onboarding. ↩