Beneficiaries API

The Beneficiaries API lets you save and manage recipients so you can initiate payouts without re-entering phone numbers and network details every time. Beneficiaries are scoped to your customer account and can be searched, updated, or removed at any time.

POST/v1/beneficiariesCreate a beneficiary

GET/v1/beneficiariesList beneficiaries

GET/v1/beneficiaries/:idGet a beneficiary

PATCH/v1/beneficiaries/:idUpdate a beneficiary

DELETE/v1/beneficiaries/:idDelete a beneficiary

Create a beneficiary

POST/v1/beneficiaries

Saves a new recipient to your account. You can reference the returned id when creating payouts to skip entering phone and network details inline.

Request body

Field	Type	Required	Description
`name`	`string`	Yes	Full name of the recipient.
`phone`	`string`	Yes	Recipient mobile number in E.164 format (e.g. `+256700123456`).
`network`	`string`	Yes	Mobile money network slug. See Supported Networks.
`nickname`	`string`	No	Short label for display in dashboards and reports.

Response

Field	Type	Description
`id`	`string`	Unique beneficiary identifier.
`customer_id`	`string`	Owning customer account ID.
`name`	`string`	Recipient full name.
`phone`	`string`	Mobile number in E.164 format.
`network`	`string`	Mobile money network slug.
`nickname`	`string \| null`	Optional short label.
`created_at`	`string`	ISO 8601 creation timestamp.
`updated_at`	`string`	ISO 8601 last-updated timestamp.

bash

"color:#ff7b72">curl "color:#79c0ff">-X POST https://api-sandbox.settlra.com/v1/beneficiaries \
  "color:#79c0ff">-H "Authorization: Bearer pk_test_your_key" \
  "color:#79c0ff">-H "Content-Type: application/json" \
  "color:#79c0ff">-d '{
    "name": "Grace Nakamura",
    "phone": "+256700123456",
    "network": "mtn_uganda",
    "nickname": "Grace"
  }'

javascript

"color:#ff7b72">import Settlra "color:#ff7b72">from '@settlra/node';

"color:#ff7b72">const client = "color:#ff7b72">new Settlra({ apiKey: process.env.SETTLRA_API_KEY });

"color:#ff7b72">const beneficiary = "color:#ff7b72">await client.beneficiaries.create({
  name: 'Grace Nakamura',
  phone: '+256700123456',
  network: 'mtn_uganda',
  nickname: 'Grace',
});

console.log(beneficiary.id); "color:#8b949e">// "ben_01HXYZ9ABCDEF"

json

{
  "id": "ben_01HXYZ9ABCDEF",
  "customer_id": "cust_abc123",
  "name": "Grace Nakamura",
  "phone": "+256700123456",
  "network": "mtn_uganda",
  "nickname": "Grace",
  "created_at": "2025-06-23T14:22:01Z",
  "updated_at": "2025-06-23T14:22:01Z"
}

List beneficiaries

GET/v1/beneficiaries

Returns a paginated list of all saved beneficiaries for your account. Use the search parameter to filter by name, phone, or nickname.

Query parameters

Parameter	Type	Default	Description
`search`	`string`	—	Full-text search across name, phone, and nickname.
`network`	`string`	—	Filter by network slug (e.g. `mtn_uganda`).
`limit`	`number`	20	Number of results per page (1–100).
`offset`	`number`	0	Pagination offset.

Response

Field	Type	Description
`data`	`Beneficiary[]`	Array of beneficiary objects.
`total`	`number`	Total count matching the query.
`limit`	`number`	Page size used.
`offset`	`number`	Current offset.

bash

"color:#ff7b72">curl "https://api-sandbox.settlra.com/v1/beneficiaries?search=Grace&limit=10" \
  "color:#79c0ff">-H "Authorization: Bearer pk_test_your_key"

javascript

"color:#ff7b72">const { data, total } = "color:#ff7b72">await client.beneficiaries.list({
  search: 'Grace',
  limit: 10,
});

console.log(`Found ${total} beneficiaries`);

Get a beneficiary

GET/v1/beneficiaries/:id

Retrieves a single beneficiary by ID.

bash

"color:#ff7b72">curl https://api-sandbox.settlra.com/v1/beneficiaries/ben_01HXYZ9ABCDEF \
  "color:#79c0ff">-H "Authorization: Bearer pk_test_your_key"

javascript

"color:#ff7b72">const beneficiary = "color:#ff7b72">await client.beneficiaries.retrieve('ben_01HXYZ9ABCDEF');
console.log(beneficiary.name); "color:#8b949e">// "Grace Nakamura"

Update a beneficiary

PATCH/v1/beneficiaries/:id

Updates one or more fields on an existing beneficiary. Only the fields you provide are changed — omitted fields remain unchanged.

Request body

Field	Type	Required	Description
`name`	`string`	No	Updated full name.
`phone`	`string`	No	Updated phone number in E.164 format.
`network`	`string`	No	Updated network slug.
`nickname`	`string`	No	Updated short label.

bash

"color:#ff7b72">curl "color:#79c0ff">-X PATCH https://api-sandbox.settlra.com/v1/beneficiaries/ben_01HXYZ9ABCDEF \
  "color:#79c0ff">-H "Authorization: Bearer pk_test_your_key" \
  "color:#79c0ff">-H "Content-Type: application/json" \
  "color:#79c0ff">-d '{
    "nickname": "Grace K"
  }'

javascript

"color:#ff7b72">const updated = "color:#ff7b72">await client.beneficiaries.update('ben_01HXYZ9ABCDEF', {
  nickname: 'Grace K',
});

console.log(updated.nickname); "color:#8b949e">// "Grace K"

Delete a beneficiary

DELETE/v1/beneficiaries/:id

Permanently removes a beneficiary from your account. Existing payouts referencing this beneficiary are unaffected.

Response

Field	Type	Description
`id`	`string`	ID of the deleted beneficiary.
`deleted`	`boolean`	Always `true` on success.

bash

"color:#ff7b72">curl "color:#79c0ff">-X DELETE https://api-sandbox.settlra.com/v1/beneficiaries/ben_01HXYZ9ABCDEF \
  "color:#79c0ff">-H "Authorization: Bearer pk_test_your_key"

javascript

"color:#ff7b72">const result = "color:#ff7b72">await client.beneficiaries.del('ben_01HXYZ9ABCDEF');
console.log(result.deleted); "color:#8b949e">// "color:#79c0ff">true

json

{
  "id": "ben_01HXYZ9ABCDEF",
  "deleted": true
}