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

# Add POD Beneficiaries to an Account

> Designate one or more payable-on-death (POD) beneficiaries on an account. A beneficiary is a person linked to the account by a relationship, each entitled to an allocated percentage of the account funds.

## Overview

Subject to bank approval, a customer can designate beneficiaries of their account. This is commonly known as a **payable-on-death (POD)** designation: on the account holder's death, the balance passes to the named beneficiaries in the allocated proportions.

In the Synctera platform a beneficiary is modeled as:

* A **person** holding the beneficiary's identification (name, date of birth, SSN, contact information). Beneficiaries are not customers of the bank, so they are stored as `PROSPECT`s and are not run through KYC.
* An **account relationship** of type `BENEFICIARY` linking that person to the account and carrying the `ownership_percentage` the beneficiary is entitled to.

Key characteristics:

* Reuses the existing [Persons](/v2/docs/create-a-personal-customer) and account [Relationships](/v2/reference/createaccountrelationship) APIs; no special endpoint.
* Each `BENEFICIARY` relationship carries an `ownership_percentage`. An account can have multiple beneficiaries whose percentages represent the share of funds each is entitled to receive.

## Prerequisites

This guide assumes you are familiar with:

* [Need to Know — Environments](/v2/reference/need-to-know#environments)
* [Need to Know — Authentication](/v2/reference/need-to-know#authentication)

It also assumes you have already created a [personal](/v2/docs/create-a-personal-customer) or [business](/v2/docs/create-a-business) customer and [opened an account](/v2/docs/create-accounts-guide) for them.

The curl examples authenticate with an `apikey` environment variable. Some examples depend on identifiers generated by previous steps; these are shown as placeholders like `{ACCOUNT_ID}`.

## The account relationship object

A `BENEFICIARY` designation is an account relationship with the following key fields:

| Field                  | Description                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| `id`                   | Unique identifier of the relationship (read-only, assigned on creation). Used for `GET`, `PUT`, and `DELETE`. |
| `relationship_type`    | The kind of relationship. Set to `BENEFICIARY` for a POD designation.                                         |
| `customer_id`          | The person linked to the account as the beneficiary.                                                          |
| `ownership_percentage` | The share of funds the beneficiary is entitled to receive (0–100).                                            |
| `created_at`           | Date and time the relationship was created (read-only).                                                       |

```json theme={"system"}
{
  "id": "5f4ff599-7c29-4f69-a3d9-e103e151afbd",
  "relationship_type": "BENEFICIARY",
  "customer_id": "3b1e...",
  "ownership_percentage": 50,
  "created_at": "2026-08-26T18:09:12.881517Z"
}
```

See the [API reference](/v2/reference/createaccountrelationship) for the full request and response schemas.

## Adding a beneficiary

<Steps>
  <Step title="Create the beneficiary as a person">
    Collect at a minimum the beneficiary's name and contact information, and create a person with [POST /v2/persons](/v2/reference/createperson).

    ```shell theme={"system"}
    curl \
      -X POST \
      -H "Authorization: Bearer $apikey" \
      -H 'Content-Type: application/json' \
      https://api.synctera.com/v2/persons \
      --data-binary '
      {
        "status": "PROSPECT",
        "is_customer": false,
        "first_name": "Jordan",
        "last_name": "Rivera",
        "dob": "1990-08-21",
        "ssn": "123-45-6789",
        "email": "jordan@example.com",
        "phone_number": "+12124567890",
        "legal_address": {
          "address_line_1": "50 Main St",
          "city": "New York",
          "state": "NY",
          "postal_code": "12345",
          "country_code": "US"
        }
      }'
    ```

    The response includes the system-generated `id`, used to link the beneficiary to the account:

    ```json theme={"system"}
    {
      "id": "{BENEFICIARY_PERSON_ID}",
      "status": "PROSPECT",
      "verification_status": "UNVERIFIED",
      "is_customer": false,
      "first_name": "Jordan",
      "last_name": "Rivera"
    }
    ```

    <Info>
      Beneficiaries are prospects, not customers. They do not need to pass KYC, so there is no verification step.
    </Info>
  </Step>

  <Step title="Link the beneficiary to the account">
    Create an account relationship of type `BENEFICIARY` with [POST /v2/accounts/\{ACCOUNT\_ID}/relationships](/v2/reference/createaccountrelationship). Provide the beneficiary's person ID in `customer_id`, and use `ownership_percentage` to record the share of funds they are entitled to.

    ```shell theme={"system"}
    curl \
      -X POST \
      -H "Authorization: Bearer $apikey" \
      -H 'Content-Type: application/json' \
      https://api.synctera.com/v2/accounts/{ACCOUNT_ID}/relationships \
      --data-binary '
      {
        "relationship_type": "BENEFICIARY",
        "customer_id": "{BENEFICIARY_PERSON_ID}",
        "ownership_percentage": 50
      }'
    ```

    The response returns the created relationship:

    ```json theme={"system"}
    {
      "id": "{RELATIONSHIP_ID}",
      "relationship_type": "BENEFICIARY",
      "customer_id": "{BENEFICIARY_PERSON_ID}",
      "ownership_percentage": 50,
      "created_at": "2026-08-26T18:09:12.881517Z"
    }
    ```

    Repeat both steps for each additional beneficiary. For example, a second beneficiary with `"ownership_percentage": 50` splits the account evenly between the two.
  </Step>
</Steps>

## Managing beneficiaries

### List beneficiaries on an account

Use [GET /v2/accounts/\{ACCOUNT\_ID}/relationships](/v2/reference/listaccountrelationship) to retrieve all relationships for an account, then filter for a `relationship_type` of `BENEFICIARY`:

```shell theme={"system"}
curl \
  -X GET \
  -H "Authorization: Bearer $apikey" \
  https://api.synctera.com/v2/accounts/{ACCOUNT_ID}/relationships
```

### Edit a beneficiary's details

Beneficiary identification lives on the person resource. Patch it with [PATCH /v2/persons/\{PERSON\_ID}](/v2/reference/updateperson):

```shell theme={"system"}
curl \
  -X PATCH \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  https://api.synctera.com/v2/persons/{BENEFICIARY_PERSON_ID} \
  --data-binary '
  {
    "phone_number": "+13105550000"
  }'
```

### Change a beneficiary's percentage

Update the `ownership_percentage` on the account relationship with [PUT /v2/accounts/\{ACCOUNT\_ID}/relationships/\{RELATIONSHIP\_ID}](/v2/reference/updateaccountrelationship):

```shell theme={"system"}
curl \
  -X PUT \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  https://api.synctera.com/v2/accounts/{ACCOUNT_ID}/relationships/{RELATIONSHIP_ID} \
  --data-binary '
  {
    "relationship_type": "BENEFICIARY",
    "customer_id": "{BENEFICIARY_PERSON_ID}",
    "ownership_percentage": 75
  }'
```

### Remove a beneficiary

Delete the account relationship with [DELETE /v2/accounts/\{ACCOUNT\_ID}/relationships/\{RELATIONSHIP\_ID}](/v2/reference/deleteaccountrelationship). This removes the POD designation; the person resource is unaffected.

```shell theme={"system"}
curl \
  -X DELETE \
  -H "Authorization: Bearer $apikey" \
  https://api.synctera.com/v2/accounts/{ACCOUNT_ID}/relationships/{RELATIONSHIP_ID}
```

## Best practices

<Warning>
  Beneficiary designations are subject to bank approval. Confirm your program supports POD designations before exposing the flow to customers.
</Warning>

* **Collect full identification** — capture name, date of birth, SSN, and contact information so the beneficiary can be identified when funds are disbursed.
* **Keep allocations consistent** — track each beneficiary's `ownership_percentage` so totals reflect your program's rules for splitting funds.
* **Reuse people where possible** — if a beneficiary already exists as a person, link the existing `id` instead of creating a duplicate.
* **Treat PII carefully** — expect vaulted fields like `ssn` to be returned masked, and never log full values.

## Related guides

<CardGroup cols={2}>
  <Card title="Create a Personal Customer" href="/v2/docs/create-a-personal-customer" icon="user" horizontal>
    Create the person resource used to represent a beneficiary.
  </Card>

  <Card title="Create Accounts" href="/v2/docs/create-accounts-guide" icon="building-columns" horizontal>
    Open the account that beneficiaries are designated on.
  </Card>
</CardGroup>

## API reference

* [Create an account relationship](/v2/reference/createaccountrelationship)
* [List account relationships](/v2/reference/listaccountrelationship)
* [Update an account relationship](/v2/reference/updateaccountrelationship)
* [Delete an account relationship](/v2/reference/deleteaccountrelationship)
* [Create a person](/v2/reference/createperson)
* [Update a person](/v2/reference/updateperson)