1. Beneficiaries
CrossFX Payment APIs
  • Guides
    • CrossFX API Documentation
    • Support & Contact
    • API Basics
    • Authentication Guide
    • FX Rates
      • FX Rates Guide
    • Corridors
      • Supported Corridors Guide
    • Banks
      • Fetching Banks List Guide
      • Fetching Bank Branches Guide
    • Sanctions
      • Sanctions Screening Guide
    • Beneficiaries
      • Create Beneficiary Guide
      • Get Beneficiary Guide
    • Transfers
      • Generate Quote Guide
      • Confirm Transfer Guide
      • Get Transfer Status Guide
    • Crypto Deposit Address
      • Crypto Deposit Address Guide
    • Payments
      • Initiate Deposit Guide
      • Initiate Payout Guide
    • Webhooks
      • Webhooks Guide
      • Webhook Subscriptions Guide
      • Webhook Events Guide
      • Webhook Delivery Attempts Guide
    • Sandbox
      • Sandbox Data & Testing Guide
  1. Beneficiaries

Get Beneficiary Guide

CROSSFX API · BENEFICIARIES
Retrieve a saved beneficiary by identifier.
Read back the beneficiary record CrossFX holds before quoting, rendering a saved recipient or reconciling your own records.
This is a read-only operation with no side effects, so it is safe to call repeatedly.
Lookup by identifierRead-onlyNo side effectsStored recipient

How it works#

Use the same beneficiary identifier returned when the recipient was created. CrossFX looks up that resource and returns the stored beneficiary.
01 · STORED VALUE
Beneficiary identifier
identifier
→
02 · LOOKUP
Get beneficiary
Read-only API call
→
03 · RESPONSE
Stored beneficiary
Identity · country · payout details
Lookup by identifier
Use the value from creation
Retrieve the beneficiary using the `identifier` returned when the resource was created.
Stored record
Read what CrossFX holds
The response contains the beneficiary's stored identity, country and payout details.
Safe to repeat
No side effects
This endpoint only reads the resource and can be called repeatedly.

When to use Get Beneficiary#

Before quoting
Confirm the recipient exists
Read the beneficiary before generating a quote against its `identifier`.
Review screens
Render a saved recipient
Display the beneficiary record without keeping a complete local copy of the payout details.
Reconciliation
Compare records
Reconcile your own beneficiary data against the record currently stored by CrossFX.

Before you start#

Authentication
Use a valid bearer token
See the [Authentication Guide](/authentication-guide-2385173m0).
Beneficiary identifier
Use the value returned at creation
You need the `identifier` returned by the [Create Beneficiary Guide](/create-beneficiary-guide-2167568m0).

Get a beneficiary#

Get Beneficiary
Retrieve the stored recipient
`GET /api/v1/beneficiaries/{beneficiary_id}`

Open the API Reference for the full response schema and an interactive console.
REQUEST & RESPONSE
Send the beneficiary's identifier in the path.

The endpoint returns the stored beneficiary resource.

Use identifier, not id#

This is the most important implementation detail on the endpoint.
PATH PARAMETER
The {beneficiary_id} path value is the beneficiary identifier.
Do not send the numeric id that also appears in the Create Beneficiary response. Store and use the identifier string.
USE THIS
identifier
The reusable string issued when the beneficiary is created.
DO NOT USE
id
The numeric id returned by Create Beneficiary is not the value expected in this path.

Response differences#

The Get Beneficiary response is slightly narrower than the Create Beneficiary response.
RETURNED
Stored beneficiary data
Identity, country and payout details are returned as the platform currently holds them.
OMITTED ON READ
id · updated_at
These fields may appear in the Create Beneficiary response but are not returned by Get Beneficiary.
ALSO NOT RETURNED
entity_type and date_of_birth are not returned by this endpoint, matching the Create Beneficiary response behaviour.

Business rules#

RULE 01
Use identifier
The path expects the beneficiary identifier string, not the numeric create-response id.
RULE 02
Read response is narrower
id and updated_at are omitted from the Get Beneficiary response.
RULE 03
Reads are repeatable
The request has no side effects and is safe to repeat whenever your application needs the current stored record.
RULE 04
Unknown means 404
An unknown beneficiary identifier never returns an empty successful response.

Errors#

Every error below returns the CrossFX platform error envelope, with error first and error_id last.
SUPPORT IDENTIFIER
Keep the error_id
Quote the returned error_id when contacting CrossFX support so the request can be located in platform logs.
HTTPcodeTriggerWhat you do
404NOT_FOUNDNo beneficiary matches the identifierCheck the value you stored when the beneficiary was created.
401—The Authorization header is missing, malformed, or the token has expiredRequest a new token and retry. The body is { "message": "Unauthorized" }.

Related#

Create Beneficiary Guide
Create and store the identifier
Register a beneficiary and save the `identifier` used by this endpoint.
API Basics
Understand common errors
See the shared `404` and `401` behaviours used by this endpoint.
Sandbox Data & Testing Guide
Test beneficiary data
See the identifiers and phone formats used by Sandbox beneficiaries.
Modified at 2026-09-11 12:18:34
Previous
Create Beneficiary Guide
Next
Generate Quote Guide
Built with