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

# Update a beneficiary (V2)

> Update an existing beneficiary by beneficiary's identifier.



## OpenAPI

````yaml https://api.ebury.io/openapi.json patch /v2/beneficiaries/{beneficiary_id}
openapi: 3.0.0
info:
  description: |
    Ebury API allows customers:
      to retrieve accounts, balances, beneficiaries, and transactions;
      to get buy/sell estimates and quotes, book trades and retrieve trade history;
      to allocate payments to a trade and beneficiary, and to submit payments in bulk;
      to download documents such as trade receipt, payment instruction and payment receipt;
      to manage the authorised persons on their account.
    The Metadata API allows applications to clarify some parts of the Ebury API
      that are impractical to express schematically.
  termsOfService: https://docs.ebury.io/#terms-of-use
  title: Ebury API
  version: '0.1'
servers:
  - url: https://{environment}.ebury.io
    variables:
      environment:
        default: api
        enum:
          - api
          - sandbox
security: []
paths:
  /v2/beneficiaries/{beneficiary_id}:
    parameters:
      - $ref: '#/components/parameters/BeneficiaryId'
      - $ref: '#/components/parameters/ClientId'
      - $ref: '#/components/parameters/Authorization'
    patch:
      tags:
        - Beneficiaries V2
      summary: Update a beneficiary (V2)
      description: Update an existing beneficiary by beneficiary's identifier.
      operationId: beneficiary_v2_patch
      parameters:
        - $ref: '#/components/parameters/XBeneficiaryPolicyVersion'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BeneficiaryV2UpdateRequest'
        description: The fields of the beneficiary to update.
        required: true
      responses:
        '200':
          $ref: '#/components/responses/BeneficiaryV2'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/BeneficiaryOrClientNotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/IntegrationError'
        '502':
          $ref: '#/components/responses/IntegrationError'
