Create an application recipient

The request body has only two fields — name and payload — but payload is where all the
recipient details go, and it is a free-form map, so it cannot be listed as a fixed set of
fields here.

What goes into payload: the destination.* fields of the transfer create body, written
as flat dot-notation keys. The accepted keys differ per payout method and provider, so the
authoritative list for a given route is the quote requirements endpoint
(GET /api/v2/transfers/quotes/{quote_uuid}/requirements) — every destination.*
path in that schema is a valid payload key.

Two rules to be aware of:

  1. Keys must be the literal flat strings shown below. A nested object
    ({"destination": {"payout_instrument": {...}}}) is not accepted.
  2. Keys that do not start with destination. are stored but ignored when the recipient is
    applied to a transfer.

Example payload for a wire payout:

{
  "destination.beneficiary_info.beneficiary_name": "John Smith",
  "destination.beneficiary_info.beneficiary_address.street": "1 Market St",
  "destination.beneficiary_info.beneficiary_address.city": "San Francisco",
  "destination.beneficiary_info.beneficiary_address.country": "US",
  "destination.payout_instrument.account_holder_name": "John Smith",
  "destination.payout_instrument.bank_name": "HSBC Bank USA",
  "destination.payout_instrument.account_number": "1234567890",
  "destination.payout_instrument.swift_code": "HSBCUSHH",
  "destination.transfer_purpose": "SALARY",
  "destination.is_self_transfer": false
}

The stored recipient is then applied to a transfer by passing its uuid as recipient_id on
transfer creation; explicit destination.* fields in the transfer request override the
recipient's values.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
required

A user-friendly name for this recipient entry. Must not be greater than 255 characters.

Headers
string
Responses

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json