Track transfer status

Retrieve transfer records after creation and after every approval, rejection, rescission, or operational update.

See API availability before you automate transfer lifecycle handling in production.

Retrieve a transfer

Retrieve the current transfer record with:

GET /api/v1/client/transfers/{transfer_id}

Send a bearer access token with the request. The response includes the transfer direction, rail, minor-unit amount, currency, status, failure reason, lifecycle identities, timestamps, and rail references.

{
  "id": "xfer_123",
  "account_id": "acct_123",
  "destination_account_id": null,
  "counterparty_id": "cpty_123",
  "direction": "withdrawal",
  "rail": "FEDWIRE",
  "amount": "125050",
  "currency": "USD",
  "status": "<current-status>",
  "failure_reason": null,
  "rail_refs": {},
  "parent_transfer_id": null,
  "created_by_identity_id": "ident_123",
  "approved_by_identity_id": null,
  "created_at": "2026-08-10T12:00:00Z",
  "business_date": "2026-08-10"
}

List transfers

Use GET /api/v1/client/transfers to list records. Filter with direction_filter, status_filter, and account_id_filter, then paginate with page and page_size.

List responses use this envelope:

{
  "data": [],
  "page": 1,
  "page_size": 20,
  "total": 0
}

Handle current status safely

The public schema returns status as a string but does not yet publish its allowed values or state-transition rules. Do not infer that a transfer is settled, delivered, failed, returned, or reversible from an undocumented value.

Retrieve the latest transfer record before you update your ledger, communicate a completion outcome, create a replacement, or release related funds. When failure_reason is present, reconcile the source account before any follow-on action.

Record transfer data

Store these values with your internal record:

• Roots transfer id
• Source account, destination account, and counterparty IDs
• direction, rail, amount, and currency
• Current status and failure_reason
• rail_refs, business_date, and timestamps
• Creating and approving identity IDs when returned

Next steps

• Read Create transfers for transfer creation and approval actions.
• Read Reconcile balances and transfers for minor-unit reconciliation.
• Read Errors before retrying failed requests.