components:
  parameters:
    BeneficiaryId:
      description: The identifier of a beneficiary.
      in: path
      name: beneficiary_id
      required: true
      schema:
        type: string
    ClientId:
      description: The identifier of a client.
      in: query
      name: client_id
      required: true
      schema:
        type: string
    Authorization:
      description: The access token.
      in: header
      name: Authorization
      required: true
      schema:
        type: string
    XBeneficiaryPolicyVersion:
      description: >-
        The version of the beneficiary validation policy to apply. The latest
        one is used when omitted.
      in: header
      name: X-Beneficiary-Policy-Version
      required: false
      schema:
        type: string
  schemas:
    BeneficiaryV2UpdateRequest:
      description: >-
        Partial update: every field is optional, and only the fields actually
        sent are forwarded. Omitting a field leaves it untouched; passing it as
        `null` clears it. identification_type and identification_value must be
        sent together.
      properties:
        name:
          description: >-
            The alias/display name of the beneficiary. The beneficiary's name is
            `bank_account.holder_name`.
          minLength: 1
          type: string
          nullable: true
        type:
          description: The type of the beneficiary.
          enum:
            - personal
            - business
            - null
          type: string
          nullable: true
        external_reference:
          description: >-
            The unique external reference submitted by the client for the
            beneficiary.
          minLength: 1
          type: string
          nullable: true
        phone_number:
          description: The phone number of the beneficiary.
          minLength: 1
          type: string
          nullable: true
        payouts_email:
          description: The email of the beneficiary to use during payouts.
          format: email
          type: string
          nullable: true
        identification_type:
          description: The identification (e.g. TAX ID) type of the beneficiary.
          minLength: 1
          type: string
          nullable: true
        identification_value:
          description: The identification (e.g. TAX ID) value of the beneficiary.
          minLength: 1
          type: string
          nullable: true
        notifications:
          allOf:
            - $ref: '#/components/schemas/BeneficiaryV2Notifications'
          nullable: true
          type: object
        address:
          allOf:
            - $ref: '#/components/schemas/BeneficiaryV2UpdateAddress'
          nullable: true
          type: object
        bank_account:
          allOf:
            - $ref: '#/components/schemas/BeneficiaryV2UpdateBankAccount'
          nullable: true
          type: object
        russian_details:
          allOf:
            - $ref: '#/components/schemas/BeneficiaryV2RussianDetails'
          nullable: true
          type: object
        payment_instructions:
          allOf:
            - $ref: '#/components/schemas/BeneficiaryV2PaymentInstructions'
          nullable: true
          type: object
      type: object
    BeneficiaryV2Notifications:
      description: The notification preferences of a beneficiary.
      properties:
        enabled:
          description: Whether the beneficiary should be notified of payments.
          type: boolean
        emails:
          description: The email addresses to notify of payments.
          items:
            type: string
          type: array
          nullable: true
      type: object
    BeneficiaryV2UpdateAddress:
      description: >-
        The address of a beneficiary or of its bank, for an update. None of the
        fields are required.
      properties:
        street_name:
          description: The street name.
          minLength: 1
          type: string
          nullable: true
        building_number:
          description: The building number.
          minLength: 1
          type: string
          nullable: true
        floor:
          description: The floor.
          minLength: 1
          type: string
          nullable: true
        apartment_office_number:
          description: The apartment/office number.
          minLength: 1
          type: string
          nullable: true
        city:
          description: The city.
          minLength: 1
          type: string
          nullable: true
        state:
          description: The state/region.
          minLength: 1
          type: string
          nullable: true
        post_code:
          description: The post code.
          minLength: 1
          type: string
          nullable: true
        country_code:
          description: The ISO 3166-1 alpha-2 country code.
          maxLength: 2
          minLength: 2
          type: string
          nullable: true
      type: object
    BeneficiaryV2UpdateBankAccount:
      description: >-
        The bank account of a beneficiary, for an update. None of the fields are
        required.
      properties:
        holder_name:
          description: The name of the bank account holder.
          minLength: 1
          type: string
          nullable: true
        number:
          description: The account number of the bank account.
          minLength: 1
          type: string
          nullable: true
        iban:
          description: The IBAN of the bank account.
          minLength: 1
          type: string
          nullable: true
        type:
          description: The type of the bank account (e.g. checking).
          minLength: 1
          type: string
          nullable: true
        currency_code:
          description: The ISO 4217 code of the bank account's currency.
          maxLength: 3
          minLength: 3
          type: string
          nullable: true
        bank:
          allOf:
            - $ref: '#/components/schemas/BeneficiaryV2UpdateBank'
          nullable: true
          type: object
        correspondent_bank:
          allOf:
            - $ref: '#/components/schemas/BeneficiaryV2CorrespondentBank'
          nullable: true
          type: object
      type: object
    BeneficiaryV2RussianDetails:
      description: The Russia-specific data of a bank account.
      properties:
        inn:
          description: >-
            The taxpayer identification number (INN) of legal entities
            registered in Russia.
          type: string
          nullable: true
        kpp:
          description: The KPP of the bank account.
          type: string
          nullable: true
        kbk:
          description: The KBK of the bank account.
          type: string
          nullable: true
        kio:
          description: The tax ID (KIO) of foreign legal entities in Russia.
          type: string
          nullable: true
        vo:
          description: The currency operation code (VO).
          type: string
          nullable: true
        central_bank_account:
          description: The 20-digit central bank account code of Russian banks.
          type: string
          nullable: true
      type: object
    BeneficiaryV2PaymentInstructions:
      description: The default payment data used when paying the beneficiary.
      properties:
        purpose_of_payment_code:
          description: The purpose of payment code, mandatory for some currencies.
          type: string
          nullable: true
        permanent_payment_reference:
          description: The default payment reference.
          type: string
          nullable: true
        purpose_of_payment_narrative:
          description: Free-text narrative describing the purpose of payment.
          type: string
          nullable: true
      type: object
    BeneficiaryV2:
      description: The data of a beneficiary.
      properties:
        id:
          description: The identifier of the beneficiary.
          type: string
        aml_status:
          description: The AML/screening status of the beneficiary.
          type: string
          nullable: true
        active:
          description: True if beneficiary is active, False otherwise.
          type: boolean
        editable:
          description: True if beneficiary is editable, False otherwise.
          type: boolean
        is_first_party:
          description: True if beneficiary is a first party, False otherwise.
          type: boolean
        created_date:
          description: The date and time when the beneficiary was created.
          type: string
        name:
          description: >-
            The alias/display name of the beneficiary. The beneficiary's name is
            `bank_account.holder_name`.
          type: string
          nullable: true
        type:
          description: The type of the beneficiary.
          enum:
            - personal
            - business
            - null
          type: string
          nullable: true
        external_reference:
          description: >-
            The unique external reference submitted by the client for the
            beneficiary.
          type: string
          nullable: true
        phone_number:
          description: The phone number of the beneficiary.
          type: string
          nullable: true
        payouts_email:
          description: The email of the beneficiary to use during payouts.
          type: string
          nullable: true
        identification_type:
          description: The identification (e.g. TAX ID) type of the beneficiary.
          type: string
          nullable: true
        identification_value:
          description: The identification (e.g. TAX ID) value of the beneficiary.
          type: string
          nullable: true
        notifications:
          $ref: '#/components/schemas/BeneficiaryV2Notifications'
        address:
          $ref: '#/components/schemas/BeneficiaryV2Address'
        bank_account:
          $ref: '#/components/schemas/BeneficiaryV2BankAccount'
      required:
        - id
        - active
        - editable
        - is_first_party
        - created_date
        - notifications
        - address
        - bank_account
      type: object
    ErrorMessage:
      description: An error message.
      properties:
        code:
          type: string
          description: The code for the error.
        details:
          description: Error details
          type: string
        message:
          type: string
          description: A short description of the cause of the error.
      required:
        - code
        - message
        - details
      type: object
    BeneficiaryV2UpdateBank:
      description: >-
        The bank of a beneficiary's bank account, for an update. None of the
        fields are required.
      properties:
        swift_code:
          description: The SWIFT code of the bank.
          minLength: 1
          type: string
          nullable: true
        name:
          description: The name of the bank.
          minLength: 1
          type: string
          nullable: true
        branch_code:
          description: The branch code of the bank.
          minLength: 1
          type: string
          nullable: true
        country_code:
          description: The ISO 3166-1 alpha-2 country code.
          maxLength: 2
          minLength: 2
          type: string
          nullable: true
        address_line:
          description: Single-line representation of the address.
          minLength: 1
          type: string
          nullable: true
        local_routing_identifier:
          description: >-
            The local identifier of the bank (e.g. Sort Code, ABA, routing
            number).
          minLength: 1
          type: string
          nullable: true
      type: object
    BeneficiaryV2CorrespondentBank:
      description: The correspondent bank of a beneficiary's bank account.
      nullable: true
      properties:
        swift_code:
          description: The SWIFT code of the correspondent bank.
          type: string
          nullable: true
        account_number:
          description: The account number at the correspondent bank.
          type: string
          nullable: true
      type: object
    BeneficiaryV2Address:
      description: An address of a beneficiary or of a bank.
      properties:
        street_name:
          description: The street name.
          type: string
          nullable: true
        building_number:
          description: The building number.
          type: string
          nullable: true
        floor:
          description: The floor.
          type: string
          nullable: true
        apartment_office_number:
          description: The apartment/office number.
          type: string
          nullable: true
        address_line_1:
          description: Single-line representation of the address.
          type: string
          nullable: true
        city:
          description: The city.
          type: string
          nullable: true
        state:
          description: The state/region.
          type: string
          nullable: true
        post_code:
          description: The post code.
          type: string
          nullable: true
        country:
          $ref: '#/components/schemas/BeneficiaryV2Country'
      required:
        - country
      type: object
    BeneficiaryV2BankAccount:
      description: The bank account of a beneficiary.
      properties:
        id:
          description: The identifier of the bank account.
          type: integer
        is_intra:
          description: True if the bank account is an intra-bank account, False otherwise.
          type: boolean
          nullable: true
        holder_name:
          description: The name of the bank account holder.
          type: string
        number:
          description: The account number of the bank account.
          type: string
          nullable: true
        iban:
          description: The IBAN of the bank account.
          type: string
          nullable: true
        type:
          description: The type of the bank account (e.g. checking).
          type: string
          nullable: true
        currency_code:
          description: The ISO 4217 code of the bank account's currency.
          maxLength: 3
          minLength: 3
          type: string
        bank:
          $ref: '#/components/schemas/BeneficiaryV2Bank'
        correspondent_bank:
          $ref: '#/components/schemas/BeneficiaryV2CorrespondentBank'
        russian_details:
          $ref: '#/components/schemas/BeneficiaryV2RussianDetails'
        payment_instructions:
          $ref: '#/components/schemas/BeneficiaryV2PaymentInstructions'
      required:
        - id
        - holder_name
        - currency_code
        - bank
        - russian_details
        - payment_instructions
      type: object
    BeneficiaryV2Country:
      description: The country of an address.
      properties:
        code_alpha2:
          description: The ISO 3166-1 alpha-2 country code.
          maxLength: 2
          minLength: 2
          type: string
        code_alpha3:
          description: The ISO 3166-1 alpha-3 country code.
          type: string
          nullable: true
        name:
          description: The full country name.
          type: string
          nullable: true
      required:
        - code_alpha2
      type: object
    BeneficiaryV2Bank:
      description: The bank of a beneficiary's bank account.
      properties:
        swift_code:
          description: The SWIFT code of the bank.
          type: string
          nullable: true
        name:
          description: The name of the bank.
          type: string
          nullable: true
        branch_code:
          description: The branch code of the bank.
          type: string
          nullable: true
        local_routing_identifier:
          description: >-
            The local identifier of the bank (e.g. Sort Code, ABA, routing
            number).
          type: string
          nullable: true
        address:
          $ref: '#/components/schemas/BeneficiaryV2Address'
      required:
        - address
      type: object
  responses:
    BeneficiaryV2:
      description: The data of a beneficiary.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BeneficiaryV2'
    ValidationError:
      description: >-
        Formatting, parameter or schema validation error. See error message for
        further details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    Unauthorized:
      description: Access denied due to authentication failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    Forbidden:
      description: >-
        Could not complete action due to data constraints. Refer to error
        message for additional details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    BeneficiaryOrClientNotFound:
      description: Beneficiary or client identifier not found.
    IntegrationError:
      description: Internal integration error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'

````