Skip to main content

RFI document

Audience: partners integrating with our push notification service.

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

Version: 1.0

1. Overview​

When a customer attaches a file to an RFI document request, the file enters the same per-document review pipeline as onboarding documents — automated validation followed by manual review. Each per-file decision emits a webhook so your system can react in real-time.

These events are a distinct family from v1.onboarding.document.*. The onboarding family covers files uploaded during initial KYB onboarding; this family covers files uploaded against an RFI document request. The two families have separate relatedObjectType values (rfi.document vs onboarding.document) so you can route them independently.

For case-level lifecycle events (opened, closed, cancelled), see RFI case.

2. Event catalogue​

EventWhen it triggers
v1.rfi.document.approvedRFI-attached document has been reviewed and accepted.
v1.rfi.document.declinedRFI-attached document has been reviewed and not accepted. See declinedReason for the category.
v1.rfi.document.validation_warningsAutomated validation flagged concerns. Customer must acknowledge the warning or re-upload the file.

All events carry relatedObjectType = rfi.document.

3. Correlating events to the parent RFI​

The v1.rfi.document.* payload deliberately does not include rfiId. To route an event back to the RFI case that produced it, you need to maintain your own mapping. Get this wrong and you will silently fail to match webhooks to RFIs in your system.

documentId is the attached document's UUID — not the upload UUID

When the customer attaches files to a document request, the gateway merges the uploaded files into a single document and returns that document's UUID. The webhook emits that UUID — not the documentUploadId returned by POST /v1/rfi/{rfiId}/documents/upload.

If you persist documentUploadId → rfiId against the upload response, your lookup will silently miss every webhook. Persist documentId → rfiId from the attach response instead (see pattern below).

Correct partner pattern — two steps:

  1. At attach time. POST /v1/rfi/{rfiId}/document-requests/{documentRequestId}/attach returns the updated Rfi. Walk Rfi.documentRequests[] and persist documentId → rfiId for every entry where documentId is non-null.

    One document is created per document-request slot — multi-file uploads (e.g. front + back of an ID) merge into a single document. You will get one webhook per document, not one per uploaded file.

  2. On webhook arrival. Look up event.data.documentId in your map to get the owning rfiId.

4. Additional data​

The data payload mirrors v1.onboarding.document.* exactly — same keys, same value semantics. All values are strings, per the platform convention.

FieldTypeEventsDescription
documentIdUUIDAllThe attached document's UUID (see correlation note above). Matches relatedObject.id.
documentTypestringAllSpecific type, e.g. BANK_STATEMENT, PROOF_OF_ADDRESS. See Document requirements.
documentCategorystringAllRFI_DOCUMENT for files attached to an RFI document request.
statusstringAllThe document status after the transition. See Document statuses.
declinedReasonstringdeclinedWhy the document was not accepted. See Decline reasons.
declinedCustomerDisplayReasonstringdeclinedFree-text reason safe to show the customer. Written by the reviewer.
validationStatusstringvalidation_warningsThe specific warning category from automated review. See Validation status.
validationMessagestringvalidation_warningsHuman-readable warning message. Safe to show the end customer directly.

5. Payload examples​

rfi.document.approved​

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event": "v1.rfi.document.approved",
  "accountId": "f5e6d7c8-b9a0-4321-8765-0fedcba98765",
  "createdAt": "2026-05-13T13:50:11Z",
  "data": {
    "documentId": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
    "documentType": "BANK_STATEMENT",
    "documentCategory": "RFI_DOCUMENT",
    "status": "APPROVED"
  },
  "relatedObject": {
    "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
    "type": "rfi.document"
  }
}

rfi.document.declined​

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event": "v1.rfi.document.declined",
  "accountId": "f5e6d7c8-b9a0-4321-8765-0fedcba98765",
  "createdAt": "2026-05-13T13:55:42Z",
  "data": {
    "documentId": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
    "documentType": "BANK_STATEMENT",
    "documentCategory": "RFI_DOCUMENT",
    "status": "DECLINED",
    "declinedReason": "QUALITY",
    "declinedCustomerDisplayReason": "Statement is illegible — please upload a clearer PDF covering the last 3 months."
  },
  "relatedObject": {
    "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
    "type": "rfi.document"
  }
}

rfi.document.validation_warnings​

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event": "v1.rfi.document.validation_warnings",
  "accountId": "f5e6d7c8-b9a0-4321-8765-0fedcba98765",
  "createdAt": "2026-05-13T13:45:09Z",
  "data": {
    "documentId": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
    "documentType": "BANK_STATEMENT",
    "documentCategory": "RFI_DOCUMENT",
    "status": "VALIDATION_WARNINGS",
    "validationStatus": "WARNING_QUALITY_INSUFFICIENT",
    "validationMessage": "The image is blurry and some figures are hard to read. Please re-upload a clearer version."
  },
  "relatedObject": {
    "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
    "type": "rfi.document"
  }
}

See the callback documentation for the full webhook envelope schema.

6. Migration note for existing partners​

Prior to the RFI doc-link refactor, per-document decisions on RFI-attached files were routed through v1.onboarding.document.*. They are now routed through this dedicated v1.rfi.document.* family instead.

If your integration was previously subscribed to v1.onboarding.document.* and expected to see RFI document decisions on it, you must additionally subscribe to v1.rfi.document.* to keep receiving those events. The onboarding family will continue to fire for initial KYB onboarding documents only.