--- title: "Update Beneficiary" source_url: https://docs.rapyd.net/en/update-beneficiary.html lang: en --- # Update Beneficiary Update a beneficiary with additional fields. > **Note:** > > - You cannot update the values of the beneficiary fields which were defined when it was created. > - The code samples include successful requests (200) and bad requests (400). > > - For error messages that appear due to bad requests (400), see: > > - [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors") > - [Payout Errors](https://docs.rapyd.net/en/payout-errors.md "Payout Errors") > - For information about unauthorized request (401) and other authentication errors, see [Troubleshooting Authentication and Authorization Errors](https://docs.rapyd.net/en/troubleshooting-authentication-and-authorization-errors.md "Troubleshooting Authentication and Authorization Errors"). ### Parameters ### Request Header Parameters - - access_key - Unique access key provided by Rapyd for each authorized user. See [Developers](https://docs.rapyd.net/en/developers.md "Developers"). - - Content-Type - Indicates that the data appears in JSON format. Set to **application/json**. - - idempotency - A unique key that prevents the platform from creating the same object twice. See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency"). - - salt - Random string. Recommended length: 8-16 characters. - - signature - Signature calculated for each request individually. See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures"). - - timestamp - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds). ### Request Path Parameters - beneficiary - ID of the `beneficiary` object. String starting with **beneficiary_**. ### Request Body Parameters > **Note:** > > In addition to the fields documented below, you can include all other fields listed for the beneficiary in the response to [Get Payout Required Fields](https://docs.rapyd.net/en/get-payout-required-fields.md "Get Payout Required Fields"), and you must conform to the regex provided. - - address - Beneficiary's street address including the building number. For example: 123 East 32nd street. - - city - City of the beneficiary. - - company_name - Name of the beneficiary company. Relevant when `entity_type` is **company**. - - country - Country of the beneficiary. Two-letter ISO 3166-1 ALPHA-2 code. The two-letter prefix of the payout method type must match the beneficiary country code. - - country_of_incorporation - The country where the company was registered. Two-letter ISO 3166-1 ALPHA-2 code. Relevant when `entity_type` is **company**. - - date_of_birth - Date of birth of the individual. Format: **DD/MM/YYYY**. Relevant when `entity_type` is **individual**. - - date_of_incorporation - The date when the company was registered. Format: **DD/MM/YYYY**. Relevant when `entity_type` is **company**. - - default_payout_method_type - The type of payout method for the beneficiary. The two-letter prefix must match the beneficiary country code. The prefix xx_ matches all countries. - - first_name - First name of the beneficiary. Relevant when `entity_type` is **individual**. - - gender - Gender of the individual. Relevant when `entity_type` is **individual**. One of the following values: - **male** - **female** - **other** - **not_applicable** - - identification_type - Type of identification document for the beneficiary. When `entity_type` is **company**, this field must be **company_registered_number**. When `entity_type` is **individual**, one of the following values: - **company_registered_number** - **drivers_license** - **identification_id** - **international_passport** - **residence_permit** - **social_security** - **work_permit** - - identification_value - Identification number on the document mentioned in `identification_type`. - - last_name - Last name of the beneficiary. Relevant when `entity_type` is **individual**. - - merchant_reference_id - Identifier defined by the client for reference purposes. Limit: 45 characters. - - nationality - The citizenship of the beneficiary. Two-letter ISO 3166-1 ALPHA-2 code for the country. Relevant when `entity_type` is **individual**. To determine the code for a country, see [List Countries](https://docs.rapyd.net/en/list-countries.md "List Countries"). ### Response Parameters - - address - Beneficiary's street address including the building number. For example: 123 East 32nd street. - - amount - Maximum payout amount to validate, in units of the currency defined in `sender_currency`. - - beneficiary - ID of the `beneficiary` object. String starting with **beneficiary_**. - - category - The category of payout method type. One of the following: - **bank** - **card** - **cash** - **ewallet** - local eWallet (non-Rapyd) - **rapyd_ewallet** - Rapyd wallet. Must match the category of the payout method. - - city - City of the beneficiary. - - company_name - Name of the beneficiary company. Relevant when `entity_type` is **company**. - - confirmation_required - Indicates whether the beneficiary must respond to accept or decline a payout. Relevant to the **rapyd_ewallet** payout method type. false - - country - Country of the beneficiary. Two-letter ISO 3166-1 ALPHA-2 code. The two-letter prefix of the payout method type must match the beneficiary country code. - - currency - Currency received by the beneficiary. Three-letter ISO 4217 code. - - date_of_birth - Date of birth of the individual. Format: **DD/MM/YYYY**. Relevant when `entity_type` is **individual**. - - date_of_incorporation - The date when the company was registered. Format: **DD/MM/YYYY**. Relevant when `entity_type` is **company**. - - default_payout_method_type - The type of payout method for the beneficiary. - - entity_type - Type of entity. One of the following values: - **company** - **individual** - - ewallet - ID of the wallet that the money is transferred to. String starting with **ewallet_**. Relevant to payout to Rapyd Wallet. - - first_name - First name of the beneficiary. Relevant when `entity_type` is **individual**. - - gender - Gender of the individual. Relevant when `entity_type` is **individual**. One of the following values: - **male** - **female** - **other** - **not_applicable** - - id - ID of the `beneficiary` object. String starting with **beneficiary_**. - - identification_type - Type of identification document for the beneficiary. When `entity_type` is **company**, this field must be **company_registered_number**. When `entity_type` is **individual**, one of the following values: - **drivers_license** - **identification_id** - **international_passport** - **residence_permit** - **social_security** - **work_permit** - - identification_value - Identification number on the document mentioned in `identification_type`. - - last_name - Last name of the beneficiary. Relevant when `entity_type` is **individual**. - - merchant_reference_id - Identifier defined by the client for reference purposes. Limit: 45 characters. - - nationality - The citizenship of the beneficiary. Relevant when `entity_type` is **individual**. - /v1/payouts/beneficiary/:beneficiary - Update Beneficiary - Individual - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary/beneficiary_0e1c96eac00e22a6875b9ba5107a310a' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "state": "Illinois", "postcode": "12345" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "af4bd368-a5fa-4d79-a51d-9fcc344d8d74" }, "data": { "id": "beneficiary_cb009f46c8dcd85004c8054541287723", "last_name": "Doe", "first_name": "John", "country": "US", "entity_type": "individual", "address": "1 Main Street", "name": "John Doe", "postcode": "12345", "city": "Anyyown", "state": "Illinois", "account_number": "1234567", "currency": "USD", "identification_type": "identification_id", "identification_value": "*********", "merchant_reference_id": "JohnDoe", "gender": "other", "bic_swift": "12345678XXX", "payment_type": "priority", "category": "bank", "default_payout_method_type": "us_general_bank" } } ``` - Bad Request - Update Beneficiary with No New Fields - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary/beneficiary_0e1c96eac00e22a6875b9ba5107a310a' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "state": "Illinois", "postcode": "12345" }' ``` - ```json { "status": { "error_code": "ERROR_UPDATE_BENEFICIARY_WITH_NO_NEW_FIELDS", "status": "ERROR", "message": "The request attempted to update a beneficiary field, but its value has already been defined. The request was rejected. Corrective action: Update only values of beneficiary fields that were not previously defined.", "response_code": "ERROR_UPDATE_BENEFICIARY_WITH_NO_NEW_FIELDS", "operation_id": "51ce8647-5495-4f44-bc90-d6b22416693b" } } ``` - Bad Request - Beneficiary Not Found - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary/beneficiary0e1c96eac00e22a6875b9ba5107a310a' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "state": "Illinois", "postcode": "12345" }' ``` - ```json { "status": { "error_code": "ERROR_GET_BENEFICIARY", "status": "ERROR", "message": "The request attempted an operation that requires a payout beneficiary, but the beneficiary was not found. The request was rejected. Corrective action: Use the ID of a valid beneficiary.", "response_code": "ERROR_GET_BENEFICIARY", "operation_id": "b08b8ef7-56ef-43c6-b437-f53395b2ab83" } } ```