Create a legal entity

post/legalEntities

Creates a legal entity.

This resource contains information about the user that will be onboarded in your platform. Adyen uses this information to perform verification checks as required by payment industry regulations. Adyen informs you of the verification results through webhooks or API responses.

Endpoint destination URL

https://kyc-test.adyen.com/lem/v3/legalEntities

Header Parameters

Required

Optional

Use a suberror code as your requested verification code. You can include one code at a time in your request header. Requested verification codes can only be used in your test environment.

Request Parameters

Required

Optional

List of legal entities associated with the current legal entity. For example, ultimate beneficial owners associated with an organization through ownership or control, or as signatories.

Information about the individual. Required if type is individual.

The individual's birth information.

The email address of the legal entity.

Information about the individual's identification document.

The individual's name.

The individual's nationality.

The phone number of the legal entity.

The residential address of the individual.

The tax information of the individual.

The website and app URL of the legal entity.

Information about the organization. Required if type is organization.

The date when the organization was incorporated in YYYY-MM-DD format.

Your description for the organization.

The organization's trading name, if different from the registered legal name.

The email address of the legal entity.

The organization's legal name.

The phone number of the legal entity.

The address where the organization operates from. Provide this if the principal place of business is different from the registeredAddress.

The address of the organization registered at their registrar (such as the Chamber of Commerce).

The organization's registration number.

Information about the organization's publicly traded stock. Provide this object only if type is listedPublicCompany.

The tax information of the organization.

The tax reporting classification (FATCA/CRS self-certification) of the organization.

Type of organization.

Possible values: associationIncorporated, governmentalOrganization, listedPublicCompany, nonProfit, partnershipIncorporated, privateCompany.

The reason the organization has not provided a VAT number.

Possible values: industryExemption, belowTaxThreshold.

The organization's VAT number.

The website and app URL of the legal entity.

Max length: 150

Your reference for the legal entity, maximum 150 characters.

Information about the sole proprietorship. Required if type is soleProprietorship.

The two-character ISO 3166-1 alpha-2 country code of the governing country.

The date when the legal arrangement was incorporated in YYYY-MM-DD format.

Short description about the Legal Arrangement.

The registered name, if different from the name.

The legal name.

The business address. Required if the principal place of business is different from the registeredAddress.

The address registered at the registrar, such as the Chamber of Commerce.

The registration number.

The tax information of the entity.

The reason for not providing a VAT number.

Possible values: industryExemption, belowTaxThreshold.

The VAT number.

Information about the trust. Required if type is trust.

The two-character ISO 3166-1 alpha-2 country code of the governing country.

The date when the legal arrangement was incorporated in YYYY-MM-DD format.

Short description about the trust.

The registered name, if different from the name.

The legal name.

The business address. Required if the principal place of business is different from the registeredAddress.

The address registered at the registrar, such as the Chamber of Commerce.

The registration number.

The tax information of the entity.

Type of trust.

Possible values for Australian trusts: cashManagementTrust, corporateUnitTrust, deceasedEstate, discretionaryInvestmentTrust, discretionaryServicesManagementTrust, discretionaryTradingTrust, firstHomeSaverAccountsTrust, fixedTrust, fixedUnitTrust, hybridTrust, listedPublicUnitTrust, otherTrust, pooledSuperannuationTrust, publicTradingTrust, unlistedPublicUnitTrust.

The undefined beneficiary information of the entity.

The reason for not providing a VAT number.

Possible values: industryExemption, belowTaxThreshold.

The VAT number.

The type of legal entity.

Possible values: individual, organization, soleProprietorship, or trust.

A key-value pair that specifies the verification process for a legal entity. Set to upfront for upfront verification for marketplaces.

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.
Show moreShow less
capabilitiesobject
Contains key-value pairs that specify the actions that the legal entity 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.
Show children Hide children
allowedboolean
Indicates whether the capability is allowed. Adyen sets this to true if the verification is successful.
allowedLevelstring
The capability level that is allowed for the legal entity.

