Requests for Information (RFIs)

The RFI webhook and API are currently in beta. The API and webhook payloads described on this page are subject to change.

A Request for Information (RFI) is raised by Bridge’s compliance team when additional information is needed about a developer, customer, or specific transaction, for example a payment’s purpose or the source of funds. RFIs are typically raised on a transfer, drain, deposit, or card_account, but may also be raised directly on a developer or customer with no associated transaction. Bridge notifies you of RFIs via the rfi webhook event category and lets you read RFI state through the /rfis API. Resolving an RFI (submitting responses) currently happens via the Bridge Dashboard, using the dashboard_url returned on the RFI object. You can also continue to respond to RFIs via email if you prefer.

RFI lifecycle

An RFI moves through the following states:

State	Description
`on_developer`	Bridge is waiting on you (or your customer) to respond. This is the initial state of a newly created RFI.
`on_bridge`	A response has been submitted and Bridge is reviewing it.
`closed`	The RFI has been resolved and no further action is needed.

The RFI object

Field	Description
`id`	Unique identifier for the RFI.
`state`	Current state of the RFI: `on_developer`, `on_bridge`, or `closed`.
`developer_id`	The developer this RFI is associated with.
`customer_id`	The customer this RFI is associated with, if any.
`referent_id`	The id of the record this RFI is associated with, if any. This is the same id you already see in that record’s own webhook events and API responses.
`referent_type`	The type of record `referent_id` refers to: `transfer`, `drain`, `deposit`, `card_account`, or `customer` (for RFIs raised directly on a customer, with no associated transaction). `deposit` covers both static memo activity and virtual account activity, which the Dashboard shows as a single payment type.
`context`	Transaction and counterparty details associated with this RFI, keyed by field name. See Context below.
`bridge_action_taken`	An action Bridge has already taken as a result of this RFI, if any: `customer_paused` or `transaction_paused`.
`expected_action_on_expiry`	The action Bridge expects to take if this RFI expires without a response: currently only `pause_customer`.
`deadline`	The date by which this RFI needs to be responded to.
`requested_items`	The items Bridge is asking for. See Requested items below.
`dashboard_url`	A link to view and respond to this RFI in the Bridge dashboard.
`state_changed_at`	The time the RFI’s `state` last changed.
`created_at`	Time the RFI was created.
`closed_at`	The time the RFI was closed, if it has been.

Context

context holds transaction and counterparty details relevant to the request. The set of keys present varies by request - fields without a value for a given RFI are omitted rather than set to null. This object may contain personally-identifiable information, such as a customer’s name or email, IBANs, or counterparty names. Below is the full list of keys context can contain. This list may grow over time.

Key	Description
`developer_name`	The developer’s display name.
`customer_name`	The customer’s name.
`customer_email`	The customer’s email.
`card_account_id`	The id of the card account this RFI is associated with.
`amount_display`	The transaction amount, pre-formatted for display, for example `"$1,000.00"`.
`currency_display`	The transaction currency, pre-formatted for display, for example `"USD"`.
`transaction_date`	The transaction date, pre-formatted for display, for example `"2026-08-26"`.
`transaction_network`	The blockchain network involved, for crypto transactions, for example `"tron"`, `"ethereum"`, `"solana"`, `"polygon"`, or `"stellar"`.
`transaction_type`	The payment rail the transaction moved on, for example `"Wire"`, `"ACH"`, `"Sepa"`, or `"Pix"`. `"Bridge Wallet"` indicates a crypto transfer through a Bridge-hosted wallet rather than a traditional payment rail.
`sender_name`	The sender’s name, if this RFI is associated with an incoming payment.
`sender_bank`	The sender’s bank.
`beneficiary_name`	The beneficiary’s name, if this RFI is associated with an outgoing payment.
`counterparty_name`	The counterparty’s name.
`payment_direction`	The direction of the payment, for example `"inbound"` (funds moving into Bridge) or `"outbound"` (funds moving out of Bridge).
`banking_circle_transaction_reference`	The Banking Circle transaction reference, for RFIs raised by that banking partner.
`transaction_id`	The id of the transaction this RFI is associated with.
`client_reference_id`	The client reference id supplied on the transaction, if any.
`transfer_id`	The id of the transfer this RFI is associated with.
`deposit_id`	The id of the deposit this RFI is associated with.
`deposit_date`	The deposit date, pre-formatted for display, for example `"2026-09-08"`.
`viban_list`	The virtual account numbers (VIBANs) involved, as an array of strings.
`viban`	A single virtual account number (VIBAN) involved.
`account_count`	The number of accounts involved, for example `59`.
`creditor_iban`	The creditor IBAN, for RFIs associated with an IBAN-based payment, for example `"DE89370400440532013000"`.
`debtor_iban`	The debtor IBAN, for RFIs associated with an IBAN-based payment, for example `"FR1420041010050500013M02606"`.
`country_name`	The country associated with the request, for example on an IP-based alert, for example `"Venezuela"`.
`access_date`	The date of the flagged account access, for example `"2026-09-08"`.
`access_time`	The time of the flagged account access, for example `"14:14:38"`.
`prohibited_or_sanctioned`	Whether the country is on Bridge’s prohibited or sanctioned list.
`sof_link`	A link to a source-of-funds questionnaire.
`period`	The time period the request concerns, pre-formatted for display.
`declared_amount`	The transaction volume declared at onboarding.
`spike_months`	The month(s) in which transaction volume spiked.
`actual_amount`	The actual transaction volume observed.
`number_of_payments`	The number of payments the request concerns.
`date_range`	The date range the request concerns.
`min_transaction_amount`	The smallest transaction amount in the set the request concerns.
`max_transaction_amount`	The largest transaction amount in the set the request concerns.
`external_account_count`	The number of external accounts the RFI is associated with.
`external_accounts_list`	The external accounts the RFI is associated with, pre-formatted for display as a single string (may list multiple accounts).
`custom_body`	Freeform text elaborating on the request, present on some RFIs.

