Recipients & Address Book

The Application Recipients API (also known as the Recipient Book) allows you to create, manage, and reuse pre-filled payee destination profiles across your application.

By saving beneficiary and payout information in advance, you can initiate cross-border and local payouts using the Transfer API by simply referencing a recipient_name—eliminating the need to repeatedly construct complex destination payloads for every transfer.

Key Benefits

• Frictionless Payouts: Initiate transfers with a single recipient_name handle instead of specifying full bank or wallet details every time.
• Error Reduction: Prevent typos in complex payout fields (e.g. IBANs, routing numbers, account numbers, beneficiary addresses, or tax IDs).
• Centralized Profile Management: Easily manage, update, or remove recipient profiles via API endpoints or through the Harbor Portal.

How Recipients Work with the Transfer API

When creating a recipient profile, you define a user-friendly name and a payload containing pre-filled destination fields mapped in flat dot-notation (e.g. destination.beneficiary_info.beneficiary_name).

When initiating a payout via POST /api/v2/transfers (Create Transfer v2):

1. Pre-filling: Include the "recipient_name": "<name>" parameter in your request body.
2. Payload Expansion: Harbor looks up the saved recipient for your application, expands the dot-notation keys into a structured destination object, and injects them into the transfer payload.
3. Field Overriding (array_replace_recursive): Any destination fields explicitly included in your POST /api/v2/transfers request body will automatically override the pre-filled values stored in the recipient record.

📘

Precedence & Overriding

Explicit fields supplied directly in the destination object of your Transfer API request will always take precedence over the pre-filled values in the saved recipient record.

Step-by-Step Workflow

Step 1: Create an Application Recipient

Store a payee's information in your application's recipient book using dot-notation field paths under payload.

Endpoint: POST /api/v1/applications/recipients

{
  "name": "John Smith Wire",
  "payload": {
    "destination.beneficiary_info.beneficiary_name": "John Smith",
    "destination.payout_instrument.account_number": "1234567890",
    "destination.payout_instrument.routing_number": "021000021",
    "destination.transfer_purpose": "SALARY",
    "destination.is_self_transfer": false
  }
}

{
  "data": {
    "object": "recipient",
    "uuid": "rcpt_0123456789abcdefghij0123456789abcdefghij",
    "name": "John Smith Wire",
    "payload": {
      "destination.beneficiary_info.beneficiary_name": "John Smith",
      "destination.payout_instrument.account_number": "1234567890",
      "destination.payout_instrument.routing_number": "021000021",
      "destination.transfer_purpose": "SALARY",
      "destination.is_self_transfer": false
    },
    "created_at": "2026-06-10T00:00:00+00:00",
    "updated_at": "2026-06-10T00:00:00+00:00"
  }
}

Step 2: Create a Transfer referencing recipient_name

When creating a transfer, pass recipient_name. Harbor will expand the saved recipient payload into the transfer's destination parameters. You can also explicitly pass fields in destination if you need to override any specific value for this particular transfer.

Endpoint: POST /api/v2/transfers

{
  "on_behalf_of": "cus_baWXWeq34SRWe6rbqHIh7iCrGkFXxU7eP9XiEoDA",
  "quote_id": "quote_1234567890abcdef",
  "application_transfer_uuid": "ORD-20260804-001",
  "recipient_name": "John Smith Wire",
  "destination": {
    "transfer_purpose": "CONSULTING_FEE"
  }
}

In this example, the beneficiary name, account number, routing number, and self-transfer flag are populated from the saved recipient profile "John Smith Wire", while transfer_purpose is overridden to "CONSULTING_FEE" for this transfer.

Managing Recipients

You can list, inspect, update, or delete application-level recipients using the following endpoints:

ℹ️

Portal Management

Recipients can also be managed visually by logging into the Harbor Portal under your application settings.