Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
version: '6'
x-publicVersion: true
title: Adyen Account Get Account Holder API
description: "This API is used for the classic integration. If you are just starting your implementation, refer to our [new integration guide](https://docs.adyen.com/marketplaces-and-platforms) instead.\n\nThe Account API provides endpoints for managing account-related entities on your platform. These related entities include account holders, accounts, bank accounts, shareholders, and verification-related documents. The management operations include actions such as creation, retrieval, updating, and deletion of them.\n\nFor more information, refer to our [documentation](https://docs.adyen.com/marketplaces-and-platforms/classic).\n## Authentication\nYour Adyen contact will provide your API credential and an API key. To connect to the API, add an `X-API-Key` header with the API key as the value, for example:\n\n ```\ncurl\n-H \"Content-Type: application/json\" \\\n-H \"X-API-Key: YOUR_API_KEY\" \\\n...\n```\n\nAlternatively, you can use the username and password to connect to the API using basic authentication. For example:\n\n```\ncurl\n-U \"ws@MarketPlace.YOUR_PLATFORM_ACCOUNT\":\"YOUR_WS_PASSWORD\" \\\n-H \"Content-Type: application/json\" \\\n...\n```\nWhen going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/development-resources/live-endpoints).\n\n## Versioning\nThe Account API supports [versioning](https://docs.adyen.com/development-resources/versioning) using a version suffix in the endpoint URL. This suffix has the following format: \"vXX\", where XX is the version number.\n\nFor example:\n```\nhttps://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder\n```"
x-timestamp: '2023-05-30T15:27:20Z'
termsOfService: https://www.adyen.com/legal/terms-and-conditions
contact:
name: Adyen Developer Experience team
url: https://github.com/Adyen/adyen-openapi
servers:
- url: https://cal-test.adyen.com/cal/services/Account/v6
tags:
- name: getAccountHolder
paths:
/getAccountHolder:
post:
tags:
- getAccountHolder
summary: Adyen Get an Account Holder
description: Returns the details of an account holder.
operationId: post-getAccountHolder
x-groupName: Account holders
x-sortIndex: 2
x-methodName: getAccountHolder
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
accountCode:
$ref: '#/components/examples/post-getAccountHolder-accountCode'
accountHolderCode:
$ref: '#/components/examples/post-getAccountHolder-accountHolderCode'
schema:
$ref: '#/components/schemas/GetAccountHolderRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetAccountHolderResponse'
examples:
post-getAccountHolder200Example:
summary: Default post-getAccountHolder 200 response
x-microcks-default: true
value:
accountHolderCode: CODE123
accountHolderDetails: example_value
accountHolderStatus: active
accounts:
- example_value
description: A sample description for this resource.
invalidFields:
- example_value
legalEntity: Business
migrationData: example_value
primaryCurrency: USD
pspReference: REF-001
resultCode: CODE123
systemUpToDateTime: '2025-03-15T14:30:00Z'
verification: example_value
verificationProfile: example_value
description: OK - the request has succeeded.
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/GetAccountHolderResponse'
examples:
post-getAccountHolder202Example:
summary: Default post-getAccountHolder 202 response
x-microcks-default: true
value:
accountHolderCode: CODE123
accountHolderDetails: example_value
accountHolderStatus: active
accounts:
- example_value
description: A sample description for this resource.
invalidFields:
- example_value
legalEntity: Business
migrationData: example_value
primaryCurrency: USD
pspReference: REF-001
resultCode: CODE123
systemUpToDateTime: '2025-03-15T14:30:00Z'
verification: example_value
verificationProfile: example_value
description: Accepted - the request has been accepted for processing, but the processing has not been completed.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-getAccountHolder401Example:
summary: Default post-getAccountHolder 401 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-403'
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-getAccountHolder422Example:
summary: Default post-getAccountHolder 422 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-getAccountHolder500Example:
summary: Default post-getAccountHolder 500 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
LegalArrangementEntityDetail:
properties:
address:
description: The address of the entity.
$ref: '#/components/schemas/ViasAddress'
businessDetails:
description: Required when creating an entity with `legalEntityType` **Business**, **NonProfit**, **PublicCompany**, or **Partnership**.
$ref: '#/components/schemas/BusinessDetails'
email:
description: The e-mail address of the entity.
type: string
fullPhoneNumber:
description: 'The phone number of the contact provided as a single string. It will be handled as a landline phone.
**Examples:** "0031 6 11 22 33 44", "+316/1122-3344", "(0031) 611223344"'
type: string
individualDetails:
description: Required when creating an entity with `legalEntityType` **Individual**.
$ref: '#/components/schemas/IndividualDetails'
legalArrangementEntityCode:
description: 'Adyen-generated unique alphanumeric identifier (UUID) for the entry, returned in the response when you create a legal arrangement entity.
Use only when updating an account holder. If you include this field when creating an account holder, the request will fail.'
type: string
legalArrangementEntityReference:
description: Your reference for the legal arrangement entity.
type: string
legalArrangementMembers:
description: 'An array containing the roles of the entity in the legal arrangement.
The possible values depend on the legal arrangement `type`.
- For `type` **Association**: **ControllingPerson** and **Shareholder**.
- For `type` **Partnership**: **Partner** and **Shareholder**.
- For `type` **Trust**: **Trustee**, **Settlor**, **Protector**, **Beneficiary**, and **Shareholder**.
'
items:
enum:
- Beneficiary
- ControllingPerson
- Partner
- Protector
- Settlor
- Shareholder
- Trustee
type: string
type: array
legalEntityType:
description: 'The legal entity type.
Possible values: **Business**, **Individual**, **NonProfit**, **PublicCompany**, or **Partnership**. '
enum:
- Business
- Individual
- NonProfit
- Partnership
- PublicCompany
type: string
phoneNumber:
description: The phone number of the entity.
$ref: '#/components/schemas/ViasPhoneNumber'
webAddress:
description: The URL of the website of the contact.
type: string
type: object
KYCCheckResult:
properties:
checks:
description: A list of the checks and their statuses.
items:
$ref: '#/components/schemas/KYCCheckStatusData'
type: array
type: object
GetAccountHolderResponse:
properties:
accountHolderCode:
description: The code of the account holder.
type: string
accountHolderDetails:
description: Details of the account holder.
$ref: '#/components/schemas/AccountHolderDetails'
accountHolderStatus:
x-addedInVersion: '2'
description: The status of the account holder.
$ref: '#/components/schemas/AccountHolderStatus'
accounts:
description: A list of the accounts under the account holder.
items:
$ref: '#/components/schemas/Account'
type: array
description:
x-addedInVersion: '4'
description: The description of the account holder.
type: string
invalidFields:
x-addedInVersion: '5'
description: Contains field validation errors that would prevent requests from being processed.
items:
$ref: '#/components/schemas/ErrorFieldType'
type: array
legalEntity:
description: The legal entity of the account holder.
enum:
- Business
- Individual
- NonProfit
- Partnership
- PublicCompany
type: string
migrationData:
x-addedInVersion: '5'
description: Details of the account holder migrated to the balance platform.
$ref: '#/components/schemas/MigrationData'
primaryCurrency:
x-addedInVersion: '4'
description: The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes), with which the prospective account holder primarily deals.
type: string
pspReference:
description: The reference of a request. Can be used to uniquely identify the request.
type: string
resultCode:
description: The result code.
type: string
systemUpToDateTime:
x-addedInVersion: '5'
description: The time that shows how up to date is the information in the response.
format: date-time
type: string
verification:
x-addedInVersion: '2'
description: The details of KYC Verification of the account holder.
$ref: '#/components/schemas/KYCVerificationResult'
verificationProfile:
x-addedInVersion: '6'
description: The identifier of the profile that applies to this entity.
type: string
type: object
MigratedStores:
properties:
businessLineId:
description: The unique identifier of the business line associated with the migrated account holder in the balance platform.
type: string
storeCode:
description: The unique identifier of the store associated with the migrated account holder in the classic integration.
type: string
storeId:
description: The unique identifier of the store associated with the migrated account holder in the balance platform.
type: string
storeReference:
description: Your reference for the store in the classic integration. The [Customer Area](https://ca-test.adyen.com/) uses this value for the store description.
type: string
type: object
KYCCheckStatusData:
properties:
requiredFields:
description: A list of the fields required for execution of the check.
items:
type: string
type: array
status:
description: 'The status of the check.
Possible values: **AWAITING_DATA** , **DATA_PROVIDED**, **FAILED**, **INVALID_DATA**, **PASSED**, **PENDING**, **RETRY_LIMIT_REACHED**.'
enum:
- AWAITING_DATA
- DATA_PROVIDED
- FAILED
- INVALID_DATA
- PASSED
- PENDING
- PENDING_REVIEW
- RETRY_LIMIT_REACHED
- UNCHECKED
type: string
summary:
description: A summary of the execution of the check.
$ref: '#/components/schemas/KYCCheckSummary'
type:
description: "The type of check.\n\nPossible values:\n\n * **BANK_ACCOUNT_VERIFICATION**: Used in v5 and earlier. Replaced by **PAYOUT_METHOD_VERIFICATION** in v6 and later.\n\n * **COMPANY_VERIFICATION**\n\n * **CARD_VERIFICATION**\n\n* **IDENTITY_VERIFICATION**\n\n* **LEGAL_ARRANGEMENT_VERIFICATION**\n\n* **NONPROFIT_VERIFICATION**\n\n * **PASSPORT_VERIFICATION**\n\n* **PAYOUT_METHOD_VERIFICATION**: Used in v6 and later.\n\n* **PCI_VERIFICATION**"
enum:
- BANK_ACCOUNT_VERIFICATION
- CARD_VERIFICATION
- COMPANY_VERIFICATION
- IDENTITY_VERIFICATION
- LEGAL_ARRANGEMENT_VERIFICATION
- NONPROFIT_VERIFICATION
- PASSPORT_VERIFICATION
- PAYOUT_METHOD_VERIFICATION
- PCI_VERIFICATION
type: string
required:
- type
- status
type: object
ViasName:
properties:
firstName:
description: The first name.
maxLength: 80
type: string
gender:
description: 'The gender.
>The following values are permitted: `MALE`, `FEMALE`, `UNKNOWN`.'
enum:
- MALE
- FEMALE
- UNKNOWN
maxLength: 1
type: string
infix:
description: 'The name''s infix, if applicable.
>A maximum length of twenty (20) characters is imposed.'
maxLength: 20
type: string
lastName:
description: The last name.
maxLength: 80
type: string
type: object
KYCVerificationResult:
properties:
accountHolder:
description: The results of the checks on the account holder.
$ref: '#/components/schemas/KYCCheckResult'
legalArrangements:
x-addedInVersion: '6'
description: The results of the checks on the legal arrangements.
items:
$ref: '#/components/schemas/KYCLegalArrangementCheckResult'
type: array
legalArrangementsEntities:
x-addedInVersion: '6'
description: The results of the checks on the legal arrangement entities.
items:
$ref: '#/components/schemas/KYCLegalArrangementEntityCheckResult'
type: array
payoutMethods:
x-addedInVersion: '6'
description: The results of the checks on the payout methods.
items:
$ref: '#/components/schemas/KYCPayoutMethodCheckResult'
type: array
shareholders:
description: The results of the checks on the shareholders.
items:
$ref: '#/components/schemas/KYCShareholderCheckResult'
type: array
signatories:
description: The results of the checks on the signatories.
items:
$ref: '#/components/schemas/KYCSignatoryCheckResult'
type: array
ultimateParentCompany:
x-addedInVersion: '6'
description: The result of the check on the Ultimate Parent Company.
items:
$ref: '#/components/schemas/KYCUltimateParentCompanyCheckResult'
type: array
type: object
PayoutScheduleResponse:
properties:
nextScheduledPayout:
description: The date of the next scheduled payout.
format: date-time
type: string
schedule:
description: 'The payout schedule of the account.
Permitted values: `DEFAULT`, `DAILY`, `DAILY_US`, `DAILY_EU`, `DAILY_AU`, `DAILY_SG`, `WEEKLY`, `WEEKLY_ON_TUE_FRI_MIDNIGHT`, `BIWEEKLY_ON_1ST_AND_15TH_AT_MIDNIGHT`, `MONTHLY`, `HOLD`.'
enum:
- BIWEEKLY_ON_1ST_AND_15TH_AT_MIDNIGHT
- DAILY
- DAILY_AU
- DAILY_EU
- DAILY_SG
- DAILY_US
- HOLD
- MONTHLY
- WEEKLY
- WEEKLY_MON_TO_FRI_AU
- WEEKLY_MON_TO_FRI_EU
- WEEKLY_MON_TO_FRI_US
- WEEKLY_ON_TUE_FRI_MIDNIGHT
- WEEKLY_SUN_TO_THU_AU
- WEEKLY_SUN_TO_THU_US
type: string
type: object
IndividualDetails:
properties:
name:
description: 'The name of the individual.
>Make sure your account holder registers using the name shown on their Photo ID.'
$ref: '#/components/schemas/ViasName'
personalData:
description: Personal information of the individual.
$ref: '#/components/schemas/ViasPersonalData'
type: object
SignatoryContact:
properties:
address:
description: The address of the person.
$ref: '#/components/schemas/ViasAddress'
email:
description: The e-mail address of the person.
type: string
fullPhoneNumber:
description: 'The phone number of the person provided as a single string. It will be handled as a landline phone.
Examples: "0031 6 11 22 33 44", "+316/1122-3344", "(0031) 611223344"'
type: string
jobTitle:
description: 'Job title of the signatory.
Example values: **Chief Executive Officer**, **Chief Financial Officer**, **Chief Operating Officer**, **President**, **Vice President**, **Executive President**, **Managing Member**, **Partner**, **Treasurer**, **Director**, or **Other**.'
type: string
name:
description: The name of the person.
$ref: '#/components/schemas/ViasName'
personalData:
description: Contains information about the person.
$ref: '#/components/schemas/ViasPersonalData'
phoneNumber:
description: The phone number of the person.
$ref: '#/components/schemas/ViasPhoneNumber'
signatoryCode:
description: 'The unique identifier (UUID) of the signatory.
>**If, during an Account Holder create or update request, this field is left blank (but other fields provided), a new Signatory will be created with a procedurally-generated UUID.**
>**If, during an Account Holder create request, a UUID is provided, the creation of the Signatory will fail while the creation of the Account Holder will continue.**
>**If, during an Account Holder update request, a UUID that is not correlated with an existing Signatory is provided, the update of the Signatory will fail.**
>**If, during an Account Holder update request, a UUID that is correlated with an existing Signatory is provided, the existing Signatory will be updated.**
'
type: string
signatoryReference:
description: Your reference for the signatory.
type: string
webAddress:
description: The URL of the person's website.
type: string
type: object
ViasPhoneNumber:
properties:
phoneCountryCode:
description: 'The two-character country code of the phone number.
>The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. ''NL'').'
type: string
phoneNumber:
description: 'The phone number.
>The inclusion of the phone number country code is not necessary.'
type: string
phoneType:
description: 'The type of the phone number.
>The following values are permitted: `Landline`, `Mobile`, `SIP`, `Fax`.'
enum:
- Fax
- Landline
- Mobile
- SIP
type: string
type: object
Amount:
properties:
currency:
description: The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes).
maxLength: 3
minLength: 3
type: string
value:
description: The amount of the transaction, in [minor units](https://docs.adyen.com/development-resources/currency-codes).
format: int64
type: integer
required:
- value
- currency
type: object
ViasAddress:
properties:
city:
description: The name of the city. Required if the `houseNumberOrName`, `street`, `postalCode`, or `stateOrProvince` are provided.
type: string
country:
description: The two-character country code of the address in ISO-3166-1 alpha-2 format. For example, **NL**.
type: string
houseNumberOrName:
description: The number or name of the house.
type: string
postalCode:
description: 'The postal code. Required if the `houseNumberOrName`, `street`, `city`, or `stateOrProvince` are provided.
Maximum length:
* 5 digits for addresses in the US.
* 10 characters for all other countries.'
type: string
stateOrProvince:
description: "The abbreviation of the state or province. Required if the `houseNumberOrName`, `street`, `city`, or `postalCode` are provided. \n\nMaximum length:\n\n* 2 characters for addresses in the US or Canada.\n\n* 3 characters for all other countries.\n"
type: string
street:
description: The name of the street. Required if the `houseNumberOrName`, `city`, `postalCode`, or `stateOrProvince` are provided.
type: string
required:
- country
type: object
KYCCheckSummary:
properties:
kycCheckCode:
x-addedInVersion: '5'
description: The code of the check. For possible values, refer to [Verification codes](https://docs.adyen.com/marketplaces-and-platforms/classic/verification-process/verification-codes).
format: int32
type: integer
kycCheckDescription:
x-addedInVersion: '5'
description: A description of the check.
type: string
type: object
MigratedAccounts:
properties:
balanceAccountId:
description: The unique identifier of the account of the migrated account holder in the balance platform.
type: string
virtualAccountCode:
description: The unique identifier of the account of the migrated account holder in the classic integration.
type: string
type: object
AccountPayoutState:
properties:
allowPayout:
description: Indicates whether payouts are allowed. This field is the overarching payout status, and is the aggregate of multiple conditions (e.g., KYC status, disabled flag, etc). If this field is false, no payouts will be permitted for any of the account holder's accounts. If this field is true, payouts will be permitted for any of the account holder's accounts.
type: boolean
disableReason:
description: The reason why payouts (to all of the account holder's accounts) have been disabled (by the platform). If the `disabled` field is true, this field can be used to explain why.
type: string
disabled:
description: Indicates whether payouts have been disabled (by the platform) for all of the account holder's accounts. A platform may enable and disable this field at their discretion. If this field is true, `allowPayout` will be false and no payouts will be permitted for any of the account holder's accounts. If this field is false, `allowPayout` may or may not be enabled, depending on other factors.
type: boolean
notAllowedReason:
x-addedInVersion: '5'
description: The reason why payouts (to all of the account holder's accounts) have been disabled (by Adyen). If payouts have been disabled by Adyen, this field will explain why. If this field is blank, payouts have not been disabled by Adyen.
type: string
payoutLimit:
description: The maximum amount that payouts are limited to. Only applies if payouts are allowed but limited.
$ref: '#/components/schemas/Amount'
tierNumber:
x-addedInVersion: '3'
description: The payout tier that the account holder occupies.
format: int32
type: integer
type: object
PayoutMethod:
properties:
merchantAccount:
description: The [`merchantAccount`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments__reqParam_merchantAccount) you used in the `/payments` request when you [saved the account holder's card details](https://docs.adyen.com/marketplaces-and-platforms/classic/payouts/manual-payout/payout-to-cards#check-and-store).
type: string
payoutMethodCode:
description: Adyen-generated unique alphanumeric identifier (UUID) for the payout method, returned in the response when you create a payout method. Required when updating an existing payout method in an `/updateAccountHolder` request.
type: string
payoutMethodReference:
description: Your reference for the payout method.
type: string
recurringDetailReference:
description: The [`recurringDetailReference`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments__resParam_additionalData-ResponseAdditionalDataCommon-recurring-recurringDetailReference) returned in the `/payments` response when you [saved the account holder's card details](https://docs.adyen.com/marketplaces-and-platforms/classic/payouts/manual-payout/payout-to-cards#check-and-store).
type: string
shopperReference:
description: The [`shopperReference`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments__reqParam_shopperReference) you sent in the `/payments` request when you [saved the account holder's card details](https://docs.adyen.com/marketplaces-and-platforms/classic/payouts/manual-payout/payout-to-cards#check-and-store).
type: string
required:
- merchantAccount
- shopperReference
- recurringDetailReference
type: object
FieldType:
properties:
field:
description: The full name of the property.
type: string
fieldName:
description: The type of the field.
enum:
- accountCode
- accountHolderCode
- accountHolderDetails
- accountNumber
- accountStateType
- accountStatus
- accountType
- address
- balanceAccount
- balanceAccountActive
- balanceAccountCode
- balanceAccountId
- bankAccount
- bankAccountCode
- bankAccountName
- bankAccountUUID
- bankBicSwift
- bankCity
- bankCode
- bankName
- bankStatement
- branchCode
- businessContact
- cardToken
- checkCode
- city
- companyRegistration
- constitutionalDocument
- controller
- country
- countryCode
- currency
- currencyCode
- dateOfBirth
- description
- destinationAccountCode
- document
- documentContent
- documentExpirationDate
- documentIssuerCountry
- documentIssuerState
- documentName
- documentNumber
- documentType
- doingBusinessAs
- drivingLicence
- drivingLicenceBack
- drivingLicenceFront
- drivingLicense
- email
- firstName
- formType
- fullPhoneNumber
- gender
- hopWebserviceUser
- houseNumberOrName
- iban
- idCard
- idCardBack
- idCardFront
- idNumber
- identityDocument
- individualDetails
- infix
- jobTitle
- lastName
- lastReviewDate
- legalArrangement
- legalArrangementCode
- legalArrangementEntity
- legalArrangementEntityCode
- legalArrangementLegalForm
- legalArrangementMember
- legalArrangementMembers
- legalArrangementName
- legalArrangementReference
- legalArrangementRegistrationNumber
- legalArrangementTaxNumber
- legalArrangementType
- legalBusinessName
- legalEntity
- legalEntityType
- logo
- merchantAccount
- merchantCategoryCode
- merchantHouseNumber
- merchantReference
- microDeposit
- name
- nationality
- originalReference
- ownerCity
- ownerCountryCode
- ownerDateOfBirth
- ownerHouseNumberOrName
- ownerName
- ownerPostalCode
- ownerState
- ownerStreet
- passport
- passportNumber
- payoutMethod
- payoutMethodCode
- payoutSchedule
- pciSelfAssessment
- personalData
- phoneCountryCode
- phoneNumber
- postalCode
- primaryCurrency
- reason
- registrationNumber
- returnUrl
- schedule
- shareholder
- shareholderCode
- shareholderCodeAndSignatoryCode
- shareholderCodeOrSignatoryCode
- shareholderType
- shareholderTypes
- shopperInteraction
- signatory
- signatoryCode
- socialSecurityNumber
- sourceAccountCode
- splitAccount
-
# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adyen/refs/heads/main/openapi/adyen-getaccountholder-api-openapi.yml