Respond to RFIs and understand holds

Track Roots requests for information and keep affected onboarding or payment activity on hold until the request is resolved.

The API reference does not yet expose an endpoint for submitting an RFI response. See API versions and Beta status for current endpoint availability.

Before you begin

Store Roots person, account, counterparty, and payment IDs in your system so you can reconcile a request with the affected record.
Build an internal queue for requests that need documents, explanations, or updated details from your end customer.
Do not release a held onboarding flow or payment based only on an internal assessment. Wait for Roots to record the required outcome.

1. List requests

Use GET /frontoffice/requests to retrieve the requests available to your company.

Parameter	Type	Required	Default	Constraints
`page`	integer	No	`1`	Must be at least `1`.
`page_size`	integer	No	`20`	From `1` through `100`.
`type`	string	No	—	`RFI` or `ACTION`.
`status`	string	No	—	`Open`, `In review`, or `Resolved`.

For example, list open RFIs in pages of 20 records:

GET /frontoffice/requests?type=RFI&status=Open&page=1&page_size=20

The current mock returns a paginated result.

{
  "total": 1,
  "items": [
    {
      "id": "rfi_123",
      "type": "RFI",
      "status": "Open",
      "person": {
        "id": "person_business_123",
        "name": "Acme Trading Ltd"
      },
      "severity": "high",
      "details": [
        {
          "title": "Provide ownership information",
          "description": "Upload the current ownership chart and identify each beneficial owner."
        }
      ],
      "due_date": "2026-08-10"
    }
  ],
  "limit": 20,
  "offset": 0
}

Use the request ID, linked person, details, severity, and due date to create an actionable task for your operations or compliance team.

2. Interpret request types and statuses

Roots exposes two request types in the current schema:

Type	Meaning	Your next action
`RFI`	Roots needs information or supporting evidence to continue a review.	Collect every item in `details`, then submit it through the production response flow when it is available.
`ACTION`	A required task, such as completing data collection or uploading a document.	Complete the underlying task and verify that the action is resolved.

A request can have the following statuses:

Status	Meaning	Your integration behavior
`Open`	The request needs a response or action.	Keep the affected workflow blocked and surface the due date to the responsible team.
`In review`	Roots is reviewing the submitted response or completed action.	Do not resubmit unless Roots requests additional information.
`Resolved`	Roots has closed the request.	Retrieve the linked record again and confirm that no separate hold or restriction remains.

3. Handle holds and restrictions

An RFI can block onboarding, account activity, or a payment while Roots reviews the required information. A hold means that affected activity must remain unavailable until Roots records an authorized outcome.

Your integration should:

Stop any automatic follow-on action for the affected record.
Notify the team responsible for providing the requested information.
Attach the response and supporting documents to your internal case record.
Track the request deadline and escalate overdue items internally.
Poll the available request and resource endpoints, or consume future webhooks, until Roots reports the resolved state.
Re-check the account, payment, or onboarding status after the RFI resolves; resolving an RFI does not by itself guarantee that an account is active or that a payment can proceed.

⚠️
Do not auto-release funds or retry a held payment because an RFI deadline passes. The Roots compliance workflow requires the applicable review and release decision before activity can continue.

4. Prepare RFI responses

The production response endpoint is not yet published. Prepare your integration to send each requested item with:

The Roots request ID.
A clear response for each request detail.
Supporting documents and document metadata when requested.
References to the affected person, account, counterparty, or payment.
Your stable internal case or ticket ID for reconciliation.

For payment-related RFIs, be ready to provide the payment purpose, sender or beneficiary details, and supporting records such as invoices, contracts, or source-of-funds evidence when Roots requests them.

Optional: Handle unknown-sender payments

The planned incoming-payment workflow can place an incoming payment on hold when the sender is unknown or unregistered. Roots may request sender identity details, the relationship to the sender, payment purpose, and supporting documents.

Keep the funds unavailable while the review remains open. The planned workflow may apply a cooling-off period after a successful review, and it may return unresolved payments rather than make them available.

Next steps

Use GET /frontoffice/persons/{person_id}/requests to plan person-specific request views.
Monitor the API reference for the RFI response endpoint, document-upload requirements, authentication, and webhook events.
Build reconciliation around Roots IDs and your own external references so your team can trace every request to the underlying business process.