Possible values: notApplicable, low, medium, high.
allowedSettingsobject
The settings that are allowed for the legal entity.
Show children Hide children
amountPerIndustryobject
The maximum amount a card holder can spend per industry.
Show children Hide children
currencystring
The type of currency. Must be EUR (or EUR equivalent)
valueinteger
Total value of amount. Must be >= 0
authorizedCardUsersboolean
The number of card holders who can use the card.
fundingSourcearray[string]
The funding source of the card, for example debit.
intervalstring
The period when the rule conditions apply.
maxAmountobject
The maximum amount a card holder can withdraw per day.
Show children Hide children
currencystring
The type of currency. Must be EUR (or EUR equivalent)
valueinteger
Total value of amount. Must be >= 0
requestedboolean
Indicates whether the capability is requested. To check whether the legal entity 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
The settings that are requested for the legal entity.
Show children Hide children
amountPerIndustryobject
The maximum amount a card holder can spend per industry.
Show children Hide children
currencystring
The type of currency. Must be EUR (or EUR equivalent)
valueinteger
Total value of amount. Must be >= 0
authorizedCardUsersboolean
The number of card holders who can use the card.
fundingSourcearray[string]
The funding source of the card, for example debit.
intervalstring
The period when the rule conditions apply.
maxAmountobject
The maximum amount a card holder can withdraw per day.
Show children Hide children
currencystring
The type of currency. Must be EUR (or EUR equivalent)
valueinteger
Total value of amount. Must be >= 0
transferInstrumentsarray[object]
The capability status of transfer instruments associated with the legal entity.
Show children Hide children
allowedboolean
Indicates whether the capability is allowed for the supporting entity.

If a capability is allowed for a supporting entity but not for the parent legal entity, this means the legal entity has other supporting entities that failed verification.

You can use the allowed supporting entity regardless of the verification status of other supporting entities.
idstring
Supporting entity reference
requestedboolean
Indicates whether the supporting entity capability is requested.
verificationStatusstring
The status of the verification checks for the capability of the supporting entity.

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.

documentDetailsarray[object]
List of documents uploaded for the legal entity.
Show children Hide children
activeboolean
Identifies whether the document is active and used for checks.
descriptionstring
Your description for the document.
fileNamestring
Document name.
idstring
The unique identifier of the resource.
modificationDatestring
The modification date of the document.
pagesarray[object]
List of document pages
Show children Hide children
pageNamestring
pageNumberinteger
typestring
typestring
Type of document, used when providing an ID number or uploading a document.
documentsarray[object]Deprecated in version 1
Use the documentDetails array instead.
List of documents uploaded for the legal entity.
Show children Hide children
idstring
The unique identifier of the resource.
entityAssociationsarray[object]
List of legal entities associated with the current legal entity. For example, ultimate beneficial owners associated with an organization through ownership or control, or as signatories.
Show children Hide children
associatorIdstring
The unique identifier of another legal entity with which the legalEntityId is associated. When the legalEntityId is associated to legal entities other than the current one, the response returns all the associations.
entityTypestring
The legal entity type of associated legal entity.

For example, organization, soleProprietorship or individual.
jobTitlestring
The individual's job title if the type is uboThroughControl or signatory.
legalEntityIdstring
The unique identifier of the associated legal entity.
namestring
The name of the associated legal entity.

For individual, name.firstName and name.lastName.

For organization, legalName.

For soleProprietorship, name.

settlorExemptionReasonarray[string]
Defines the Kyc Exemption Reason for a Settlor associated with a trust.

For example, professionalServiceProvider, deceased, or contributionBelowThreshold.
typestring
Defines the relationship of the legal entity to the current legal entity.

Possible values for organizations: uboThroughOwnership, uboThroughControl, director, signatory, or ultimateParentCompany.

Possible values for sole proprietorships: soleProprietorship.

Possible value for trusts: trust

Possible values for trust members: definedBeneficiary, protector, secondaryTrustee, settlor, uboThroughControl, or uboThroughOwnership.
idstring
The unique identifier of the legal entity.
individualobject
Information about the individual. Required if type is individual.
Show children Hide children
birthDataobject
The individual's birth information.
Show children Hide children
dateOfBirthstring
The individual's date of birth, in YYYY-MM-DD format.
emailstring
The email address of the legal entity.
identificationDataobject
Information about the individual's identification document.
Show children Hide children
cardNumberstring
The card number of the document that was issued (AU only).
expiryDatestring
The expiry date of the document, in YYYY-MM-DD format.
issuerCountrystringDeprecated in version 1
The two-character ISO 3166-1 alpha-2 country code where the document was issued. For example, US.
issuerStatestring
The state or province where the document was issued (AU only).
nationalIdExemptboolean
Applies only to individuals in the US. Set to true if the individual does not have an SSN. To verify their identity, Adyen will require them to upload an ID document.
numberstring
The number in the document.
typestring
Type of identity data. For individual, the type value is nationalIdNumber.
nameobject
The individual's name.
Show children Hide children
firstNamestring
The individual's first name. Must not be blank.
infixstring
The infix in the individual's name, if any.
lastNamestring
The individual's last name. Must not be blank.
nationalitystring
The individual's nationality.
phoneobject
The phone number of the legal entity.
Show children Hide children
numberstring
The full phone number, including the country code. For example, +3112345678.
typestring
The type of phone number. Possible values: mobile, landline, sip, fax.
residentialAddressobject
The residential address of the individual.
Show children Hide children
citystring
The name of the city. Required if stateOrProvince is provided.

