Managing Recipients

Before You Start

Read the following guides before proceeding:

Overview

Recipients belong to the corporation, not to the employee who created them. Every employee with a
corporation token can read them; changing them requires TransactionManage or TransactionSu.

List Recipients

GET /api/v1/recipients

Query parameters:

Response:

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "personal_info": {
        "first_name": "Alex",
        "last_name": "Grey",
        "is_business": false,
        "nick_name": ""
      },
      "payment_details": [
        {
          "id": "64120850-73a1-4df5-a074-d463258c9deb",
          "type": "Sepa",
          "currencies": ["EUR"],
          "sepa": { "iban": "DE89370400440532013000", "bic": "COBADEFF" }
        }
      ]
    }
  ]
}

Filters

Four filter endpoints, each returning the same shape as the list. All take the same pagination and
sort parameters.

type accepts Crypto, Sepa, FasterPayment, Ach, Swift, Spei, Card, Pix, FpsHk,
Imps, Instapay, BiFast, Nip, Ipp, Pse.

The filters are not combinable — each takes exactly one criterion. To filter on two dimensions, filter
on the more selective one and narrow the result client-side.

Read One Recipient

GET /api/v1/recipients/{recipientId}

Path parameters:

Returns a single recipient in the same shape as one data[] entry.

Update the Identity

PUT /api/v2/recipients/{recipientId}

Requires TransactionSu or TransactionManage. Takes the same body as
POST /api/v2/recipients — identity fields plus a type and its details object — and updates both in
one call.

PUT /api/v1/recipients/{recipientId}

Updates the identity only:

{
  "first_name": "Alex",
  "last_name": "Grey",
  "is_business": false,
  "nick_name": "Alex — EUR"
}

Add Payment Details

POST /api/v1/recipients/{recipientId}/payment_details

Requires TransactionSu or TransactionManage. Use this to add a second rail to an existing
recipient.

Request body:

{
  "type": "FasterPayment",
  "currencies": ["GBP"],
  "faster_payments": {
    "account_number": "12345678",
    "sort_code": "123456"
  }
}

Response:

Returns the created payment details, including their id.

Field names and formats are identical to
Creating a Recipient — including faster_payments on the way in and
faster_payment on the way out.

Update Payment Details

PUT /api/v1/recipients/{recipientId}/payment_details/{paymentDetailsId}

Requires TransactionSu or TransactionManage.

Path parameters:

Takes the same body as the create-details call and replaces the details.

Delete Payment Details

DELETE /api/v1/recipients/{recipientId}/payment_details/{paymentDetailsId}

Requires TransactionSu or TransactionManage.

Response:

{}

Removes one rail from the recipient, leaving the recipient itself in place.

Delete a Recipient

DELETE /api/v1/recipients/{recipientId}

Requires TransactionSu or TransactionManage.

Response:

{}

Deleting a recipient invalidates every recipient_id reference to it. A corridor estimate naming a
deleted recipient fails with Recipient not found or does not belong to you — the same error a
foreign recipient produces.

Increment Usage

POST /api/v1/recipients/{recipientId}/usage

Requires TransactionSu, TransactionCreate or TransactionManage.

Response:

{}

Increments the recipient's usage counter, which is what sort=usage orders by. The API does not
increment it automatically — a transfer to a recipient does not change its usage count. Call this after
a successful payout if you want most-recently-used ordering to reflect real activity.

Code

// Add a second rail to an existing recipient
const response = await fetch(`${baseUrl}/api/v1/recipients/${recipientId}/payment_details`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${corporationToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'FasterPayment',
    currencies: ['GBP'],
    faster_payments: { account_number: '12345678', sort_code: '123456' }
  })
});
const details = await response.json();

# Add a second rail to an existing recipient
response = requests.post(
    f"{base_url}/api/v1/recipients/{recipient_id}/payment_details",
    headers={
        "Authorization": f"Bearer {corporation_token}",
        "Content-Type": "application/json",
    },
    json={
        "type": "FasterPayment",
        "currencies": ["GBP"],
        "faster_payments": {"account_number": "12345678", "sort_code": "123456"},
    },
)
details = response.json()

// Add a second rail to an existing recipient
body, _ := json.Marshal(map[string]interface{}{
    "type":       "FasterPayment",
    "currencies": []string{"GBP"},
    "faster_payments": map[string]string{
        "account_number": "12345678",
        "sort_code":      "123456",
    },
})

req, _ := http.NewRequest("POST", baseURL+"/api/v1/recipients/"+recipientId+"/payment_details", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer "+corporationToken)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Webhooks

Endpoint: POST {your_webhook_base_url}/v2/webhooks/recipients

Delivered when a recipient is created or updated. See Webhooks.

Error Handling

{
  "error_reason": "ErrorInvalidField",
  "error_description": "Invalid format for catalog index",
  "error_category": {
    "category": "CategoryValidationFailure",
    "http_status_code": 400
  },
  "error_details": [
    { "key": "field", "details": "catalog_index" }
  ]
}

Validation Errors (400)

Permission Errors (403)

Server Errors (500)