> ## Documentation Index
> Fetch the complete documentation index at: https://docs.juicyway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Beneficiaries

> Retrieve a paginated list of beneficiaries associated with your account. 

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

```bash theme={null}
GET /beneficiaries
```

## Query Parameters

<ParamField query="limit" type="integer" default="15">
  Number of records to return per page (max: 100)
</ParamField>

<ParamField query="after" type="string">
  Cursor for fetching next page of results
</ParamField>

<ParamField query="before" type="string">
  Cursor for fetching previous page of results
</ParamField>

<ParamField query="currency" type="string">
  Filter by currency (e.g., NGN, USD, CAD)
</ParamField>

<ParamField query="type" type="string">
  Filter by beneficiary type (e.g., bank\_account, crypto\_address)
</ParamField>

## Response Object

<ResponseField name="data" type="array">
  Array of beneficiary objects

  <Expandable title="Beneficiary Properties">
    <ResponseField name="id" type="string">
      Unique identifier for the beneficiary
    </ResponseField>

    <ResponseField name="type" type="string">
      Type of beneficiary (bank\_account, crypto\_address)
    </ResponseField>

    <ResponseField name="currency" type="string">
      Currency code for the beneficiary account
    </ResponseField>

    <ResponseField name="account_name" type="string">
      Name on the bank account (for bank\_account type)
    </ResponseField>

    <ResponseField name="account_number" type="string">
      Account number (for bank\_account type)
    </ResponseField>

    <ResponseField name="bank_name" type="string">
      Bank name (for bank\_account type)
    </ResponseField>

    <ResponseField name="bank_code" type="string">
      Bank identifier code
    </ResponseField>

    <ResponseField name="virtual" type="boolean">
      Whether this is a virtual account
    </ResponseField>

    <ResponseField name="lifetime" type="string">
      Duration of beneficiary validity
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <ResponseField name="before" type="string">
    Cursor for the previous page
  </ResponseField>

  <ResponseField name="after" type="string">
    Cursor for the next page
  </ResponseField>

  <ResponseField name="limit" type="integer">
    Current page size
  </ResponseField>
</ResponseField>

## Examples

### List All Beneficiaries

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.spendjuice.com/beneficiaries?limit=2" \
    -H "Authorization:  YOUR_API_KEY"
  ```

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

  ```python Python theme={null}
  import requests

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

### Success Response

```json theme={null}
{
  "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

<Note>
  For optimal performance:

  * Use reasonable page sizes (15-50 records)

  * Cache results when possible

  * Implement progressive loading in your UI
</Note>

## Error Responses

<AccordionGroup>
  <Accordion title="400 Bad Request">
    ```json theme={null}
    {
      "error": {
        "code": "invalid_request",
        "message": "Invalid query parameters",
        "details": {
          "limit": ["Must be between 1 and 100"]
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="401 Unauthorized">
    ```json theme={null}
    {
      "error": {
        "code": "unauthorized",
        "message": "Invalid or missing API key"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## 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

<Card title="Need Help?">
  For additional assistance:

  * Check our [Error Handling Guide](/errors)

  * Contact [Support](mailto:support@juicyway.com)
</Card>