If you specify the city, you must also send postalCode and street.
countrystring
The two-letter ISO 3166-1 alpha-2 country code.
postalCodestring
Postal code. Required if stateOrProvince and/or city is provided.
stateOrProvincestring
The two-letter ISO 3166-2 state or province code. For example, CA in the US.

If you specify the state or province, you must also send city, postalCode, and street.
streetstring
The name of the street, and the house or building number. Required if stateOrProvince and/or city is provided.
street2string
The apartment, unit, or suite number.
taxInformationarray[object]
The tax information of the individual.
Show children Hide children
countrystring
Min length: 2Max length: 2
The two-letter ISO 3166-1 alpha-2 country code.
numberstring
The tax ID number (TIN) of the organization or individual.
typestring
The TIN type depending on the country where it was issued. Provide only for countries that have multiple tax IDs, such as Sweden, the UK, or the US. For example, provide SSN, EIN, or ITIN for the US.
webDataobjectDeprecated in version 1
The website and app URL of the legal entity.
Show children Hide children
webAddressstring
The URL of the website or the app store URL.
webAddressIdstring
The unique identifier of the web address.
organizationobject
Information about the organization. Required if type is organization.
Show children Hide children
dateOfIncorporationstring
The date when the organization was incorporated in YYYY-MM-DD format.
descriptionstring
Your description for the organization.
doingBusinessAsstring
The organization's trading name, if different from the registered legal name.
emailstring
The email address of the legal entity.
legalNamestring
The organization's legal name.
phoneobject
The phone number of the legal entity.
Show children Hide children
numberstring
The full phone number, including the country code. For example, +3112345678.
typestring
The type of phone number. Possible values: mobile, landline, sip, fax.
principalPlaceOfBusinessobject
The address where the organization operates from. Provide this if the principal place of business is different from the registeredAddress.
Show children Hide children
citystring
The name of the city. Required if stateOrProvince is provided.

If you specify the city, you must also send postalCode and street.
countrystring
The two-letter ISO 3166-1 alpha-2 country code.
postalCodestring
Postal code. Required if stateOrProvince and/or city is provided.
stateOrProvincestring
The two-letter ISO 3166-2 state or province code. For example, CA in the US.

If you specify the state or province, you must also send city, postalCode, and street.
streetstring
The name of the street, and the house or building number. Required if stateOrProvince and/or city is provided.
street2string
The apartment, unit, or suite number.
registeredAddressobject
The address of the organization registered at their registrar (such as the Chamber of Commerce).
Show children Hide children
citystring
The name of the city. Required if stateOrProvince is provided.

If you specify the city, you must also send postalCode and street.
countrystring
The two-letter ISO 3166-1 alpha-2 country code.
postalCodestring
Postal code. Required if stateOrProvince and/or city is provided.
stateOrProvincestring
The two-letter ISO 3166-2 state or province code. For example, CA in the US.

If you specify the state or province, you must also send city, postalCode, and street.
streetstring
The name of the street, and the house or building number. Required if stateOrProvince and/or city is provided.
street2string
The apartment, unit, or suite number.
registrationNumberstring
The organization's registration number.
stockDataobject
Information about the organization's publicly traded stock. Provide this object only if type is listedPublicCompany.
Show children Hide children
marketIdentifierstring
The four-digit Market Identifier Code of the stock market where the organization's stocks are traded.
stockNumberstring
The 12-digit International Securities Identification Number (ISIN) of the company, without dashes (-).
tickerSymbolstring
The stock ticker symbol.
taxInformationarray[object]
The tax information of the organization.
Show children Hide children
countrystring
Min length: 2Max length: 2
The two-letter ISO 3166-1 alpha-2 country code.
numberstring
The tax ID number (TIN) of the organization or individual.
typestring
The TIN type depending on the country where it was issued. Provide only for countries that have multiple tax IDs, such as Sweden, the UK, or the US. For example, provide SSN, EIN, or ITIN for the US.
taxReportingClassificationobject
The tax reporting classification (FATCA/CRS self-certification) of the organization.
Show children Hide children
businessTypestring
The organization's business type.

