Manage account holders

To get account holders, use the following endpoints:

• GET balancePlatforms/{id}/accountHolders: Get a list of the account holders in your platform. This endpoint returns a paginated list of account holders.
• GET /accountHolders/{id}: Get the details of an account holder, including their capabilities.
• GET /accountHolders/{id}/balanceAccounts: Get a list of the balance accounts of an account holder. This endpoint returns a paginated list of balance accounts.

To view the account holders in your platform:

1. Log in to your Balance Platform Customer Area.
2. Go to Accounts & balances > Account holders.
3. In the account holder table, select an Account holder ID to open the Account holder details page.

The Account holder details page shows information such as:

• The status of the account holder
• Their balance accounts and available balances
• Their associated legal entities
• The ID and type of their uploaded document
• Their capabilities

Filter and search

In the Account holders page, you can find specific account holders by using the filter and search features.

Set a filter by using the buttons on the filter bar, located on top of the account holder table. For example, you can filter account holders based on their capabilities and the capability statuses.

Also, you can search for an account holder by using their name or ID. You can limit the scope of search results by applying filters before searching.

To search for an account holder:

1. Select Search.
2. On the dropdown menu, select Account holder.
3. In the text field, enter the required data.

The search window now shows any corresponding account holders.

Liable account holder

To view the details of the liable account holder of your platform:

1. Go to Accounts & balances > Account holders.
2. Select View liable account holder.

The Account holder details of the liable account holder are shown.

When you make a GET /accountHolders/{id} request, refer to the following response parameters in the capabilities object:

• allowed: Boolean that indicates whether the capability is allowed.
• verificationStatus: The status of the checks. The possible values are invalid, pending, rejected, or valid.
• problems array: When this array is not empty, this means that there are errors that you need to address. Refer to verification error codes for a list of verification errors.

To view capabilities, you must have one of the following user roles:

• Balance platform admin role
• Balance platform base role

To view the capabilities of an account holder:

1. Log in to your Balance Platform Customer Area.
2. Do one of the following:
   • Go to Account holders and select an account holder ID from the table.
   • Search for an account holder by selecting Search. As a parameter, you can use the account holder ID, account holder reference, or the ID of the linked legal entity.
3. On the Account holder details page, you see details about the capabilities:
   • Whether the capabilities are allowed
   • Their verification status

Default capabilities are automatically requested when you create an account holder. However, if you need to request a specific capability, you must update the account holder and include the capabilities map.

In your PATCH /accountHolders/{id} request, set the capability that you are requesting as the key, and specify the following fields in the object:

• requested: Set this to true.
• requestedLevel: Set a capability level if required.

Here is an example of how to update an existing account holder to request the receivePayment capability. If you're requesting for multiple capabilities, add another set of key-value object.

You receive a response informing you that the capability has been requested and the verification status is pending.

To request a capability:

1. Log in to your Balance Platform Customer Area.

2. Do one of the following:

   • Go to Account holders and select an account holder ID from the table.
   • Search for an account holder by selecting Search. As a parameter, you can use the account holder ID, account holder reference, or the ID of the linked legal entity.

3. On the Account holder details page, select + Request new capability in the Capabilities section.

4. From the dropdown menu, select a capability and, if applicable, its level.

   You can only see capabilities that are already configured in your platform.

5. Select Submit.

6. On the confirmation window, select Submit request.

The capability request is sent to Adyen for approval.

To disable a capability, make a PATCH /accountHolders/{id} request to update the capability. Set the enabled field to false.

To enable or disable a capability:

1. Log in to your Balance Platform Customer Area.

2. Perform one of the following:

   • Go to Account holders and select an account holder ID from the table.
   • Search for an account holder by selecting Search. As a parameter, you can use the account holder ID, account holder reference, or the ID of the linked legal entity.

3. On the Account holder details page, select Edit in the Capabilities section.

4. In the Enabled column:

   • Select the corresponding checkbox to enable the capability.
   • Clear the corresponding checkbox to disable the capability.

5. Select Save.

6. On the confirmation window, select Save changes.