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

# Update account beneficiaries

> Permissions required: **Manage Accounts**

Update the primary and/or contingent beneficiaries for an account.



## OpenAPI

````yaml /knowledge-base/openapi/v4.yaml patch /accounts/{accountId}/beneficiaries
openapi: 3.1.0
info:
  title: Anchorage Digital Account APIs (v4)
  version: 4.0.0-beta
  description: >-
    Reference for the Anchorage Digital v4 API, the surface behind Crypto as a
    Service: account management (accounts and the account tree, beneficiaries,
    freeze/unfreeze/close), balances and transactions, trusted destinations,
    orders and allocations, withdrawals, deposit instructions, deposit
    attributions, the policy engine (policies, approval keys), and supported
    asset types. Approval groups, endorsements, compliance profiles, customers
    (onboarding), fee configuration updates, interest enrollment, funding
    allocations, and destination removal are under construction and return
    mocked data only.


    Status: BETA. The v4 API is available in the sandbox only
    (https://api.anchorage-staging.com/v4) and is not available in production
    yet. The contract may change until general availability. Which endpoints are
    live, in final testing, or under construction:
    https://docs.anchorage.com/platform/developers/caas/caas-overview


    Authentication: every request carries an `Api-Access-Key` header. Every
    POST, PATCH, and DELETE additionally requires an `Idempotency-Key`, and is
    signed with `Api-Signature` (hex-encoded Ed25519 over
    `timestamp_epoch_seconds + uppercase(http_method) + request_path +
    request_body`) plus `Api-Timestamp` (unix epoch seconds).


    Pagination: list endpoints accept `after` (cursor) and `limit` (page size, 1
    to 1000, default 100) and return a `page.endCursor` to continue from. Errors
    use a common envelope with a human-readable `message`; batch endpoints
    return a result per item instead.


    Guides: https://docs.anchorage.com/platform/developers/caas/caas-overview
servers:
  - url: https://api.anchorage-staging.com/v4
security:
  - Api-Access-Key: []
tags:
  - name: Accounts
  - name: Compliance Profiles
  - name: Balances
  - name: Transactions
  - name: Trusted Destinations
  - name: Orders & Allocations
  - name: Withdrawals
  - name: Deposit Instructions
  - name: Deposit Attributions
  - name: Policies
  - name: Approval Groups
  - name: Endorsements
  - name: Customers
  - name: Asset Types
paths:
  /accounts/{accountId}/beneficiaries:
    patch:
      tags:
        - Accounts
      summary: Update account beneficiaries
      description: |-
        Permissions required: **Manage Accounts**

        Update the primary and/or contingent beneficiaries for an account.
      operationId: updateAccountBeneficiaries
      parameters:
        - name: accountId
          in: path
          schema:
            type: string
            format: uuid
            example: 3486b413-93d3-4447-afce-2b9c9dc34a32
          required: true
          description: Unique identifier for the account
        - name: Idempotency-Key
          in: header
          schema:
            type: string
          required: true
          description: >-
            Client-supplied key that deduplicates retried requests. Reusing a
            key returns the original result instead of repeating the action.
        - name: Api-Signature
          in: header
          required: true
          schema:
            type: string
            pattern: ^[0-9A-Fa-f]{128,160}$
          description: >-
            A hex-encoded Ed25519 signature of `timestamp_epoch_seconds +
            uppercase(http_method) + request_path + request_body`.
        - name: Api-Timestamp
          in: header
          required: true
          schema:
            type: integer
            format: int64
          description: Current timestamp, represented as unix epoch seconds
      requestBody:
        description: Beneficiaries to set
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAccountBeneficiariesRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountBeneficiariesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
components:
  schemas:
    UpdateAccountBeneficiariesRequest:
      title: Update Account Beneficiaries Request
      additionalProperties: false
      type: object
      description: >-
        The primary and contingent beneficiaries for an account. Contingent
        beneficiaries inherit only if no primary beneficiary survives the
        account holder.
      properties:
        primary:
          $ref: '#/components/schemas/AccountBeneficiaryGroup'
        contingent:
          $ref: '#/components/schemas/AccountBeneficiaryGroup'
    AccountBeneficiariesResponse:
      title: Account Beneficiaries Response
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/AccountBeneficiaries'
    ErrorDetails:
      title: ErrorDetails
      type: object
      properties:
        message:
          description: A human-readable message providing more details about the error.
          example: Missing required field 'amount'.
          type: string
      required:
        - message
    AccountBeneficiaryGroup:
      title: Account Beneficiary Group
      type: array
      items:
        $ref: '#/components/schemas/AccountBeneficiary'
      description: A group of beneficiaries. Allocations within a group should sum to 100.
    AccountBeneficiaries:
      title: Account Beneficiaries
      type: object
      description: >-
        The primary and contingent beneficiaries for an account. Contingent
        beneficiaries inherit only if no primary beneficiary survives the
        account holder.
      properties:
        primary:
          $ref: '#/components/schemas/AccountBeneficiaryGroup'
        contingent:
          $ref: '#/components/schemas/AccountBeneficiaryGroup'
    AccountBeneficiary:
      title: Account Beneficiary
      type: object
      description: >-
        A named beneficiary entitled to a share of the account on the account
        holder's death.
      properties:
        beneficiaryType:
          $ref: '#/components/schemas/AccountBeneficiaryType'
        beneficiaryName:
          type: string
          description: Name of the beneficiary.
        allocation:
          type: number
          minimum: 0
          maximum: 100
          description: Percentage of the account allocated to this beneficiary.
      required:
        - beneficiaryType
        - beneficiaryName
        - allocation
    AccountBeneficiaryType:
      title: Account Beneficiary Type
      type: string
      enum:
        - SPOUSE
        - FAMILY_OR_FRIEND
        - CHARITY
        - TRUST
        - ESTATE
      description: Relationship of the beneficiary to the account holder.
  securitySchemes:
    Api-Access-Key:
      type: apiKey
      name: Api-Access-Key
      in: header
      description: An API key associated with a security role

````

## Related topics

- [Accounts](https://docs.anchorage.com/knowledge-base/platform/developers/caas/caas-accounts.md)
- [Update an account](https://docs.anchorage.com/knowledge-base/api-reference/v4/accounts/update-an-account.md)
- [Get account beneficiaries](https://docs.anchorage.com/knowledge-base/api-reference/v4/accounts/get-account-beneficiaries.md)
- [Update account fee configurations](https://docs.anchorage.com/knowledge-base/api-reference/v4/accounts/update-account-fee-configurations.md)
- [Getting started](https://docs.anchorage.com/knowledge-base/platform/developers/caas/caas-getting-started.md)