Possible values: other, listedPublicCompany, subsidiaryOfListedPublicCompany, governmentalOrganization, internationalOrganization, financialInstitution.
financialInstitutionNumberstring
The Global Intermediary Identification Number (GIIN) required for FATCA. Only required if the organization is a US financial institution and the businessType is financialInstitution.
mainSourceOfIncomestring
The organization's main source of income.

Possible values: businessOperation, realEstateSales, investmentInterestOrRoyalty, propertyRental, other.
typestring
The tax reporting classification type.

Possible values: nonFinancialNonReportable, financialNonReportable, nonFinancialActive, nonFinancialPassive.
typestring
Type of organization.

Possible values: associationIncorporated, governmentalOrganization, listedPublicCompany, nonProfit, partnershipIncorporated, privateCompany.
vatAbsenceReasonstring
The reason the organization has not provided a VAT number.

Possible values: industryExemption, belowTaxThreshold.
vatNumberstring
The organization's VAT number.
webDataobjectDeprecated in version 1
The website and app URL of the legal entity.
Show children Hide children
webAddressstring
The URL of the website or the app store URL.
webAddressIdstring
The unique identifier of the web address.
problemsarray[object]
List of verification errors related to capabilities for the legal entity.
Show children Hide children
entityobject
Show children Hide children
documentsarray[string]
List of document IDs corresponding to the verification errors from capabilities.
idstring
ownerobject
Show children Hide children
documentsarray[string]
List of document IDs corresponding to the verification errors from capabilities.
idstring
typestring
typestring
verificationErrorsarray[object]
Show children Hide children
capabilitiesarray[string]
Contains key-value pairs that specify the actions that the legal entity 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.
codestring
The general error code.
messagestring
The general error message.
remediatingActionsarray[object]
An object containing possible solutions to fix a verification error.
Show children Hide children
codestring
messagestring
subErrorsarray[object]
An array containing more granular information about the cause of the verification error.
Show children Hide children
capabilitiesarray[string]
Contains key-value pairs that specify the actions that the legal entity 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.
codestring
The general error code.
messagestring
The general error message.
typestring
The type of error.
remediatingActionsarray[object]
An object containing possible solutions to fix a verification error.
Show children Hide children
codestring
messagestring
typestring
The type of error.
referencestring
Max length: 150
Your reference for the legal entity, maximum 150 characters.
soleProprietorshipobject
Information about the sole proprietorship. Required if type is soleProprietorship.
Show children Hide children
countryOfGoverningLawstring
The two-character ISO 3166-1 alpha-2 country code of the governing country.
dateOfIncorporationstring
The date when the legal arrangement was incorporated in YYYY-MM-DD format.
descriptionstring
Short description about the Legal Arrangement.
doingBusinessAsstring
The registered name, if different from the name.
namestring
The legal name.
principalPlaceOfBusinessobject
The business address. Required if the principal place of business is different from the registeredAddress.
Show children Hide children
citystring
The name of the city. Required if stateOrProvince is provided.

If you specify the city, you must also send postalCode and street.
countrystring
The two-letter ISO 3166-1 alpha-2 country code.
postalCodestring
Postal code. Required if stateOrProvince and/or city is provided.
stateOrProvincestring
The two-letter ISO 3166-2 state or province code. For example, CA in the US.

If you specify the state or province, you must also send city, postalCode, and street.
streetstring
The name of the street, and the house or building number. Required if stateOrProvince and/or city is provided.
street2string
The apartment, unit, or suite number.
registeredAddressobject
The address registered at the registrar, such as the Chamber of Commerce.
Show children Hide children
citystring
The name of the city. Required if stateOrProvince is provided.

If you specify the city, you must also send postalCode and street.
countrystring
The two-letter ISO 3166-1 alpha-2 country code.
postalCodestring
Postal code. Required if stateOrProvince and/or city is provided.
stateOrProvincestring
The two-letter ISO 3166-2 state or province code. For example, CA in the US.

If you specify the state or province, you must also send city, postalCode, and street.
streetstring
The name of the street, and the house or building number. Required if stateOrProvince and/or city is provided.
street2string
The apartment, unit, or suite number.
registrationNumberstring
The registration number.
taxInformationarray[object]
The tax information of the entity.
Show children Hide children
countrystring
Min length: 2Max length: 2
The two-letter ISO 3166-1 alpha-2 country code.
numberstring
The tax ID number (TIN) of the organization or individual.
typestring
The TIN type depending on the country where it was issued. Provide only for countries that have multiple tax IDs, such as Sweden, the UK, or the US. For example, provide SSN, EIN, or ITIN for the US.
vatAbsenceReasonstring
The reason for not providing a VAT number.

