Document

Audience: partners integrating with our push notification service.

Scope: events whose event value starts with v1.onboarding.document.*

Version: 1.0

---

1. 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.

---

2. 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.

3. 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.

---

4. 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.
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.

---

5. 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 the callback documentation for the full webhook envelope schema.

---