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

# Create Your First Beneficiary

> Add a payment recipient under an existing customer

A beneficiary is created under a customer. The customer ID belongs in the URL, not in the JSON body.

You need `BENEFICIARIES_WRITE` to create a beneficiary. Add `BENEFICIARIES_READ` if your integration reads the beneficiary back after creation.

<Steps>
  <Step title="Prepare the beneficiary payload">
    Use an active BIC known to Nuvera. Either `iban` or `accountNumber` must be present.

    ```json theme={null}
    {
      "country": "<beneficiary-country-alpha-2>",
      "companyName": "Acme Supplier GmbH",
      "address": "Taunusanlage 12, Frankfurt",
      "zipCode": "60325",
      "currencyCode": "USD",
      "accountNumber": "1234567890",
      "bankBic": "<valid-bank-bic>"
    }
    ```
  </Step>

  <Step title="Create the beneficiary under a customer">
    Generate the signed JWT with `uri` set to `/api/v1/customers/{customerId}/beneficiaries` after replacing `{customerId}` with the actual customer ID.

    ```bash theme={null}
    CUSTOMER_ID="<customer-id>"
    BODY='{"country":"<beneficiary-country-alpha-2>","companyName":"Acme Supplier GmbH","address":"Taunusanlage 12, Frankfurt","zipCode":"60325","currencyCode":"USD","accountNumber":"1234567890","bankBic":"<valid-bank-bic>"}'
    TOKEN="<signed-request-jwt>"

    curl "https://rest-api.nuvera.global/api/v1/customers/$CUSTOMER_ID/beneficiaries" \
      -H "x-api-key: $NUVERA_API_KEY" \
      -H "Authorization: Bearer $TOKEN" \
      -H "content-type: application/json" \
      --data "$BODY"
    ```
  </Step>
</Steps>

## Field notes

| Field               | Required?   | Notes                                               |
| ------------------- | ----------- | --------------------------------------------------- |
| `country`           | Required    | Beneficiary country as an ISO alpha-2 country code. |
| `companyName`       | Required    | Legal or business name of the beneficiary.          |
| `address`           | Required    | Beneficiary address.                                |
| `zipCode`           | Required    | Postal code.                                        |
| `currencyCode`      | Required    | Currently `USD`.                                    |
| `bankBic`           | Required    | Active SWIFT/BIC known to Nuvera.                   |
| `iban`              | Conditional | Required when `accountNumber` is not provided.      |
| `accountNumber`     | Conditional | Required when `iban` is not provided.               |
| `wireRoutingNumber` | Optional    | Add only when required for the payout rail.         |
| `achRoutingNumber`  | Optional    | Add only when required for the payout rail.         |
| `intermediaryBank`  | Optional    | Add only when required for the payout rail.         |

New beneficiaries enter review. Use `GET /api/v1/customers/{customerId}/beneficiaries/{id}` and the activity endpoint to track the record. For the complete schema, open the [API Reference](/api-reference/introduction).