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

GET /beneficiaries

​
Query Parameters

​
limit
integer
default:"15"

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

​
after
string

Cursor for fetching next page of results

​
before
string

Cursor for fetching previous page of results

​
currency
string

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

​
type
string

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

​
Response Object

​
data
array

Array of beneficiary objects

​
pagination
object
​
before
string

Cursor for the previous page

​
after
string

Cursor for the next page

​
limit
integer

Current page size

​
Examples

​
List All Beneficiaries

curl -X GET "https://api.spendjuice.com/beneficiaries?limit=2" \
  -H "Authorization: Bearer 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:

  1. Get the after cursor from the pagination object

  2. Include it in your next request

  3. 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

​
Best Practices

  1. Efficient Filtering

    • Use filters to reduce response size

    • Combine filters for precise results

    • Cache frequently accessed data

  2. Pagination Handling

    • Store cursors temporarily for navigation

    • Implement infinite scroll for large lists

    • Show loading states during fetches

  3. Error Handling

    • Implement proper retry logic

    • Handle rate limits gracefully

    • Log pagination errors

Need Help?

For additional assistance: