List Beneficiaries

This endpoint supports filtering and sorting options to help you manage large numbers of beneficiaries efficiently.

GET /beneficiaries

Query Parameters

integer

default:"15"

Number of records to return per page (max: 100)

string

Cursor for fetching next page of results

string

Cursor for fetching previous page of results

string

Filter by currency (e.g., NGN, USD, CAD)

string

Filter by beneficiary type (e.g., bank_account, crypto_address)

Response Object

array

Array of beneficiary objects

Show Beneficiary Properties

string

Unique identifier for the beneficiary

string

Type of beneficiary (bank_account, crypto_address)

string

Currency code for the beneficiary account

string

Name on the bank account (for bank_account type)

string

Account number (for bank_account type)

string

Bank name (for bank_account type)

string

Bank identifier code

boolean

Whether this is a virtual account

string

Duration of beneficiary validity

object

string

Cursor for the previous page

string

Cursor for the next page

integer

Current page size

Examples

List All Beneficiaries

curl -X GET "https://api.spendjuice.com/beneficiaries?limit=2" \
  -H "Authorization:  YOUR_API_KEY"

const response = await fetch(
  'https://api.spendjuice.com/beneficiaries?limit=2',
  {
    headers: {
      'Authorization': ' YOUR_API_KEY'
    }
  }
);

import requests

response = requests.get(
    'https://api.spendjuice.com/beneficiaries',
    params={'limit': 2},
    headers={'Authorization': ' YOUR_API_KEY'}
)

Success Response

{
  "data": [
    {
      "account_name": "MICHAEL ENITAN ASAJU",
      "account_number": "0821081314",
      "account_type": "savings",
      "address": null,
      "bank_address": null,
      "bank_code": "000014",
      "bank_id": null,
      "bank_name": "ACCESS BANK",
      "bic": null,
      "currency": "NGN",
      "id": "d8c0226b-048c-4c44-9606-a93333f56283",
      "lifetime": "permanent",
      "routing_number": null,
      "sort_code": null,
      "type": "bank_account",
      "user_id": "c545cbc5-9915-4bfb-98ee-3759894feac2",
      "virtual": false
    },
    {
      "account_name": "Michael Asaju",
      "account_number": "8036120312",
      "account_type": "savings",
      "address": null,
      "bank_address": null,
      "bank_code": "100004",
      "bank_id": null,
      "bank_name": "OPAY",
      "bic": null,
      "currency": "NGN",
      "id": "d71efb6e-b7f5-4acd-a729-3da08e36eaed",
      "lifetime": "permanent",
      "routing_number": null,
      "sort_code": null,
      "type": "bank_account",
      "user_id": "c545cbc5-9915-4bfb-98ee-3759894feac2",
      "virtual": false
    }
  ],
  "pagination": {
    "after": "d71efb6e-b7f5-4acd-a729-3da08e36eaed",
    "before": null,
    "limit": 2
  }
}

Pagination

The API uses cursor-based pagination. To fetch subsequent pages:

Get the after cursor from the pagination object
Include it in your next request
Repeat until no more after cursor is returned

For optimal performance:

Use reasonable page sizes (15-50 records)
Cache results when possible
Implement progressive loading in your UI

Error Responses

400 Bad Request

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid query parameters",
    "details": {
      "limit": ["Must be between 1 and 100"]
    }
  }
}

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Best Practices

Efficient Filtering
- Use filters to reduce response size
- Combine filters for precise results
- Cache frequently accessed data
Pagination Handling
- Store cursors temporarily for navigation
- Implement infinite scroll for large lists
- Show loading states during fetches
Error Handling
- Implement proper retry logic
- Handle rate limits gracefully
- Log pagination errors

Need Help?

For additional assistance:

Check our Error Handling Guide
Contact Support

Home

Customers

Payments

Payment Transactions

Transfers

Exchange

Wallet As A Service

Query Parameters

Response Object

Examples

List All Beneficiaries

Success Response

Error Responses

Best Practices

Need Help?

​Query Parameters

​Response Object

​Examples

​List All Beneficiaries

​Success Response

​Pagination

​Error Responses

​Best Practices

Need Help?

Query Parameters

Response Object

Examples

List All Beneficiaries

Success Response

Pagination

Error Responses

Best Practices