Add POD Beneficiaries to an Account

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 PROSPECTs 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 and account Relationships 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:

It also assumes you have already created a personal or business customer and opened an account 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).

{
  "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 for the full request and response schemas.

Adding a beneficiary

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.

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:

{
  "id": "{BENEFICIARY_PERSON_ID}",
  "status": "PROSPECT",
  "verification_status": "UNVERIFIED",
  "is_customer": false,
  "first_name": "Jordan",
  "last_name": "Rivera"
}

Beneficiaries are prospects, not customers. They do not need to pass KYC, so there is no verification step.

Link the beneficiary to the account

Create an account relationship of type BENEFICIARY with POST /v2/accounts/{ACCOUNT_ID}/relationships. Provide the beneficiary’s person ID in customer_id, and use ownership_percentage to record the share of funds they are entitled to.

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:

{
  "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.

Managing beneficiaries

List beneficiaries on an account

Use GET /v2/accounts/{ACCOUNT_ID}/relationships to retrieve all relationships for an account, then filter for a relationship_type of BENEFICIARY:

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}:

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}:

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}. This removes the POD designation; the person resource is unaffected.

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

Best practices

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

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.

Overview

Products

Onboard a Personal Customer

Onboard a Business Customer

Create Accounts

Link External Accounts

Link External Cards

Issue Cards

Move Money

Get Transactions

Dispute Transactions

Platform Tools

Use Cases

Add POD Beneficiaries to an Account

Overview

Prerequisites

The account relationship object

Adding a beneficiary

Managing beneficiaries

List beneficiaries on an account

Edit a beneficiary’s details

Change a beneficiary’s percentage

Remove a beneficiary

Best practices

Create a Personal Customer

Create Accounts

API reference

​Overview

​Prerequisites

​The account relationship object

​Adding a beneficiary

​Managing beneficiaries

​List beneficiaries on an account

​Edit a beneficiary’s details

​Change a beneficiary’s percentage

​Remove a beneficiary

​Best practices

​Related guides

Create a Personal Customer

Create Accounts

​API reference

Overview

Prerequisites

The account relationship object

Adding a beneficiary

Managing beneficiaries

List beneficiaries on an account

Edit a beneficiary’s details

Change a beneficiary’s percentage

Remove a beneficiary

Best practices

Related guides

API reference