---
title: "Create Beneficiary"
method: POST
path: "/beneficiaries"
---

# Create Beneficiary

`POST /beneficiaries`

## Request

- Base URL: `https://sandbox.openpayd.com/api`
- URL: `https://sandbox.openpayd.com/api/beneficiaries`
- Auth: API key in header `Authorization`

Create a new parent beneficiary.

## Request body

- object
  - `beneficiaryType` 'RETAIL' | 'CORPORATE', required: Specifies the category of the beneficiary being created. Accepted values are `CORPORATE` (for business entities) and `RETAIL` (for individual persons). Determines which additional fields are required.
  - `friendlyName` string, required: A user-friendly label to help you easily identify this beneficiary within your environment or dashboard. Used for internal reference and display only.
  - `companyName` string: The registered legal name of the beneficiary company. Required when beneficiaryType is set to `CORPORATE`. Must match the official company registration or incorporation documents.
  - `firstName` string: The given (first) name of the individual beneficiary. Required when beneficiaryType is set to `RETAIL`.
  - `lastName` string: The surname or family name of the individual beneficiary. Required when beneficiaryType is set to `RETAIL`.
  - `title` string: An optional courtesy title for the individual beneficiary e.g. `Mr.`, `Ms.`, `Dr.`. Used for display or communication purposes only.
  - `tag` string: Indicates the relationship of the beneficiary to the account holder. Accepted values are `SELF` (the beneficiary is the account holder) or `THIRD_PARTY` (the beneficiary is another individual or organisation).

## Response `200`

200

- object
  - `id` string
  - `beneficiaryType` string
  - `tag` string
  - `accountHolderId` string
  - `title` string
  - `firstName` string
  - `lastName` string
  - `friendlyName` string

## Other responses

- `400`: 400

---

[API](https://skmtc.dev/openpayd/apis/openpayd-api.md) - [All operations](https://skmtc.dev/openpayd/apis/openpayd-api/llms.txt) - [OpenAPI document](https://skmtc.dev/openpayd/apis/openpayd-api/revisions/0f820ef79fab?raw)