RFI v5 Flow: Overview
RFI Flow v5 is Nium's unified integration for handling all requests for information (RFIs). When Nium needs additional information to progress a request — an onboarding step, a transaction, a refund, or any other action — it raises an RFI through this flow.
The v5 flow consolidates all RFI types into a single contract: one set of webhooks, one set of APIs, covering every situation in which Nium needs information from the client.
RFI Flow v5 requires enablement. Contact your Nium account manager to activate it for your client.
For the full API specification, see the RFI API Reference.
Design principles
| Principle | What it means |
|---|---|
| One contract, all RFIs | A single integration handles every category of RFI Nium raises. No branching on RFI source or category is needed. |
| Optional comment and file attachment | Every RFI supports an optional free-text comment and file attachment so end-users can provide context alongside their response. |
| Stable contract | New question types, RFI categories, or metadata are additive. Existing fields retain their semantics, so Nium-side changes do not break client integrations. |
| Self-describing payloads | Each RFI carries the structure and examples needed to render and respond to it. Clients do not need to maintain mapping tables between Nium field codes and their UI. |
| Webhook-first | Each RFI raised has its own webhook cycle. The webhook payload contains the full RFI object so clients can reduce reliance on polling the Fetch RFI Details API. |
| Minimal mapping | Response payloads mirror the structure of the fetch payload, minimising transformation on the client side. |
Concepts and data model
What an RFI is
An RFI is a structured request from Nium asking for additional information. Each RFI is tied to an rfiEntity — the entity the information is being requested about. Valid rfiEntity values are ONBOARDING, TRANSACTION, ICC_RECON, and USER_ONBOARDING. The client receives the RFI, gathers the information from the end-user or their internal systems, and responds through the API.
Lifecycle
The state is the source of truth for what actions the client can take. Each state transition is accompanied by a webhook event.
| State | Description |
|---|---|
RFI_REQUESTED | Nium has raised the RFI and is awaiting a response. |
RFI_RESPONDED | The client has submitted a response. |
RFI_CLOSED | Nium cancelled the RFI before it was resolved. |
Core objects
| Object | Description |
|---|---|
| RFI Query | A single piece of information, document, or action being requested. Has a unique ID, a state, a type, a prompt, and optionally an example, validation hints, and accepted response formats. |
| Response | The client's answer to a query or submission of a document. |
| Comment | An optional free-text comment by the end-user supporting the response. |
| Attachment | An optional file submitted by the end-user. Uploaded separately and referenced by ID in the response. |
Each RFI query gets at most one response. If Nium re-raises the RFI for additional clarification, a new cycle begins and prior responses are preserved as history.
Question types
Each RFI query declares a type that tells the client how to render the input and shape the response.
| Type | Description |
|---|---|
TEXT | Free-form long-text input. |
CHOICE | Single value selected from a list of options. |
MULTI_CHOICE | Multiple values selected from a list of options. |
ADDRESS | An address split into Address Line 1, Address Line 2, City, State, Country, and Postcode. |
FILE_ATTACHMENT | One or more file uploads. |
IDENTITY_DOCUMENT | One or more personal document uploads. |
CONFIRMATION | A true/false answer. |
URL | A URL to complete a hosted flow or download an offline form template. |
DATE | A date value (for example, date of birth or document expiry). Format: YYYY-MM-DD. |
The Fetch RFI API response includes two arrays — mandatoryFieldTypes and optionalFieldTypes — rather than a single type field. An RFI may accept multiple response types simultaneously; mandatoryFieldTypes lists what the client must provide, and optionalFieldTypes lists what the client may additionally include. Render based on these arrays rather than maintaining a separate question schema.
Identifiers to persist
| Identifier | Description |
|---|---|
rfiId | Stable, globally unique identifier for each RFI query. Use for all subsequent API calls and to correlate webhook events. |
rfiEntityReferenceId | Reference ID of the entity the RFI was raised against (for example, a stakeholder, applicant, remitter, or beneficiary reference ID). |
externalReferenceId | Reference ID shared by the client to Nium during onboarding or transactions, uniquely identifying the end-customer or their associated entities. |
End-to-end flow
Happy path
Variants
Multi-question RFI: Multiple queries can be responded to together in a single call to the Submit RFI Response API using their unique rfiId values.
Closed RFIs: Nium may cancel an RFI before it is resolved. The client receives an rfi.closed webhook.
Optional attachments: Additional or supporting files are uploaded using the Create File API before submitting the response. The upload returns an attachment ID that is referenced in the response payload.
Unanswered RFIs: Clients can request cancellation of a transaction or onboarding application when the required information cannot be provided, using the cannotRespond object in the response payload.
Webhooks
Each RFI state change fires a webhook to your registered endpoint. Webhooks carry the full RFI object as their payload so you can act without an additional API call.
See Notifications and webhooks for authentication and delivery details, and RFI Webhooks for the full payload reference.
| Event | When it fires |
|---|---|
rfi.requested | A new RFI has been raised and is awaiting response. |
rfi.responded | The client has submitted a response. |
rfi.closed | The RFI was cancelled by Nium before resolution. |
Webhooks are not guaranteed to arrive in order. Use the status field in the payload as the source of truth. Every webhook carries a unique eventId — deduplicate on this field.
Next steps
- Build your RFI form — how to render each question type and a full end-to-end example
- RFI API Reference — full API specification for Fetch RFI Details and Submit RFI Response