Update an account holder

patch/accountHolders/{id}

API Version

Updates an account holder. When updating an account holder resource, if a parameter is not provided in the request, it is left unchanged.

Endpoint destination URL

https://balanceplatform-api-test.adyen.com/bcl/v1/accountHolders/{id}

Path Parameters

Required

Optional

The unique identifier of the account holder.

Request Parameters

Required

Optional

The unique identifier of the balance platform to which the account holder belongs. Required in the request if your API credentials can be used for multiple balance platforms.

Contains key-value pairs that specify the actions that an account holder can do in your platform. The key is a capability required for your integration. For example, issueCard for Issuing. The value is an object containing the settings for the capability.

Contact details of the account holder.

Max length: 300

Your description for the account holder, maximum 300 characters.

The unique identifier of the legal entity associated with the account holder. Adyen performs a verification process against the legal entity of the account holder.

The ID of the account holder's primary balance account. By default, this is set to the first balance account that you create for the account holder. To assign a different balance account, send a PATCH request.

Max length: 150

Your reference for the account holder, maximum 150 characters.

The status of the account holder.

Possible values:

Active: The account holder is active. This is the default status when creating an account holder.
Inactive: The account holder is temporarily inactive due to missing KYC details. You can set the account back to active by providing the missing KYC details.
Suspended: The account holder is permanently deactivated by Adyen. This action cannot be undone.
Closed: The account holder is permanently deactivated by you. This action cannot be undone.

The time zone of the account holder. For example, Europe/Amsterdam. Defaults to the time zone of the balance platform if no time zone is set. For possible values, see the list of time zone codes.

Response parameters

After submitting a call, you receive a response message to inform you that your request was received and processed.

Depending on the HTTP status code of the response message, it is helpful to build some logic to handle any errors that a request or the system may return.

HTTP Responses

200 - OK
The request has succeeded.
balancePlatformstring
The unique identifier of the balance platform to which the account holder belongs. Required in the request if your API credentials can be used for multiple balance platforms.
capabilitiesobject
Contains key-value pairs that specify the actions that an account holder can do in your platform. The key is a capability required for your integration. For example, issueCard for Issuing. The value is an object containing the settings for the capability.
allowedboolean
Indicates whether the capability is allowed. Adyen sets this to true if the verification is successful and the account holder is permitted to use the capability.
allowedLevelstring
The capability level that is allowed for the account holder.

Possible values: notApplicable, low, medium, high.
allowedSettingsobject
A JSON object containing the settings that are allowed for the account holder.
pathsarray[object]
contentarray[string]
rootPathobject
contentarray[string]
enabledboolean
Indicates whether the capability is enabled. If false, the capability is temporarily disabled for the account holder.
problemsarray[object]
Contains verification errors and the actions that you can take to resolve them.
requestedboolean
Indicates whether the capability is requested. To check whether the account holder is permitted to use the capability, refer to the allowed field.
requestedLevelstring
The requested level of the capability. Some capabilities, such as those used in card issuing, have different levels. Levels increase the capability, but also require additional checks and increased monitoring.

Possible values: notApplicable, low, medium, high.
requestedSettingsobject
A JSON object containing the settings that were requested for the account holder.
pathsarray[object]
contentarray[string]
rootPathobject
contentarray[string]
transferInstrumentsarray[object]
Contains the status of the transfer instruments associated with this capability.
allowedboolean
Indicates whether the supporting entity capability is allowed. Adyen sets this to true if the verification is successful and the account holder is permitted to use the capability.
allowedLevelstring
The capability level that is allowed for the account holder.

Possible values: notApplicable, low, medium, high.
enabledboolean
Indicates whether the capability is enabled. If false, the capability is temporarily disabled for the account holder.
idstring
The ID of the supporting entity.
requestedboolean
Indicates whether the capability is requested. To check whether the account holder is permitted to use the capability, refer to the allowed field.
requestedLevelstring
The requested level of the capability. Some capabilities, such as those used in card issuing, have different levels. Levels increase the capability, but also require additional checks and increased monitoring.

Possible values: notApplicable, low, medium, high.
verificationStatusstring
The status of the verification checks for the supporting entity capability.

Possible values:

pending: Adyen is running the verification.

invalid: The verification failed. Check if the errors array contains more information.

valid: The verification has been successfully completed.

rejected: Adyen has verified the information, but found reasons to not allow the capability.

verificationStatusstring
The status of the verification checks for the capability.

Possible values:

pending: Adyen is running the verification.

invalid: The verification failed. Check if the errors array contains more information.

valid: The verification has been successfully completed.

rejected: Adyen has verified the information, but found reasons to not allow the capability.

contactDetailsobject
Contact details of the account holder.
addressobject
The address of the account holder.
citystring
Max length: 3000
The name of the city. Maximum length: 3000 characters.
countrystring
The two-character ISO-3166-1 alpha-2 country code. For example, US.

If you don't know the country or are not collecting the country from the shopper, provide country as ZZ.

houseNumberOrNamestring
Max length: 3000
The number or name of the house. Maximum length: 3000 characters.
postalCodestring
A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries.
stateOrProvincestring
The two-character ISO 3166-2 state or province code. For example, CA in the US or ON in Canada.

Required for the US and Canada.

streetstring
Max length: 3000
The name of the street. Maximum length: 3000 characters.

The house number should not be included in this field; it should be separately provided via houseNumberOrName.

emailstring
The email address of the account holder.
phoneobject
The phone number of the account holder.
numberstring
The full phone number provided as a single string. For example, "0031 6 11 22 33 44", "+316/1122-3344",

or "(0031) 611223344".
typestring
Type of phone number. Possible values: Landline, Mobile.

webAddressstring
The URL of the account holder's website.
descriptionstring
Max length: 300
Your description for the account holder, maximum 300 characters.
idstring
The unique identifier of the account holder.
legalEntityIdstring
The unique identifier of the legal entity associated with the account holder. Adyen performs a verification process against the legal entity of the account holder.
primaryBalanceAccountstring
The ID of the account holder's primary balance account. By default, this is set to the first balance account that you create for the account holder. To assign a different balance account, send a PATCH request.
referencestring
Max length: 150
Your reference for the account holder, maximum 150 characters.
statusstring
The status of the account holder.

Possible values:

Active: The account holder is active. This is the default status when creating an account holder.

Inactive: The account holder is temporarily inactive due to missing KYC details. You can set the account back to active by providing the missing KYC details.

Suspended: The account holder is permanently deactivated by Adyen. This action cannot be undone.

Closed: The account holder is permanently deactivated by you. This action cannot be undone.

timeZonestring
The time zone of the account holder. For example, Europe/Amsterdam. Defaults to the time zone of the balance platform if no time zone is set. For possible values, see the list of time zone codes.
400 - Bad Request
A problem reading or understanding the request.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
pathsarray[object]
contentarray[string]
rootPathobject
contentarray[string]
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
401 - Unauthorized
Authentication required.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
pathsarray[object]
contentarray[string]
rootPathobject
contentarray[string]
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
403 - Forbidden
Insufficient permissions to process the request.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
pathsarray[object]
contentarray[string]
rootPathobject
contentarray[string]
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
422 - Unprocessable Entity
A request validation error.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
pathsarray[object]
contentarray[string]
rootPathobject
contentarray[string]
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
500 - Internal Server Error
The server could not process the request.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
pathsarray[object]
contentarray[string]
rootPathobject
contentarray[string]
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.

Update an account holder

HTTP Responses

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

422 - Unprocessable Entity

500 - Internal Server Error