Skip to main content
GET
/
v1
/
payouts
/
beneficiaries
Fetch Payout Beneficiaries
curl --request GET \
  --url https://carbonapistagingsecure.getcarbon.co/baas/api/v1/payouts/beneficiaries \
  --header 'apikey: <api-key>' \
  --header 'x-carbon-key: <x-carbon-key>'
{
  "status": "success",
  "message": "Beneficiaries fetched successfully",
  "data": [
    {
      "bank_code": "058",
      "bank_name": "Guaranty Trust Bank",
      "account_number": "0123456789",
      "account_name": "JOHN DOE"
    },
    {
      "bank_code": "044",
      "bank_name": "Access Bank",
      "account_number": "0987654321",
      "account_name": "JANE SMITH"
    }
  ],
  "pagination": {
    "total": 45,
    "page": 1,
    "limit": 20,
    "pages": 3
  }
}

​
Overview

The Fetch Payout Beneficiaries endpoint retrieves a deduplicated list of all unique beneficiaries that have received payouts from your account. This is useful for displaying a list of frequent recipients when creating new payouts.

​
Usage Examples

​
Basic Usage

Fetch the first page of beneficiaries with default limit: 
GET /v1/payouts/beneficiaries

​
Pagination

Fetch a specific page with custom limit: 
GET /v1/payouts/beneficiaries?page=2&limit=50
Search for beneficiaries by account name or number: 
GET /v1/payouts/beneficiaries?search=john

​
Combined Parameters

Use multiple parameters together: 
GET /v1/payouts/beneficiaries?page=1&limit=10&search=access

​
Error Handling

Status CodeDescription
200Success - Beneficiaries retrieved successfully
400Bad Request - Invalid query parameters
401Unauthorized - Missing or invalid API key
500Internal Server Error - Unexpected server error

​
Notes

  • The endpoint returns deduplicated beneficiaries based on unique combinations of bank_code and account_number
  • Search functionality is case-insensitive and matches partial strings in both account_number and account_name fields
  • If no beneficiaries are found, an empty array will be returned in the data field
  • The pagination object always reflects the current state, even when no results are found

Authorizations

​
apikey
string
header
required

Provide your API key in the 'apikey' header.

Headers

​
x-carbon-key
string
required

Query Parameters

​
page
integer
default:1
Required range: x >= 1
​
limit
integer
default:20
Required range: x >= 1
​
search
string

Response

OK

The response is of type object.