Skip to main content
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:  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

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

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

​
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:
⌘I