Requested items

requested_items lists the items Bridge is asking the developer to provide.

Field	Description
`content`	The question or request being made, in plain language.

API

Use the RFIs API to read the current state of RFIs raised on your developer or customer accounts.

GET /rfis - list RFIs, optionally filtered by state or customer_id, with cursor-based pagination via starting_after/ending_before.
GET /rfis/{rfiID} - retrieve a single RFI by id.

Request

curl --request GET \
  --url 'https://api.bridge.xyz/v0/rfis/8991c31c-3cf6-4128-8ad4-177fcd114c8a' \
  --header 'Api-Key: <api-key>'

Response

{
  "id": "8991c31c-3cf6-4128-8ad4-177fcd114c8a",
  "state": "closed",
  "developer_id": "ffcf9216-30a2-49cd-b095-79afabf7ae6f",
  "customer_id": "80b4cf5b-d4d0-4139-b8d8-de534e455cd3",
  "referent_id": "480ba091-1be0-4669-b738-6ef4651d4f4d",
  "referent_type": "transfer",
  "bridge_action_taken": "transaction_paused",
  "expected_action_on_expiry": "pause_customer",
  "deadline": "2026-09-16T09:00:00Z",
  "dashboard_url": "https://dashboard.bridge.xyz/app/support?action=view-ticket&conversationId=d9c99009-edaf-4e2f-8b4e-389173655c8a",
  "state_changed_at": "2026-09-09T18:24:22Z",
  "context": {
    "developer_name": "Northwind Labs - non-custodial testing",
    "customer_name": "Jordan Rivera",
    "customer_email": "jordan.rivera@example.com",
    "amount_display": "$1.00 USDB",
    "currency_display": "USDB",
    "transaction_date": "2026-08-26",
    "transaction_type": "Bridge Wallet",
    "sender_bank": "Unknown",
    "transaction_id": "480ba091-1be0-4669-b738-6ef4651d4f4d"
  },
  "requested_items": [
    {
      "content": "What is the purpose of this payment and how will the customer be using these funds?"
    },
    {
      "content": "What is the source of funds for this payment? Please provide supporting documentation (bank or investment statement, pay stub, invoice, receipt or contract)."
    }
  ],
  "created_at": "2026-09-09T18:23:01Z",
  "closed_at": "2026-09-09T18:24:22Z"
}

There is currently no API for submitting RFI answers - respond via the dashboard_url returned on the RFI object.

Webhooks

Subscribe to the rfi event category on your webhook endpoint to be notified as RFIs are created and change state. The event_object on these events matches the RFI object returned by the API. If you don’t have a webhook endpoint yet, follow the webhook setup guide to create one. To add RFI events to an existing endpoint, include rfi in the event_categories array when you create or update the endpoint. See the webhooks overview and event structure docs for general webhook concepts.

Event type	Trigger
`rfi.created`	A new RFI is raised on your developer or customer account.
`rfi.updated.status_transitioned`	An RFI’s `state` changes, for example from `on_developer` to `on_bridge`, or to `closed`.

Example: RFI lifecycle

The following three events show a single RFI moving from on_developer, to on_bridge after a response is submitted in the dashboard, to closed once Bridge finishes review.

rfi.created
rfi.updated.status_transitioned (on_bridge)
rfi.updated.status_transitioned (closed)

