# Recipients

List and create saved payout recipients. Transfers are sent to a saved recipient id.

A recipient is a saved payout destination. You create a recipient once, then reference its Dolafy `id` when you [send a transfer](/docs/banking-transfers). In v1, recipients are **BRL PIX** destinations.

## List recipients

```http
GET /v1/banking/recipients
x-api-key: dlfy_live_...
```

### Query parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `limit` | `50` | Page size, capped at `100`. |
| `offset` | `0` | Number of records to skip. |
| `currency` | — | Filter by recipient currency, for example `BRL`. |
| `rail` | — | Filter by payment rail, for example `pix`. |

### Response

```json
{
  "recipients": [
    {
      "id": "9a5b47c1-234d-4841-a5b8-d1b790f774be",
      "name": "Acme Ltda",
      "type": "pix",
      "currency": "BRL",
      "rails": ["pix"],
      "createdAt": "2026-06-25T12:00:00.000Z",
      "updatedAt": "2026-06-25T12:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}
```

Provider recipient ids, account numbers, and PIX keys are never returned.

## Create a recipient

```http
POST /v1/banking/recipients
x-api-key: dlfy_live_...
Idempotency-Key: recipient-acme-pix-001
content-type: application/json
```

Current scope: **BRL PIX only** (`currency: "BRL"`, `rail: "pix"`), create-only. `Idempotency-Key` is required — see [Errors & Idempotency](/docs/errors).

### Request

```json
{
  "name": "Acme Ltda",
  "type": "business",
  "currency": "BRL",
  "rail": "pix",
  "pix": {
    "key": "finance@acme.example",
    "documentNumber": "12345678000199"
  },
  "email": "finance@acme.example"
}
```

### Response

```json
{
  "recipient": {
    "id": "9a5b47c1-234d-4841-a5b8-d1b790f774be",
    "name": "Acme Ltda",
    "type": "pix",
    "currency": "BRL",
    "rails": ["pix"],
    "createdAt": "2026-06-25T12:00:00.000Z",
    "updatedAt": "2026-06-25T12:00:00.000Z"
  },
  "idempotencyKey": "recipient-acme-pix-001"
}
```

### Notes

- The returned `recipient.id` is Dolafy's identifier. Use it directly as `recipientId` when sending a transfer.
- Creating a recipient with a PIX key that already exists returns `409 recipient_already_exists`, unless you are replaying the same idempotency key.
- You can also create recipients from the dashboard; API transfers can pay any saved recipient regardless of where it was created.