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

# Listar beneficiários

> Liste os beneficiários cadastrados na conta de recebimento, com filtros por externalId, documento, forma de repasse e situação.

> [!WARNING]
>
> **Funcionalidade em beta.** Contrato em proposta, sujeito a mudanças. Veja o guia [Cadastro de beneficiários](https://docs.delfinance.com.br/guias/split-pagamentos/beneficiarios.md).

Retorna, de forma paginada, os beneficiários cadastrados na conta de recebimento. Use o filtro `externalId` para encontrar o beneficiário de um vendedor a partir do id dele no seu sistema.

## Headers

**x-delbank-api-key** `string` *required*

Sua API key.

**x-delfinance-account-id** `string` *required*

Número da conta de recebimento.

## Query params

Todos os filtros são opcionais e podem ser combinados.

**externalId** `string`

Identificador do beneficiário no seu sistema.

**document** `string`

CPF ou CNPJ do titular (`account.holder.document`), somente números.

**transferType** `string`

Forma de repasse: `INTERNAL`, `PIX_MANUAL` ou `PIX_KEY`.

**status** `string`

Situação do cadastro: `ACTIVE` ou `INACTIVE`.

**page** `number` (default: 1)

Número da página (começa em 1).

**limit** `number` (default: 20)

Itens por página. Máximo de 100.

## Response

Array de beneficiários, cada um com a estrutura descrita em [Cadastrar beneficiário](https://docs.delfinance.com.br/api-reference/split-pagamentos/beneficiarios/cadastrar.md#response). Os dados de paginação vêm no header `Pagination`.

## Paginação

A resposta é um array. Os dados de paginação vêm no header `Pagination`:

```text Header theme={null}
Pagination: {"currentPage":1,"pageSize":20,"pageCount":1,"rowCount":1}
```

| Campo | Descrição |
| - | - |
| `currentPage` | Página retornada |
| `pageSize` | Itens por página (`limit`) |
| `pageCount` | Total de páginas |
| `rowCount` | Total de beneficiários encontrados |

```bash cURL theme={null}
curl --location 'https://apisandbox.delbank.com.br/baas/api/v1/split-payments/beneficiaries?externalId=seller-4821&status=ACTIVE' \
--header 'x-delbank-api-key: {{apiKey}}' \
--header 'x-delfinance-account-id: {{accountId}}'
```

```json 200 theme={null}
[
    {
        "id": "6f1c2a9e-3b7d-4e8a-9c21-5d4f0e7b8a13",
        "bankAccountNumber": "10050",
        "externalId": "seller-4821",
        "transferType": {
            "name": "PIX_MANUAL",
            "description": "Pix Manual",
            "value": 2
        },
        "account": {
            "number": "123456",
            "branch": "0001",
            "type": "CURRENT",
            "participantIspb": "00000000",
            "pixKey": null,
            "holder": {
                "document": "12345678909",
                "name": "Maria Souza",
                "type": "NATURAL"
            }
        },
        "status": {
            "name": "ACTIVE",
            "description": "Ativo",
            "value": 0
        },
        "createdAt": "2026-11-03T14:00:00.000Z",
        "updatedAt": null
    }
]
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.