{
  "api_version": "v0",
  "event_id": "wh_t9k2XPwmeCYAQTxRmYq7QRk",
  "event_developer_id": "ffcf9216-30a2-49cd-b095-79afabf7ae6f",
  "event_sequence": 173,
  "event_category": "rfi",
  "event_type": "rfi.created",
  "event_object_id": "8991c31c-3cf6-4128-8ad4-177fcd114c8a",
  "event_object_status": "on_developer",
  "event_object": {
    "id": "8991c31c-3cf6-4128-8ad4-177fcd114c8a",
    "state": "on_developer",
    "deadline": "2026-09-16T09:00:00Z",
    "customer_id": "80b4cf5b-d4d0-4139-b8d8-de534e455cd3",
    "referent_id": "480ba091-1be0-4669-b738-6ef4651d4f4d",
    "developer_id": "ffcf9216-30a2-49cd-b095-79afabf7ae6f",
    "dashboard_url": "https://dashboard.bridge.xyz/app/support?action=view-ticket&conversationId=d9c99009-edaf-4e2f-8b4e-389173655c8a",
    "referent_type": "transfer",
    "state_changed_at": "2026-09-09T18:23:03Z",
    "bridge_action_taken": "transaction_paused",
    "expected_action_on_expiry": "pause_customer"
  },
  "event_object_changes": {},
  "event_created_at": "2026-09-09T18:23:03.694Z"
}

{
  "api_version": "v0",
  "event_id": "wh_tcRZoir1gWXYBoHMJcijjQm",
  "event_developer_id": "ffcf9216-30a2-49cd-b095-79afabf7ae6f",
  "event_sequence": 174,
  "event_category": "rfi",
  "event_type": "rfi.updated.status_transitioned",
  "event_object_id": "8991c31c-3cf6-4128-8ad4-177fcd114c8a",
  "event_object_status": "on_bridge",
  "event_object": {
    "id": "8991c31c-3cf6-4128-8ad4-177fcd114c8a",
    "state": "on_bridge",
    "deadline": "2026-09-16T09:00:00Z",
    "customer_id": "80b4cf5b-d4d0-4139-b8d8-de534e455cd3",
    "referent_id": "480ba091-1be0-4669-b738-6ef4651d4f4d",
    "developer_id": "ffcf9216-30a2-49cd-b095-79afabf7ae6f",
    "dashboard_url": "https://dashboard.bridge.xyz/app/support?action=view-ticket&conversationId=d9c99009-edaf-4e2f-8b4e-389173655c8a",
    "referent_type": "transfer",
    "state_changed_at": "2026-09-09T18:23:40Z",
    "bridge_action_taken": "transaction_paused",
    "expected_action_on_expiry": "pause_customer"
  },
  "event_object_changes": {
    "state": [
      "on_developer",
      "on_bridge"
    ],
    "state_changed_at": [
      "2026-09-09T18:23:03Z",
      "2026-09-09T18:23:40Z"
    ]
  },
  "event_created_at": "2026-09-09T18:23:40.749Z"
}

{
  "api_version": "v0",
  "event_id": "wh_tvpV4VJ4diENPzuEc2mC81D",
  "event_developer_id": "ffcf9216-30a2-49cd-b095-79afabf7ae6f",
  "event_sequence": 175,
  "event_category": "rfi",
  "event_type": "rfi.updated.status_transitioned",
  "event_object_id": "8991c31c-3cf6-4128-8ad4-177fcd114c8a",
  "event_object_status": "closed",
  "event_object": {
    "id": "8991c31c-3cf6-4128-8ad4-177fcd114c8a",
    "state": "closed",
    "deadline": "2026-09-16T09:00:00Z",
    "customer_id": "80b4cf5b-d4d0-4139-b8d8-de534e455cd3",
    "referent_id": "480ba091-1be0-4669-b738-6ef4651d4f4d",
    "developer_id": "ffcf9216-30a2-49cd-b095-79afabf7ae6f",
    "dashboard_url": "https://dashboard.bridge.xyz/app/support?action=view-ticket&conversationId=d9c99009-edaf-4e2f-8b4e-389173655c8a",
    "referent_type": "transfer",
    "state_changed_at": "2026-09-09T18:24:22Z",
    "bridge_action_taken": "transaction_paused",
    "expected_action_on_expiry": "pause_customer"
  },
  "event_object_changes": {
    "state": [
      "on_bridge",
      "closed"
    ],
    "state_changed_at": [
      "2026-09-09T18:23:40Z",
      "2026-09-09T18:24:22Z"
    ]
  },
  "event_created_at": "2026-09-09T18:24:23.245Z"
}

Orchestration

Wallets

Issuance

Cards

Customers

Logistics

Additional information

Requests for Information (RFIs)

RFI lifecycle

The RFI object

Context

Requested items

API

Webhooks

Example: RFI lifecycle

​RFI lifecycle

​The RFI object

​Context

​Requested items

​API

​Webhooks

​Example: RFI lifecycle

RFI lifecycle

The RFI object

Context

Requested items

API

Webhooks

Example: RFI lifecycle