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

# List recipients

> List saved recipients with optional filters

## Overview

Retrieve a paginated list of saved recipients belonging to the authenticated merchant. Supports filtering by type, customer, and search term.

## Authentication

<ParamField header="X-Api-Key" type="string" required>
  Your merchant API key
</ParamField>

## Query Parameters

<ParamField query="type" type="string">
  Filter by recipient type.

  **Allowed values:** `BANK_ACCOUNT` | `CRYPTO_ADDRESS`
</ParamField>

<ParamField query="customer_id" type="string">
  Filter by associated customer ID (UUID)

  **Example:** `650e8400-e29b-41d4-a716-446655440000`
</ParamField>

<ParamField query="search" type="string">
  Search by account name, account number, or wallet address

  **Example:** `John`
</ParamField>

<ParamField query="limit" type="integer">
  Results per page

  **Default:** `20` | **Max:** `100`
</ParamField>

<ParamField query="page" type="integer">
  Page number to retrieve

  **Default:** `1`
</ParamField>

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.daya.co/v1/recipients?limit=20&page=1' \
    --header 'X-Api-Key: YOUR_API_KEY'
  ```

  ```bash cURL - Filter by type theme={null}
  curl --request GET \
    --url 'https://api.daya.co/v1/recipients?type=BANK_ACCOUNT&limit=20' \
    --header 'X-Api-Key: YOUR_API_KEY'
  ```

  ```bash cURL - Filter by customer theme={null}
  curl --request GET \
    --url 'https://api.daya.co/v1/recipients?customer_id=650e8400-e29b-41d4-a716-446655440000' \
    --header 'X-Api-Key: YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    type: "BANK_ACCOUNT",
    limit: "20",
    page: "1",
  });

  const response = await fetch(
    `https://api.daya.co/v1/recipients?${params.toString()}`,
    {
      method: "GET",
      headers: {
        "X-Api-Key": "YOUR_API_KEY",
      },
    }
  );

  const recipients = await response.json();
  ```
</CodeGroup>

## Response

<ResponseField name="data" type="array" required>
  Array of recipient objects
</ResponseField>

<ResponseField name="page" type="integer" required>
  Current page number
</ResponseField>

<ResponseField name="limit" type="integer" required>
  Results per page
</ResponseField>

<ResponseField name="total" type="integer" required>
  Total number of recipients matching the query
</ResponseField>

<ResponseField name="total_pages" type="integer" required>
  Total number of pages available
</ResponseField>

### Success Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": [
      {
        "id": "750e8400-e29b-41d4-a716-446655440000",
        "type": "BANK_ACCOUNT",
        "first_name": "John",
        "last_name": "Doe",
        "bank_account": {
          "account_name": "John Doe",
          "account_number_last4": "7890",
          "bank_code": "044",
          "bank_name": "Access Bank"
        },
        "crypto_address": null,
        "us_bank_account": null,
        "swift_bank_account": null,
        "created_at": "2026-01-05T15:04:05Z"
      },
      {
        "id": "850e8400-e29b-41d4-a716-446655440000",
        "type": "CRYPTO_ADDRESS",
        "first_name": null,
        "last_name": null,
        "bank_account": null,
        "crypto_address": {
          "asset": "USDC",
          "chain": "BASE",
          "address": "0x1234567890abcdef1234567890abcdef12345678"
        },
        "us_bank_account": null,
        "swift_bank_account": null,
        "created_at": "2026-01-05T15:04:05Z"
      }
    ],
    "page": 1,
    "limit": 20,
    "total": 2,
    "total_pages": 1
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 400 Bad Request - Invalid query parameter theme={null}
  {
    "error": {
      "code": "VALIDATION_FAILED",
      "message": "Validation failed",
      "request_id": "550e8400-e29b-41d4-a716-446655440000",
      "validation": "type must be one of: BANK_ACCOUNT, CRYPTO_ADDRESS"
    }
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Invalid or missing API key",
      "request_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
  ```
</ResponseExample>

## Pagination

This endpoint uses **page-based pagination**.

1. Make your initial request (optionally with `limit` and `page`)
2. Check `total_pages` to determine how many pages are available
3. Increment `page` to fetch subsequent pages until you reach `total_pages`

## Next Steps

<CardGroup cols={2}>
  <Card title="Create recipient" icon="plus" href="/api-reference/recipients/create-recipient">
    Create a new recipient
  </Card>

  <Card title="Get recipient" icon="magnifying-glass" href="/api-reference/recipients/get-recipient">
    Retrieve a single recipient by ID
  </Card>
</CardGroup>