# Replace the worker's entire nominated beneficiary set

**PUT /employers/{employer_id}/employees/{employee_id}/beneficiaries**

Replace the worker's entire nominated beneficiary set. Existing beneficiaries
are deleted and the request body is written as the new set.

Every request must include the **full desired beneficiary list**. Send every
beneficiary you want on record after the write, each with a complete `address`.
Omitting a beneficiary that exists today removes them. There is no partial update
or merge-by-id behaviour.

`percentage` values across all beneficiaries in the request must sum to exactly
100, or the request fails with `400`.



## Servers
- https://payroll-api.getpenfold.dev/v4: https://payroll-api.getpenfold.dev/v4 ()


## Authentication methods
- O auth2 client credentials


## Parameters

### Path parameters

- **employer_id** (string)

- **employee_id** (string)



### Body: application/json (array[object])

- **first_name** (string)

- **last_name** (string)

- **phone** (string | null)

- **relationship** (string)

- **percentage** (integer)

- **address** (object)



## Responses
### 200
Beneficiaries replaced successfully.

#### Body: application/json (array[object])
- **id** (string)

- **first_name** (string)

- **last_name** (string)

- **phone** (string | null)

- **relationship** (string)

- **percentage** (integer)
  Share of benefits as a whole-number percentage (all beneficiaries must sum to 100).

- **address** (object)

- **created_at** (string(date-time))

- **updated_at** (string(date-time))


### 400
Validation failed (e.g. percentages do not sum to 100).

#### Body: application/json (object)
- **error** (string)
  A descriptive error message.

- **validation_errors** (array[object])


### 401
Unauthorized.

#### Body: application/json (object)
- **error** (string)
  A descriptive error message.


### 404
Employee or employer not found.

#### Body: application/json (object)
- **error** (string)
  A descriptive error message.


### 405
Method not allowed

#### Body: application/json (object)
- **error** (string)
  A descriptive error message.



[Powered by Bump.sh](https://bump.sh)