Create a legal entity

post/legalEntities

API Version

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://balanceplatform-api-test.adyen.com/bcl/v1/legalEntities

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 website and app URL of the legal entity.

Information about the organization. Required if type is organization.

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.

Indicates whether the legal entity is exempt from tax. When true, the taxIdAbsenceReason must be provided.

The organization's tax identifier.

The reason the organization has not provided a tax identifier.

Possible values: industryExemption, belowTaxThreshold.

Type of organization.

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

The website and app URL of the legal entity.

Max length: 150

Your reference for the legal entity, maximum 150 characters.

The type of legal entity.

Possible values: individual or organization

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.
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.
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 were allowed for the Legal Entity.
amountPerIndustryobject
The maximum amount a card holder can spend per industry.
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
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.
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
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 Legal Entity is permitted to use the capability,
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.
amountPerIndustryobject
The maximum amount a card holder can spend per industry.
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
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.
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
transferInstrumentsarray[object]
Capability status for transfer instruments associated with legal entity
allowedboolean
Indicates whether the supporting entity capability is allowed.

If a supporting entity is allowed but its parent legal entity is not, it means there are other supporting entities that failed validation.

The allowed supporting entity can still be used
idstring
Supporting entity reference
requestedboolean
Indicates whether the supporting entity capability is requested.
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.

documentsarray[object]Deprecated in version 1
Use the documentDetails array instead.
List of documents uploaded for the legal entity.
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.
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.

typestring
Defines the relationship of the legal entity to the current legal entity.

For example, uboThroughOwnership, uboThroughControl, signatory, or soleProprietorship.
idstring
The unique identifier of the legal entity.
individualobject
Information about the individual. Required if type is individual.
birthDataobject
The individual's birth information.
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.
cardNumberstring
The card number of the document that was issued (AU only).
expiryDatestringDeprecated in version 1
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 document, used when providing an ID number or uploading a document. The possible values depend on the legal entity type.

When providing ID numbers:

For individual, the type values can be driversLicense, identityCard, nationalIdNumber, or passport.

When uploading documents:

For organization, the type values can be proofOfAddress, registrationDocument, taxDocument, proofOfOwnership, or proofOfIndustry.

For individual, the type values can be identityCard, driversLicense, proofOfNationalIdNumber, proofOfResidency, or proofOfIndustry.

Use bankStatement to upload documents for a transfer instrument.

name
The individual's name.
firstNamestring
The individual's first name.
infixstring
The infix in the individual's name, if any.
lastNamestring
The individual's last name.
nationalitystring
The individual's nationality.
phone
The phone number of the legal entity.
countryCodestring
The two-letter ISO 3166-1 alpha-2 country code. For example, US or NL.
numberstring
The phone number.
typestring
The type of phone number. Possible values: mobile, landline, sip, fax.
residentialAddress
The residential address of the individual.
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.
webDataobjectDeprecated in version 1
The website and app URL of the legal entity.
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.
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.
phone
The phone number of the legal entity.
countryCodestring
The two-letter ISO 3166-1 alpha-2 country code. For example, US or NL.
numberstring
The phone number.
typestring
The type of phone number. Possible values: mobile, landline, sip, fax.
principalPlaceOfBusiness
The address where the organization operates from. Provide this if the principal place of business is different from the registeredAddress.
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.
registeredAddress
The address of the organization registered at their registrar (such as the Chamber of Commerce).
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.
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.
taxExemptboolean
Indicates whether the legal entity is exempt from tax. When true, the taxIdAbsenceReason must be provided.

taxIdstring
The organization's tax identifier.
taxIdAbsenceReasonstring
The reason the organization has not provided a tax identifier.

Possible values: industryExemption, belowTaxThreshold.
typestring
Type of organization.

Possible values: associationIncorporated, governmentalOrganization, listedPublicCompany, nonProfit, partnershipIncorporated, privateCompany.
webDataobjectDeprecated in version 1
The website and app URL of the legal entity.
webAddressstring
The URL of the website or the app store URL.
webAddressIdstring
The unique identifier of the web address.
referencestring
Max length: 150
Your reference for the legal entity, maximum 150 characters.
transferInstrumentsarray[object]
List of transfer instruments that the legal entity owns.
accountIdentifierstring
The masked IBAN or bank account number.
idstring
The unique identifier of the resource.
typestring
The type of legal entity.

Possible values: individual or organization
400 - Bad Request
A problem reading or understanding the request.
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.
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.
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.
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.
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.

Create a legal entity

HTTP Responses

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

422 - Unprocessable Entity

500 - Internal Server Error