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

# Create Beneficiary

> Create a new beneficiary for sending payments

Create a beneficiary record to store recipient information for future payouts. After creating a beneficiary, add their payment method details using the payment methods endpoint.

```
POST /v1/beneficiaries
```

<Note>
  Requires an `Idempotency-Key` header.
</Note>

## Request body

<ParamField body="recipient_type" type="string" required>
  Beneficiary type: `"individual"` or `"business"`.
</ParamField>

<ParamField body="customer_name" type="string" required>
  Full name of the beneficiary (individual) or legal business name.
</ParamField>

<ParamField body="customer_email" type="string" required>
  Beneficiary's email address.
</ParamField>

<ParamField body="customer_address" type="string" required>
  Beneficiary's physical address.
</ParamField>

<ParamField body="country" type="string" required>
  Beneficiary's country code (e.g. `CHL`, `MEX`, `BRA`).
</ParamField>

<ParamField body="customer_nickname" type="string">
  A short label for this beneficiary. Defaults to `customer_name` if omitted.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://api.yativo.com/api/v1/beneficiaries' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
      "recipient_type": "individual",
      "customer_name": "Maria Gonzalez",
      "customer_email": "maria.gonzalez@example.com",
      "customer_address": "123 Main Street, Santiago",
      "country": "CHL",
      "customer_nickname": "Maria"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "status": "success",
    "data": {
      "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
      "user_id": "usr-001",
      "recipient_type": "individual",
      "customer_name": "Maria Gonzalez",
      "customer_email": "maria.gonzalez@example.com",
      "customer_nickname": "Maria",
      "country": "CHL",
      "customer_address": "123 Main Street, Santiago",
      "is_archived": false,
      "created_at": "2026-04-02T10:00:00.000000Z",
      "updated_at": "2026-04-02T10:00:00.000000Z"
    }
  }
  ```
</ResponseExample>