Update Beneficiary (Atlas)

Overview

The PUT /banking/ibans/v2/recipients/{recipientId} endpoint updates an existing beneficiary record. Field updates are merged with the current record state.

[!IMPORTANT] currencyId, paymentMode, and beneficiaryType must always be supplied in the request body so downstream validation engines can correctly resolve the currency and clearing rail rules for the updated payload.

Runtime validation rules apply identically to the updated fields:

• Sanctioned (OORA) SWIFT bank codes remain strictly prohibited.
• For financial services and crypto clients, nestedType must be supplied.
• Name and address formatting rules (maximum lengths, allowed character sets) are enforced.

Resource Access

• HTTP Method: PUT
• Endpoint: /banking/ibans/v2/recipients/{recipientId}
• Authentication: Bearer token required

Request Headers

Header	Value	Required	Description
Authorization	Bearer {access_token}	Yes	JWT Bearer access token
Content-Type	application/json	Yes	Request payload format
Accept	application/json	Yes	Response payload format
x-api-key	string	No	Optional API key

Path Parameters

Parameter	Type	Required	Description
recipientId	string	Yes	Unique identifier of the beneficiary record to update.

Request Body

Mandatory Base Fields

Field	Type	Required	Description
currencyId	integer	Yes	Currency identifier (e.g. 1).
paymentMode	string	Yes	Mode: LOCAL, INTERNATIONAL, MOBILE_MONEY, STABLECOIN, HK_BANK.
beneficiaryType	string	Yes	Entity type: company, individual, myOrganisation.

Updatable Fields

Field	Type	Description
companyName	string	Updated corporate name (when beneficiaryType is company).
firstName	string	Updated first name (when beneficiaryType is individual).
lastName	string	Updated last name (when beneficiaryType is individual).
accountNumber	string	Updated account number or IBAN.
bankCode	string	Updated sort code, routing number, or BIC.
bankName	string	Updated receiving bank institution name.
bankAddress	object	Updated bank location object (countryCode, city, address).
beneficiaryAddress	object	Updated recipient address object (addressLine1, city, countryCode, postCode, mobileNumber, email).
customReferenceLabel	string	Client-defined tracking tag or custom label.
forFurtherCredit	object	Intermediary correspondent routing object (accountNumber, routingNumber, bankName, bankAddress, countryCode).
isAccountActive	boolean	Set to true or false to activate or suspend beneficiary payout routing.

Request Example

{
  "currencyId": 1,
  "paymentMode": "LOCAL",
  "beneficiaryType": "company",
  "companyName": "Acme Logistics International Ltd",
  "beneficiaryAddress": {
    "countryCode": "GB",
    "city": "London",
    "addressLine1": "250 Bishopsgate",
    "postCode": "EC2M 4AA",
    "email": "finance@acmelogistics.co.uk"
  },
  "customReferenceLabel": "Operations-Vendor-01"
}

Response

Success Response (200 OK)

{
  "success": true,
  "accounts": {
    "id": 948201,
    "companyId": "1045",
    "currencyId": 1,
    "paymentMode": "LOCAL",
    "beneficiaryType": "company",
    "companyName": "Acme Logistics International Ltd",
    "accountNumber": "20406080",
    "bankCode": "200000",
    "bankName": "Barclays Bank UK",
    "verificationState": "pending",
    "isAccountActive": true,
    "customReferenceLabel": "Operations-Vendor-01"
  }
}

Response Fields

Field	Type	Description
success	boolean	Indicates if the update succeeded.
accounts.id	number	Beneficiary record ID.
accounts.verificationState	string	New verification state (pending if re-screening is triggered, or approved).
accounts.companyName	string	Merged company name.

Error Responses

• 400 Bad Request: Missing mandatory base fields (currencyId, paymentMode, beneficiaryType) or invalid format.
• 401 Unauthorized: Missing or expired Bearer token.
• 404 Not Found: Beneficiary ID not found.
• 500 Internal Server Error: Internal platform error.

Code Examples

cURL

curl -X PUT "https://gateway.ahrvo.network/banking/ibans/v2/recipients/948201" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "currencyId": 1,
    "paymentMode": "LOCAL",
    "beneficiaryType": "company",
    "companyName": "Acme Logistics International Ltd"
  }'

Python

import requests

url = "https://gateway.ahrvo.network/banking/ibans/v2/recipients/948201"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

payload = {
    "currencyId": 1,
    "paymentMode": "LOCAL",
    "beneficiaryType": "company",
    "companyName": "Acme Logistics International Ltd"
}

response = requests.put(url, json=payload, headers=headers)
print(response.status_code, response.json())

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/banking/ibans/v2/recipients/948201';
const headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

const payload = {
  currencyId: 1,
  paymentMode: 'LOCAL',
  beneficiaryType: 'company',
  companyName: 'Acme Logistics International Ltd'
};

axios.put(url, payload, { headers })
  .then(res => console.log('Updated:', res.data))
  .catch(err => console.error(err.response ? err.response.data : err.message));

Interactive API Explorer