Altruist Draft Beneficiaries API
Beneficiary management for account drafts within bundles
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/altruist:altruist-draft-beneficiaries-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Enterprise Realtime Draft Beneficiaries API
description: The Enterprise Realtime API service acts as the public API layer for advisor infrastructure, enabling partner-developers to programmatically perform advisor actions.
version: v1
servers:
- url: https://integrations.altruist.com
description: API Server
tags:
- name: Draft Beneficiaries
description: Beneficiary management for account drafts within bundles
paths:
/api/v1/orgs/{orgId}/households/{householdId}/accounts/draftBundles/{accountDraftBundleId}/drafts/{draftId}/beneficiaries:
get:
tags:
- Draft Beneficiaries
summary: List beneficiaries for an account draft
description: Returns a paginated list of beneficiaries configured on the specified account draft within a bundle.
operationId: listBeneficiaries
parameters:
- name: orgId
in: path
required: true
schema:
type: string
format: uuid
- name: householdId
in: path
required: true
schema:
type: string
format: uuid
- name: accountDraftBundleId
in: path
required: true
schema:
type: string
format: uuid
- name: draftId
in: path
required: true
schema:
type: string
format: uuid
- name: page
in: query
required: false
schema:
type: integer
format: int32
default: 1
- name: size
in: query
required: false
schema:
type: integer
format: int32
default: 50
maximum: 200
responses:
'200':
description: Paginated list of beneficiaries (may be empty)
content:
'*/*':
schema:
$ref: '#/components/schemas/PageResponseBeneficiaryV1'
'400':
description: Invalid input or account type does not support beneficiaries
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'401':
description: Unauthorized — missing or invalid token
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'403':
description: Access denied — caller lacks READ on the household
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'404':
description: Draft, bundle, or household not found
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'409':
description: Conflict
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'422':
description: Unprocessable Entity
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'500':
description: Internal Server Error
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'501':
description: Not Implemented
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'502':
description: Bad Gateway
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
post:
tags:
- Draft Beneficiaries
summary: Create a beneficiary for an account draft
description: Creates a new beneficiary on the specified account draft within a bundle.
operationId: createBeneficiary
parameters:
- name: orgId
in: path
required: true
schema:
type: string
format: uuid
- name: householdId
in: path
required: true
schema:
type: string
format: uuid
- name: accountDraftBundleId
in: path
required: true
schema:
type: string
format: uuid
- name: draftId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBeneficiaryRequestV1'
required: true
responses:
'201':
description: Beneficiary created
content:
'*/*':
schema:
$ref: '#/components/schemas/BeneficiaryV1'
'400':
description: Invalid input, account type does not support beneficiaries, or invalid relationship/designationType combination (e.g. Entity with PerStirpes, Contingent with PerStirpes)
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'401':
description: Unauthorized — missing or invalid token
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'403':
description: Access denied — caller lacks READ on the household
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'404':
description: Draft, bundle, or household not found
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'409':
description: Conflict
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'422':
description: Unprocessable Entity
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'500':
description: Internal Server Error
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'501':
description: Not Implemented
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'502':
description: Bad Gateway
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
delete:
tags:
- Draft Beneficiaries
summary: Batch delete beneficiaries from an account draft
description: Removes multiple beneficiaries from the specified account draft within a bundle in a single request.
operationId: batchDeleteBeneficiaries
parameters:
- name: orgId
in: path
required: true
schema:
type: string
format: uuid
- name: householdId
in: path
required: true
schema:
type: string
format: uuid
- name: accountDraftBundleId
in: path
required: true
schema:
type: string
format: uuid
- name: draftId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BatchDeleteBeneficiariesRequestV1'
required: true
responses:
'204':
description: Beneficiaries deleted
'400':
description: Invalid input, empty beneficiary ID list, or account type does not support beneficiaries
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'401':
description: Unauthorized - missing or invalid token
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'403':
description: Access denied - caller lacks READ on the household
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'404':
description: Draft, bundle, or household not found
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'409':
description: Conflict
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'422':
description: Unprocessable Entity
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'500':
description: Internal Server Error
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'501':
description: Not Implemented
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'502':
description: Bad Gateway
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
? /api/v1/orgs/{orgId}/households/{householdId}/accounts/draftBundles/{accountDraftBundleId}/drafts/{draftId}/beneficiaries/allocations
: post:
tags:
- Draft Beneficiaries
summary: Set beneficiary allocations for an account draft
description: 'Atomically sets allocation percentages for beneficiaries on the specified account draft. This endpoint only updates allocation percentages — no other beneficiary fields (name, address, relationship, etc.) can be changed through it. Use PUT .../beneficiaries/{beneficiaryId} to update other fields.
Validation rules:
- Every beneficiary in a designation group (Primary or Contingent) must be included when any beneficiary of that group is present.
- Percentages must sum to exactly 100 per designation group.
- Each percentage must be strictly greater than 0 and at most 100, with at most 2 decimal places.
- No duplicate beneficiaryIds are allowed.'
operationId: setAllocations
parameters:
- name: orgId
in: path
required: true
schema:
type: string
format: uuid
- name: householdId
in: path
required: true
schema:
type: string
format: uuid
- name: accountDraftBundleId
in: path
required: true
schema:
type: string
format: uuid
- name: draftId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SetBeneficiaryAllocationsRequestV1'
required: true
responses:
'204':
description: Allocations applied
'400':
description: 'Invalid input: allocations do not sum to 100 per designation group, duplicate beneficiaryIds, missing beneficiaries within a designation group, percentage out of range or exceeds 2 decimal places, or account type does not support beneficiaries'
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'401':
description: Unauthorized - missing or invalid token
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'403':
description: Access denied - caller lacks READ on the household
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'404':
description: Draft, bundle, or household not found
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'409':
description: Conflict
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'422':
description: Unprocessable Entity
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'500':
description: Internal Server Error
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'501':
description: Not Implemented
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'502':
description: Bad Gateway
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
? /api/v1/orgs/{orgId}/households/{householdId}/accounts/draftBundles/{accountDraftBundleId}/drafts/{draftId}/beneficiaries/{beneficiaryId}
: get:
tags:
- Draft Beneficiaries
summary: Get a single beneficiary for an account draft
description: Returns the details of a single beneficiary on the specified account draft within a bundle.
operationId: getBeneficiary
parameters:
- name: orgId
in: path
required: true
schema:
type: string
format: uuid
- name: householdId
in: path
required: true
schema:
type: string
format: uuid
- name: accountDraftBundleId
in: path
required: true
schema:
type: string
format: uuid
- name: draftId
in: path
required: true
schema:
type: string
format: uuid
- name: beneficiaryId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: The beneficiary
content:
'*/*':
schema:
$ref: '#/components/schemas/BeneficiaryV1'
'400':
description: Invalid input or account type does not support beneficiaries
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'401':
description: Unauthorized — missing or invalid token
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'403':
description: Access denied — caller lacks READ on the household
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'404':
description: Draft, bundle, household, or beneficiary not found
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'409':
description: Conflict
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'422':
description: Unprocessable Entity
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'500':
description: Internal Server Error
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'501':
description: Not Implemented
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'502':
description: Bad Gateway
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
put:
tags:
- Draft Beneficiaries
summary: Update a beneficiary for an account draft
description: Full replacement update of an existing beneficiary on the specified account draft within a bundle. All required fields must be provided.
operationId: updateBeneficiary
parameters:
- name: orgId
in: path
required: true
schema:
type: string
format: uuid
- name: householdId
in: path
required: true
schema:
type: string
format: uuid
- name: accountDraftBundleId
in: path
required: true
schema:
type: string
format: uuid
- name: draftId
in: path
required: true
schema:
type: string
format: uuid
- name: beneficiaryId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateBeneficiaryRequestV1'
required: true
responses:
'200':
description: Beneficiary updated
content:
'*/*':
schema:
$ref: '#/components/schemas/BeneficiaryV1'
'400':
description: Invalid input, missing required fields, account type does not support beneficiaries, or invalid relationship/designationType combination (e.g. Entity with PerStirpes, Contingent with PerStirpes)
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'401':
description: Unauthorized — missing or invalid token
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'403':
description: Access denied — caller lacks READ on the household
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'404':
description: Draft, bundle, household, or beneficiary not found
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'409':
description: Conflict
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'422':
description: Unprocessable Entity
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'500':
description: Internal Server Error
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'501':
description: Not Implemented
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'502':
description: Bad Gateway
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
delete:
tags:
- Draft Beneficiaries
summary: Delete a beneficiary from an account draft
description: Removes a single beneficiary from the specified account draft within a bundle.
operationId: deleteBeneficiary
parameters:
- name: orgId
in: path
required: true
schema:
type: string
format: uuid
- name: householdId
in: path
required: true
schema:
type: string
format: uuid
- name: accountDraftBundleId
in: path
required: true
schema:
type: string
format: uuid
- name: draftId
in: path
required: true
schema:
type: string
format: uuid
- name: beneficiaryId
in: path
required: true
schema:
type: string
format: uuid
responses:
'204':
description: Beneficiary deleted, or did not exist in the first place
'400':
description: Invalid input or account type does not support beneficiaries
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'401':
description: Unauthorized - missing or invalid token
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'403':
description: Access denied - caller lacks READ on the household
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'404':
description: Draft, bundle, or household, not found
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'409':
description: Conflict
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'422':
description: Unprocessable Entity
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'500':
description: Internal Server Error
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'501':
description: Not Implemented
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
'502':
description: Bad Gateway
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorV1'
components:
schemas:
ErrorV1:
type: object
properties:
code:
type: integer
format: int32
description: '### Error Codes
| Code | Description |
|--------|-------------------------------------|
| **0xx** | **Unknown or Unexpected** |
| 0 | Unknown error |
| 40 | Unknown authentication error |
| **1xx** | **General** |
| 101 | Invalid input |
| 104 | Not found |
| 140 | Access Denied |
| 141 | Unauthorized |
| 150 | Not implemented |
| **10xx** | **Household** |
| 1000 | Household not found |
| 1001 | Duplicate contact |
| 1002 | Household contact not found |
| 1003 | Household contact already exists |
| **11xx** | **Account** |
| 1100 | Account not found |
| 1110 | Invalid account group |
| **12xx** | **User** |
| 1200 | User not found |
| 1201 | User profile not found |
| **13xx** | **Transfer** |
| 1300 | Transfer not found |
| 1301 | Transfer not supported |
| 1302 | Duplicate transfer |
| 1303 | Funding account not found |
| 1304 | Duplicate funding account |
| **14xx** | **Client Agreement** |
| 1400 | Client Agreement not found |
| 1401 | Invalid Client Agreement file |
| 1402 | Client Agreement could not be updated |
| **15xx** | **Trusted Contact** |
| 1500 | Trusted Contact not found |
| **17xx** | **Cash Set Aside** |
| 1700 | Cash set aside not found |
| 1701 | Cash set aside invalid amount |
| 1702 | Cash set aside invalid date |
| 1703 | Cash set aside upstream error |
| 1704 | Cash set aside cannot be cancelled |
| 1705 | Cash set aside invalid account |
| **18xx** | **Cash Settings** |
| 1800 | Cash settings not found |
'
message:
type: string
requestId:
type: string
BeneficiaryAllocationV1:
type: object
description: A single beneficiary allocation entry pairing a beneficiary with a percentage.
properties:
beneficiaryId:
type: string
format: uuid
description: ID of an existing beneficiary on the account draft.
percentage:
type: number
description: Allocation percentage for this beneficiary. Must be strictly greater than 0 and at most 100, with at most 2 decimal places. Percentages for all beneficiaries within a designation group (Primary or Contingent) must sum to exactly 100.
example: 50
maximum: 100
minimum: 0
required:
- beneficiaryId
- percentage
PageResponseBeneficiaryV1:
type: object
properties:
page:
type: integer
format: int32
size:
type: integer
format: int32
total:
type: integer
format: int64
items:
type: array
items:
$ref: '#/components/schemas/BeneficiaryV1'
BeneficiaryV1:
type: object
properties:
id:
type: string
format: uuid
relationship:
type: string
enum:
- Spouse
- NonSpouse
- Entity
designation:
type: string
enum:
- Primary
- Contingent
designationType:
type: string
enum:
- PerCapita
- PerStirpes
beneficiaryClass:
$ref: '#/components/schemas/BeneficiaryClassV1'
description: Beneficiary classification derived from the account type. IraBeneficiary for IRA-type account drafts, TodBeneficiary for TOD-type account drafts. Read-only; determined by the server based on account type.
readOnly: true
firstName:
type: string
middleName:
type: string
lastName:
type: string
dateOfBirth:
type: string
format: date
entityName:
type: string
dateOfFormation:
type: string
format: date
taxId:
type: string
allocationPercentage:
type: number
phoneNumber:
type: string
email:
type: string
address:
$ref: '#/components/schemas/BeneficiaryAddressV1'
created:
type: string
format: date-time
updated:
type: string
format: date-time
UpdateBeneficiaryRequestV1:
type: object
properties:
relationship:
type: string
enum:
- Spouse
- NonSpouse
- Entity
designation:
type: string
enum:
- Primary
- Contingent
designationType:
type: string
description: Designation type for the beneficiary. PerStirpes is only valid for Primary designation with Spouse or NonSpouse relationship. Entity beneficiaries and Contingent beneficiaries must use PerCapita.
enum:
- PerCapita
- PerStirpes
firstName:
type: string
maxLength: 100
minLength: 0
middleName:
type: string
maxLength: 100
minLength: 0
lastName:
type: string
maxLength: 100
minLength: 0
dateOfBirth:
type: string
pattern: \d{4}-\d{2}-\d{2}
entityName:
type: string
maxLength: 200
minLength: 0
dateOfFormation:
type: string
pattern: \d{4}-\d{2}-\d{2}
taxId:
type: string
phoneNumber:
type: string
pattern: \d{3}-\d{3}-\d{4}
email:
type: string
pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}$
address:
$ref: '#/components/schemas/BeneficiaryAddressV1'
required:
- designation
- designationType
- relationship
CreateBeneficiaryRequestV1:
type: object
properties:
relationship:
type: string
enum:
- Spouse
- NonSpouse
- Entity
designation:
type: string
enum:
- Primary
- Contingent
designationType:
type: string
description: Designation type for the beneficiary. PerStirpes is only valid for Primary designation with Spouse or NonSpouse relationship. Entity beneficiaries and Contingent beneficiaries must use PerCapita.
enum:
- PerCapita
- PerStirpes
firstName:
type: string
maxLength: 100
minLength: 0
middleName:
type: string
maxLength: 100
minLength: 0
lastName:
type: string
maxLength: 100
minLength: 0
dateOfBirth:
type: string
pattern: \d{4}-\d{2}-\d{2}
entityName:
type: string
maxLength: 200
minLength: 0
dateOfFormation:
type: string
pattern: \d{4}-\d{2}-\d{2}
taxId:
type: string
phoneNumber:
type: string
pattern: \d{3}-\d{3}-\d{4}
email:
type: string
pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}$
address:
$ref: '#/components/schemas/BeneficiaryAddressV1'
required:
- designation
- designationType
- relationship
BatchDeleteBeneficiariesRequestV1:
type: object
properties:
beneficiaryIds:
type: array
items:
type: string
format: uuid
minItems: 1
required:
- beneficiaryIds
BeneficiaryAddressV1:
type: object
properties:
addr1:
type: string
addr2:
type: string
city:
type: string
state:
type: string
zipCode:
type: string
BeneficiaryClassV1:
type: string
description: Beneficiary classification derived from the account type. IraBeneficiary for IRA-type accounts, TodBeneficiary for TOD-type accounts.
enum:
- IraBeneficiary
- TodBeneficiary
SetBeneficiaryAllocationsRequestV1:
type: object
description: Request to set allocation percentages for existing beneficiaries on an account draft. This endpoint only updates allocation percentages — no other beneficiary fields can be changed through it. All beneficiaries within a designation group (Primary or Contingent) must be included when any beneficiary of that group is present, and percentages must sum to exactly 100 per group.
properties:
allocations:
type: array
description: List of beneficiary allocation entries. Must not be empty. Each entry pairs an existing beneficiaryId with a percentage. No duplicate beneficiaryIds are allowed. All beneficiaries sharing the same designation (Primary or Contingent) must be included if any one of them is, and their percentages must sum to 100.
items:
$ref: '#/components/schemas/BeneficiaryAllocationV1'
minItems: 1
required:
- allocations
x-provenance:
method: searched
source: https://developer.altruist.com/reference
harvested: '2026-10-13'
tool: harvest-readme-openapi.py
note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
assembled_from:
- https://developer.altruist.com/reference/assignaccountportfolio-1.md
- https://developer.altruist.com/reference/assignaccounttohousehold.md
- https://developer.altruist.com/reference/associatedrafttobundle.md
- https://developer.altruist.com/reference/batchdeletebeneficiaries.md
- https://developer.altruist.com/reference/cancelacattransfer.md
- https://developer.altruist.com/reference/cancelcashsetaside.md
- https://developer.altruist.com/reference/cancelcashtransfer-1.md
- https://developer.altruist.com/reference/cancelscheduledtransfer-1.md
- https://developer.altruist.com/reference/checkdrafteligibility.md
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/altruist/refs/heads/main/openapi/altruist-draft-beneficiaries-api-openapi.yml