Beneficiaries

Beneficiary management

Get all beneficiaries

get

/api/v1/

/beneficiaries

Retrieve a list of all beneficiaries for the authenticated tenant. Returns only active beneficiaries (not soft-deleted). Each beneficiary represents a recipient who can receive money transfers.

Authorizations

ApiKeyAuth

x-api-keystringRequired

API key for tenant authentication

Responses

200

Successfully retrieved list of beneficiaries

application/json

get

/beneficiaries

HTTPcURLJavaScriptPython

GET /api/v1/beneficiaries HTTP/1.1
Host: 
x-api-key: YOUR_API_KEY
Accept: */*

200

Successfully retrieved list of beneficiaries

[
  {
    "beneficiary_id": "b1a2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "created_at": "2025-10-05T10:00:00.000Z",
    "updated_at": "2025-11-10T15:20:00.000Z",
    "deleted_at": null,
    "first_name": "Thabo",
    "middle_name": null,
    "last_name": "Molefe",
    "country": "South Africa",
    "phone_number": "[phone]",
    "daily_limit": 5000,
    "monthly_limit": 50000
  },
  {
    "beneficiary_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
    "created_at": "2025-09-15T08:30:00.000Z",
    "updated_at": "2025-11-05T12:45:00.000Z",
    "deleted_at": null,
    "first_name": "Amina",
    "middle_name": "Nakato",
    "last_name": "Musoke",
    "country": "Uganda",
    "phone_number": "[phone]",
    "daily_limit": 10000,
    "monthly_limit": 100000
  }
]

Create beneficiary

post

/api/v1/

/beneficiaries

Create a new beneficiary (money recipient) for the authenticated tenant. The beneficiary's country must match supported destination countries in available corridors. Phone number must be in international E.164 format. Daily and monthly limits must be at least 1.

Authorizations

ApiKeyAuth

x-api-keystringRequired

API key for tenant authentication

Body

application/json

first_namestring · min: 1Required

Beneficiary's first name

middle_namestring | nullOptional

Beneficiary's middle name (optional)

last_namestring · min: 1Required

Beneficiary's last name

countrystring · min: 1Required

Beneficiary's country. Must match a supported destination country in available corridors

phone_numberstringRequired

International phone number in E.164 format (e.g., [phone])

daily_limitnumber · min: 1Required

Maximum amount this beneficiary can receive per day

monthly_limitnumber · min: 1Required

Maximum amount this beneficiary can receive per month

Responses

201

Beneficiary created successfully

application/json

400

Bad request - Invalid input data

401

Unauthorized - Invalid or missing API key

409

Conflict - Beneficiary already exists

500

Internal server error

post

/beneficiaries

HTTPcURLJavaScriptPython

POST /api/v1/beneficiaries HTTP/1.1
Host: 
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 139

{
  "first_name": "Thabo",
  "last_name": "Molefe",
  "country": "South Africa",
  "phone_number": "[phone]",
  "daily_limit": 5000,
  "monthly_limit": 50000
}

South African BeneficiaryUgandan Beneficiary with Middle Name

{
  "beneficiary_id": "text",
  "created_at": "2025-12-12T09:29:25.845Z",
  "updated_at": null,
  "deleted_at": null,
  "first_name": "text",
  "middle_name": null,
  "last_name": "text",
  "country": "text",
  "phone_number": "text",
  "daily_limit": 1,
  "monthly_limit": 1
}

Get beneficiary details

get

/api/v1/

/beneficiaries/{beneficiaryId}

Retrieve detailed information for a specific beneficiary by ID. Returns 404 if the beneficiary doesn't exist or has been deleted. Only returns beneficiaries belonging to the authenticated tenant.

Authorizations

ApiKeyAuth

x-api-keystringRequired

API key for tenant authentication

Path parameters

beneficiaryIdstringRequired

Responses

200

Successfully retrieved beneficiary details

application/json

404

Not found - Beneficiary does not exist or has been deleted

application/json

get

/beneficiaries/{beneficiaryId}

HTTPcURLJavaScriptPython

GET /api/v1/beneficiaries/{beneficiaryId} HTTP/1.1
Host: 
x-api-key: YOUR_API_KEY
Accept: */*

{
  "beneficiary_id": "b1a2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "created_at": "2025-10-05T10:00:00.000Z",
  "updated_at": "2025-11-10T15:20:00.000Z",
  "deleted_at": null,
  "first_name": "Thabo",
  "middle_name": null,
  "last_name": "Molefe",
  "country": "South Africa",
  "phone_number": "[phone]",
  "daily_limit": 5000,
  "monthly_limit": 50000
}

Update beneficiary

put

/api/v1/

/beneficiaries/{beneficiaryId}

Update an existing beneficiary's information. All fields from the create operation can be updated. The beneficiary must exist and belong to the authenticated tenant. Returns 404 if not found.

Authorizations

ApiKeyAuth

x-api-keystringRequired

API key for tenant authentication

Path parameters

beneficiaryIdstringRequired

Body

application/json

first_namestring · min: 1Required

middle_namestring | nullOptional

last_namestring · min: 1Required

countrystring · min: 1Required

phone_numberstringRequired

International phone number in E.164 format

daily_limitnumber · min: 1Required

monthly_limitnumber · min: 1Required

Responses

200

Beneficiary updated successfully

application/json

400

Bad request - Invalid input data

401

Unauthorized - Invalid or missing API key

404

Not found - Beneficiary does not exist

application/json

500

Internal server error

put

/beneficiaries/{beneficiaryId}

HTTPcURLJavaScriptPython

PUT /api/v1/beneficiaries/{beneficiaryId} HTTP/1.1
Host: 
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 132

{
  "first_name": "text",
  "middle_name": null,
  "last_name": "text",
  "country": "text",
  "phone_number": "text",
  "daily_limit": 1,
  "monthly_limit": 1
}

{
  "beneficiary_id": "text",
  "created_at": "2025-12-12T09:29:25.845Z",
  "updated_at": null,
  "deleted_at": null,
  "first_name": "text",
  "middle_name": null,
  "last_name": "text",
  "country": "text",
  "phone_number": "text",
  "daily_limit": 1,
  "monthly_limit": 1
}

Delete beneficiary

delete

/api/v1/

/beneficiaries/{beneficiaryId}

Soft delete a beneficiary by ID. This marks the beneficiary as deleted but preserves the record in the database. The beneficiary will no longer appear in list operations or be available for new transactions.

Authorizations

ApiKeyAuth

x-api-keystringRequired

API key for tenant authentication

Path parameters

beneficiaryIdstringRequired

Responses

200

Beneficiary deleted successfully

application/json

401

Unauthorized - Invalid or missing API key

404

Not found - Beneficiary does not exist

application/json

500

Internal server error

delete

/beneficiaries/{beneficiaryId}

HTTPcURLJavaScriptPython

DELETE /api/v1/beneficiaries/{beneficiaryId} HTTP/1.1
Host: 
x-api-key: YOUR_API_KEY
Accept: */*

{
  "id": "text"
}