Possible values: industryExemption, belowTaxThreshold.
vatNumberstring
The VAT number.
transferInstrumentsarray[object]
List of transfer instruments that the legal entity owns.
Show children Hide children
accountIdentifierstring
The masked IBAN or bank account number.
idstring
The unique identifier of the resource.
realLastFourstring
Four last digits of the bank account number. If the transfer instrument is created using instant bank account verification, and it is a virtual bank account, these digits may be different from the last four digits of the masked account number.
trustedSourceboolean
Identifies if the bank account was created through instant bank verification.
trustobject
Information about the trust. Required if type is trust.
Show children Hide children
countryOfGoverningLawstring
The two-character ISO 3166-1 alpha-2 country code of the governing country.
dateOfIncorporationstring
The date when the legal arrangement was incorporated in YYYY-MM-DD format.
descriptionstring
Short description about the trust.
doingBusinessAsstring
The registered name, if different from the name.
namestring
The legal name.
principalPlaceOfBusinessobject
The business address. Required if the principal place of business is different from the registeredAddress.
Show children Hide children
citystring
The name of the city. Required if stateOrProvince is provided.

If you specify the city, you must also send postalCode and street.
countrystring
The two-letter ISO 3166-1 alpha-2 country code.
postalCodestring
Postal code. Required if stateOrProvince and/or city is provided.
stateOrProvincestring
The two-letter ISO 3166-2 state or province code. For example, CA in the US.

If you specify the state or province, you must also send city, postalCode, and street.
streetstring
The name of the street, and the house or building number. Required if stateOrProvince and/or city is provided.
street2string
The apartment, unit, or suite number.
registeredAddressobject
The address registered at the registrar, such as the Chamber of Commerce.
Show children Hide children
citystring
The name of the city. Required if stateOrProvince is provided.

If you specify the city, you must also send postalCode and street.
countrystring
The two-letter ISO 3166-1 alpha-2 country code.
postalCodestring
Postal code. Required if stateOrProvince and/or city is provided.
stateOrProvincestring
The two-letter ISO 3166-2 state or province code. For example, CA in the US.

If you specify the state or province, you must also send city, postalCode, and street.
streetstring
The name of the street, and the house or building number. Required if stateOrProvince and/or city is provided.
street2string
The apartment, unit, or suite number.
registrationNumberstring
The registration number.
taxInformationarray[object]
The tax information of the entity.
Show children Hide children
countrystring
Min length: 2Max length: 2
The two-letter ISO 3166-1 alpha-2 country code.
numberstring
The tax ID number (TIN) of the organization or individual.
typestring
The TIN type depending on the country where it was issued. Provide only for countries that have multiple tax IDs, such as Sweden, the UK, or the US. For example, provide SSN, EIN, or ITIN for the US.
typestring
Type of trust.

Possible values for Australian trusts: cashManagementTrust, corporateUnitTrust, deceasedEstate, discretionaryInvestmentTrust, discretionaryServicesManagementTrust, discretionaryTradingTrust, firstHomeSaverAccountsTrust, fixedTrust, fixedUnitTrust, hybridTrust, listedPublicUnitTrust, otherTrust, pooledSuperannuationTrust, publicTradingTrust, unlistedPublicUnitTrust.
undefinedBeneficiaryInfoarray[object]
The undefined beneficiary information of the entity.
Show children Hide children
descriptionstring
The details of the undefined beneficiary.
referencestring
The reference of the undefined beneficiary.
vatAbsenceReasonstring
The reason for not providing a VAT number.

Possible values: industryExemption, belowTaxThreshold.
vatNumberstring
The VAT number.
typestring
The type of legal entity.

Possible values: individual, organization, soleProprietorship, or trust.
verificationDeadlinesarray[object]
List of verification deadlines and the capabilities that will be disallowed if verification errors are not resolved.
Show children Hide children
capabilitiesarray[string]
The list of capabilities that will be disallowed if information is not reviewed by the time of the deadline
entityIdsarray[string]
The unique identifiers of the legal entity or supporting entities that the deadline applies to
expiresAtstring
The date that verification is due by before capabilities are disallowed.
verificationPlanstring
A key-value pair that specifies the verification process for a legal entity. Set to upfront for upfront verification for marketplaces.
400 - Bad Request
A problem reading or understanding the request.
Show more Show less
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
401 - Unauthorized
Authentication required.
Show more Show less
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
403 - Forbidden
Insufficient permissions to process the request.
Show more Show less
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
422 - Unprocessable Entity
A request validation error.
Show more Show less
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
500 - Internal Server Error
The server could not process the request.
Show more Show less
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.