This endpoint allows you to modify the customer details of one or more active Virtual Accounts.

Requirements

• The Virtual Accounts being modified must have status set to active and
• The Virtual Accounts must already have customer details assigned. To assign customer details for the first time, use this endpoint.
• Each modification must include a reason code (reasonCode).
• You can make one modification per field per year(name, address, or ultimateBeneficialOwners) and up to two modifications total per year for each Virtual Account. Each change to a field counts as a modification.
• For example, if you modify both the name and address in one request, that counts as two modifications and no further customer details changes will be allowed for that Virtual Account in the same year. If you modify only name, you can make one more modification that year, but only to address or ultimateBeneficialOwners

📘

Validation rules:

Request payloads are validated according to the ISO 20022 address structure and country-specific postal standards, to determine what constitutes a valid address for the purpose of account ownership.

ISO 20022 defines which fields must be provided. In addition, the validation checks that the submitted values are valid and plausible, not just present.

Post box addresses are not accepted for account ownership, neither are fictional addresses or common testing values.

Modification Reason Codes

A modification request must include one of the following reason codes:

Required properties

virtualAccountNumber and reasonCode are always required.

Other properties marked as required in the body params section below are only required if you modify the object they are in.

For example, address.townName and address.country are required only when you update the address object. They are not required when you update name or ultimateBeneficialOwners. Additional address fields can also become required depending on the address.country value according to the ISO 20022 standard. For example, if you set country to DK, you must also provide postCode and streetName.

Clearing optional values

To clear an existing optional value, pass an empty string to the property you want to remove, for example:

{
    "items":
    [
        {
            "virtualAccountNumber": "0040087035",
            "reasonCode": "E03",
            "address": {
                "department": "", // Empty string
                "townName": "NewTown",
                "country": "SE"
            }
        }
    ]
}

Modifying multiple properties at once

If you want to modify multiple properties of the same Virtual Account, include separate objects for each modification in the items array:

{
    "items": [
        {
            "virtualAccountNumber": "0040087035",
            "reasonCode": "E01",
            "name": "NewName"
        },
        {
            "virtualAccountNumber": "0040087035",
            "reasonCode": "E03",
            "address": {
                "streetName": "NewStreet 2",
                "townName": "NewTown",
                "country": "SE"
            }
        }
    ]
}

Rate and volume limits

The following limits apply:

• Request limit of maximum 100 modifications per request
• Processing limit of up to 2000 modifications per 10min

Field constraints

Allowed characters

The allowed characters are:

a b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
0 1 2 3 4 5 6 7 8 9
/ - ? : ( ) . ' +
Space

Character limits

The customer detail properties for name and beneficialOwners accept up to 35 characters.

The address properties have varying limits, which are shown in the table below.

Address1-3 line mapping

When you modify the address object, the Address1-3 fields are recalculated. Structured address data is mapped into the three legacy address lines (Address1–3) as follows.
Each line has a maximum length of 35 characters; excess content is truncated.

Address1 and Address2 may be empty if none of their respective source fields are provided.

The mapping depends on whether the addressLine, also known as hybrid address, is used.

No hybrid address

Address1

• If <postBox> is provided → <postBox>
• Else → <buildingNumber> + <streetName>

Address2

Appended in this order (skip missing fields):
<buildingName>, <floor>, <room>, <department>, <subDepartment>

Address3

• Always starts with <country> (ISO 2 alpha‑2)

• Then append, in order (skip missing fields):
  <townName>, <postCode>, <countrySubDivision>, <townLocationName>, <districtName>

Hybrid address

Address1

If <addressLine[0]> is provided → <addressLine[0]>

Address2

• If <addressLine[0]> + <addressLine[1]> are provided → <addressLine[1]>
• Else If <addressLine[0]> is provided → always starts with <country> (ISO 2 alpha‑2). Then append, in order (skip missing fields):
  <townName>, <postCode>, <countrySubDivision>, <townLocationName>, <districtName>

Address3

• If <addressLine[0]> + <addressLine[1]> are provided → always starts with <country> (ISO 2 alpha‑2). Then append, in order (skip missing fields):
  <townName>, <postCode>, <countrySubDivision>, <townLocationName>, <districtName>
• Else If <addressLine[0]> is provided → In order (skip missing fields): <streetName>, <buildingNumber>, <buildingName>, <floor>, <postBox>, <room>, <department>, <subDepartment>

After a successful modification request, you can check the status of the modification process with the status endpoint.