Required Parameters

The API fields shown on this page are relevant to the European Union only. To see the full payload, refer to the Onboard Corporate Customer API Reference.

note

All fields have a maximum limit of 255 characters unless stated otherwise.

Request parameters

Property	Description	Required
region	The country or geographic region where the end corporate customer is located and is onboarded. To onboard an EU-based customer, use the EU value.	Yes
businessDetails	An object that contains business details about the corporate customer.	Yes
riskAssessmentInfo	An object that contains the risk assessment information.	Yes
deviceDetails	An object that contains information about the customer's device and IP address.	Yes
expectedAccountUsage	An object that contains the expected usage of the account	Yes
natureOfBusiness	An object that contains the nature of business information	Yes
tags	An object that contains the tags.	No
clientId	This field contains the Nium client ID of the customer. It's received in the response to the previously executed Onboard Corporate Customer request. Note: This field is required to reinitiate the KYB process.	Yes *
customerHashId	This field contains the unique customer identifier generated at the time of the customer creation. It's received in the response to the previously executed Onboard Corporate Customer request. Note: This field is required to reinitiate the KYB process.	Yes *

Table headers

The below table headers refer to the businessType fields:

Association Sole trader Trust	Government Private Public	LLP
ASSOCIATION SOLE_TRADER TRUST	GOVERNMENT_ENTITY PRIVATE_COMPANY PUBLIC_COMPANY	LIMITED_LIABILITY_PARTNERSHIP

businessDetails object

An object that contains business details about the corporate customer.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
referenceId	The universally unique identifier (UUID) of the business entity that Nium uses to identify the businessDetails entity. If it's not provided, Nium generates one. The UUID is used to respond to a request for information (RFI) or to upload required documents for the business entity.	Optional	Optional	Optional
businessName	The name a corporate customer is registered under.	Required	Required	Required
businessRegistrationNumber	The business registration number.	Required	Required	Required
tradeName	In case the corporate customer is doing business under a different name than their licensed business name.	N/A	Required	Optional
website	The corporate customer's website.	Optional	Optional	Optional
businessType	The legal entity type of the business. Use Fetch corporate constants API for a valid set of values.	Required	Required	Required
legalDetails	An object that contains the legal details.	Required	Required	Required
taxDetails	An array of objects that contains the business taxation details.	Required	Required	Required
addresses	An object that contains the registered and business addresses of the corporate customer.	Required	Required	Required
documentDetails	An array of objects that contains the business documents. Note: For a complete list of required documents, see EU required documents.	Required *	Required *	Required *
stakeholders	An array of objects that contains the individual and corporate stakeholders of the corporate customer.	Required	Required	Required
applicantDetails	An object that contains the applicant's details.	Required	Required	Required
additionalInfo	An object that contains additional information about the business.	Optional	Optional	Optional

legalDetails object

An object within the businessDetails object that contains legal details.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
registeredDate	The date the business was registered entered in the YYYY-MM-DD format. Registered date cannot be a past date.	Required	Required	Required
registeredCountry	The country where the business is registered. Use Fetch corporate constants API for a valid set of values.	Required	Required	Required

taxDetails array

An array of objects within the businessDetails object that contains multiple values of taxation details of the corporate customer.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
country	The country in which the corporate customer is paying taxes. This will be the same as the registered country, unless the customer is paying taxes in other countries as well. Note: If the customer is a subsidiary or a part of a group of companies, the customer needs to provide countries where taxes are paid for its own legal entity and not for the entire group of companies. Use Fetch corporate constants API for a valid set of values.	Required	Required	Required
taxNumber	The tax ID number for this country. Max character length is 64 characters	Required	Required	Required

addresses object

An object within the businessDetails object that contain registered and business addresses.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
registeredAddress	An object that contains the address where the business is registered.	Required	Required	Required
businessAddress	An object that contains the address where the business is mainly conducted, if different than the registered address. Note: This is required if isSameBusinessAddress = No	Required *	Required *	Required *

registeredAddress object

An object within the businessDetails.address object that contains the address details where the corporate customer is registered.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
addressLine1	The first address line of the registered business.	Required	Required	Required
addressLine2	The second address line of the registered business.	Optional	Optional	Optional
city	The city where the corporate customer is registered.	Required	Required	Required
state	The state where the corporate customer is registered.	Required	Required	Required
country	The country where the corporate customer is registered. Use Fetch corporate constants API for a valid set of values.	Required	Required	Required
postcode	The postal code where the corporate customer is registered.	Required	Required	Required

businessAddress object

An object within the businessDetails.address object that contains the address details of the principal place of business only when the registered address is different.

* This object is required only if businessDetails.additionalInfo.isSameBusinessAddress = No.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
addressLine1	The first address line of the principal place of business if different than the registered business.	Required *	Required *	Required *
addressLine2	The second address line of the principal place of business if different than the registered business.	Optional	Optional	Optional
city	The city of the principal place of business if different than the registered address.	Required *	Required *	Required *
state	The state of the principal place of business if different than the registered address.	Required *	Required *	Required *
country	The country where the principal place of business occurs if different than the registered country. Use Fetch corporate constants API for a valid set of values.	Required *	Required *	Required *
postcode	The postal code where the principal place of business occurs if different than the registered address.	Required *	Required *	Required *

documentDetails object

An array of objects within the businessDetails object that contains one or more business documents.

* For a complete list of required documents, see EU required documents.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
documentType	The type of business document. Use Fetch corporate constants API for a valid set of values.	Required *	Required *	Required *
document	An array of objects that contains a copy of the document.	Required *	Required *	Required *

document object

An array object within the businessDetails.documentDetails object.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
fileName	The name of the file.	Required *	Required *	Required *
fileType	The type of the file. Valid types are application/pdf, image/jpeg, image/jpg, image/png, jpeg, jpg, and png.	Required *	Required *	Required *
document	The file as a base64 encoded string.	Required *	Required *	Required *

additionalInfo object

An object within the businessDetails object that contains additional information about the business.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
isSameBusinessAddress	This field accepts Yes or No to indicate if the principal place of business is the same or different from the registered business entity address. Note: Required only if Yes; optional if No.	Optional	Optional	Optional
searchId	This field is required for eKYB and is returned in the response of the Exhaustive Corporate Details using Business ID API.	Optional	Optional	Optional

stakeholders object

An array of objects within the businessDetails object that contains information about one or more stakeholders.

For every stakeholder object, you need to send either the stakeholderDetails or the businessPartner parameters.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
referenceId	The universal unique identifier (UUID) associated with the stakeholder and stakeholder object. If the UUID isn't provided, Nium generates one. The UUID can be used to respond to an RFI or to upload the required documents.	Optional	Optional	Optional
stakeholderDetails	An object that contains the details of the individual stakeholder.	Required	Required	Required
businessPartner	An object that contains the details of the corporate stakeholder, if available.	Required	Required	Required

stakeholderDetails object

An object within the stakeholders object that contains the details about an individual stakeholder.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
kycMode	The KYC mode for the individual stakeholder. Note: This field is required to be MANUAL_KYC for position= SIGNATORY, REPRESENTATIVE, UBO, TRUSTEE, PARTNER. Else ignore this field.	Required	Required	Required
firstName	The first name of the individual stakeholder.	Required	Required	Required
middleName	The middle name of the individual stakeholder.	Optional	Optional	Optional
lastName	The surname of the individual stakeholder.	Required	Required	Required
nationality	The nationality of the individual stakeholder.	Required	Required	Required
dateOfBirth	The date the individual stakeholder was born in the YYYY-MM-DD format. Date of birth cannot be a future date.	Required	Required	Required
birthCountry	The country of birth.	Required	Required	Required
taxDetails	The taxation details of the individual stakeholder. Note: This field is required if the position is UBO, TRUSTEE, or PARTNER.	Required *	Required *	Required *
professionalDetails	The professional details of the individual stakeholder.	Required	Required	Required
address	An object that contains the residential address of the individual stakeholder.	Required	Required	Required
contactDetails	An object that contains the contact details of the individual stakeholder.	Optional	Optional	Optional
documentDetails	An object that contains the document details of the individual stakeholder. Note: This field is required if position is UBO, TRUSTEE or PARTNER regardless of kycMode.	Required *	Required *	Required *
additionalInfo	An object that contains additional information about the individual stakeholder.	Required	Required	Required

taxDetails array

An array of objects within the businessDetails.stakeholders.stakeholderDetails object that contains the individual stakeholder's tax details of one or more countries.

* This object is required if the position is UBO, TRUSTEE, or PARTNER.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
country	The country of the stakeholder's residence. Use Fetch corporate constants API for a valid set of values.	Required *	Required *	Required *
taxNumber	The tax ID number for the corresponding country.	Required *	Required *	Required *

professionalDetails object

An array of objects within the businessDetails.stakeholders.stakeholderDetails object that contains the individual stakeholder's professional details.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
position	The position of the individual stakeholder. Use Fetch corporate constants API for a valid set of values.	Required	Required	Required
sharePercentage	The share percentage of the individual stakeholder in the company. Note: This field is a required input parameter If the stakeholder’s position is UBO.	Required *	Required *	Required *
positionStartDate	The date the individual stakeholder started the position of UBO. Note: This field is required if the individual stakeholder is currently an UBO or TRUSTEE or PARTNER. Position start date cannot be a future date.	Required *	Required *	Required *

address object

An object within the businessDetails.stakeholders.stakeholderDetails object that contains the individual stakeholder's residential address.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
addressLine1	The first address line of the individual stakeholder.	Required	Required	Required
addressLine2	The second address line of the individual stakeholder.	Optional	Optional	Optional
city	The city or suburb of the individual stakeholder.	Required	Required	Required
state	The state of the individual stakeholder.	Required	Required	Required
country	The country where the individual stakeholder resides. Use Fetch corporate constants API for a valid set of values.	Required	Required	Required
postcode	The postal code of the individual stakeholder.	Required	Required	Required

contactDetails object

An optional object within the businessDetails.stakeholders.stakeholderDetails object that contains the stakeholder's contact information.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
email	The individual stakeholder's email address.	Optional	Optional	Optional
contactNo	The contact phone number of the individual stakeholder.	Optional	Optional	Optional

documentDetails object

An array of objects within the businessDetails.stakeholders.stakeholderDetails object that contains the individual stakeholder's document details.

Please note:

• This object is required if the position is UBO, TRUSTEE, PARTNER or DIRECTOR regardless of kycMode.
• Document file is not required for the DIRECTOR position.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
documentType	The type of document. Use Fetch corporate constants API for a valid set of values.	Required *	Required *	Required *
documentNumber	The ID number for the given document type.	Required *	Required *	Required *
documentIssuanceCountry	The country that issued the business document. Use Fetch corporate constants API for a valid set of values. Not required if documentType= POWER_OF_ATTORNEY.	Required *	Required *	Required *
documentExpiryDate	The date the document expires in the YYYY-MM-DD format. Note: This is required only if documentType = PASSPORT. Expiry date cannot be a past date.	Required *	Required *	Required *
[document](#businessDetails-stakeholders-stakeholderDetails-document)	An array of objects that contains a copy of a document. Document is required only if kycMode=MANUAL_KYC.	Required *	Required *	Required *

document object

An array of objects within the businessDetails.stakeholders.stakeholderDetails.documentDetails object that contains a copy of the individual stakeholder's document.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
fileName	The name of the file.	Required *	Required *	Required *
fileType	The type of the file. Valid types are application/pdf, image/jpeg, image/jpg, image/png, jpeg, jpg, and png.	Required *	Required *	Required *
document	The file as a base64 encoded string.	Required *	Required *	Required *

additionalInfo object

An object within the businessDetails.stakeholders.stakeholderDetails object that contains additional information about the individual stakeholder.

Here's the provided data represented in a markdown table:

Property	Description	Association Sole trader Trust	Government	Private	Public	LLP
isPep	This field accepts Yes or No to indicate if the individual stakeholder is a politically exposed person.	Required	Required	Required	Required	Required

businessPartner

An object within the businessDetails.stakeholders object that contains the business details of the corporate stakeholder.

important

This object is required if a corporate stakeholder exists.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
businessName	The registered business name of the corporate stakeholder.	Required	Required	Required
businessRegistrationNumber	The business registration number.	Required	Required	Required
businessEntityType	The position of the corporate stakeholder in the company. Use Fetch corporate constants API for a valid set of values.	Required	Required	Required
sharePercentage	The share percentage of the corporate stakeholder in the company. Note: This field is a required input parameter If the stakeholder’s position is UBO.	Required *	Required *	Required *
legalDetails	An object that contains the legal details of the corporate stakeholder.	Required	Required	Required

legalDetails object

An object within the businessDetails.stakeholders.businessPartner object that contains the corporate stakeholder's legal details.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
registeredCountry	The country where the corporate stakeholder is registered. Use Fetch corporate constants API for a valid set of values.	Required	Required	Required

applicantDetails object

An object within the businessDetails object that contains details about the applicant.

Property	Description	Association	Sole trader	Trust	Government	Private	Public	LLP
referenceId	The universally unique identifier (UUID) associated with the applicant and applicant object.	Optional	Optional	Optional	Optional	Optional	Optional	Optional
kycMode	The KYC mode for verifying the identity of the applicant. The only valid value is E_DOC_VERIFY.	Required	Required	Required	Required	Required	Required	Required
firstName	The first name of the applicant.	Required	Required	Required	Required	Required	Required	Required
middleName	The middle name of the applicant.	Optional	Optional	Optional	Optional	Optional	Optional	Optional
lastName	The surname of the applicant.	Required	Required	Required	Required	Required	Required	Required
nationality	The nationality of the applicant.	Required	Required	Required	Required	Required	Required	Required
dateOfBirth	The date on which the applicant was born in the YYYY-MM-DD format. Date of birth cannot be a future date. Applicant age cannot be less than 18 yrs.	Required	Required	Required	Required	Required	Required	Required
birthCountry	The country of birth. Note: This field is required if the applicant's position is UBO, TRUSTEE, or PARTNER.	Required \*	Required \*	Required \*	Required \*	Required \*	Required \*	Required \*
professionalDetails	An array of objects that contains the professional details about the applicant.	Required	Required	Required	Required	Required	Required	Required
address	An object that contains the address of the applicant.	Required	Required	Required	Required	Required	Required	Required
contactDetails	An object that contains the contact details about the applicant.	Required	Required	Required	Required	Required	Required	Required
documentDetails	An array of objects that contains the document details of the applicant.	Required	Required	Required	Required	Required	Required	Required
additionalInfo	An object that contains additional information about the applicant.	Required	Required	Required	Required	Required	Required	Required

professionalDetails object

An array of objects within the businessDetails.applicantDetails object that contains the professional details of the applicant.

Property	Description	Association	Sole trader	Trust	Government	Private	Public	LLP
position	The position of the applicant. Use Fetch corporate constants API for a valid set of values.	Required	Required	Required	Required	Required	Required	Required
sharePercentage	The share percentage of the applicant in the company. Note: This field is a required input parameter If the applicant's position is UBO.	Required \*	Required \*	Required \*	Required \*	Required \*	Required \*	Required \*
positionStartDate	The date the applicant started the position at the corporate customer. Position start date cannot be a future date.	Required	Required	Required	Required	Required	Required	Required

address object

An object within the businessDetails.applicantDetails object that contains the applicant's residential address.

Property	Description	Association	Sole trader	Trust	Government	Private	Public	LLP
addressLine1	The first address line of the applicant. The maximum character length is 40.	Required	Required	Required	Required	Required	Required	Required
addressLine2	The second address line of the applicant. The maximum character length is 40.	Optional	Optional	Optional	Optional	Optional	Optional	Optional
city	The city of the applicant. The maximum character length is 20.	Required	Required	Required	Required	Required	Required	Required
state	The state of the applicant. The maximum character length is 30.	Required	Required	Required	Required	Required	Required	Required
country	The country where the applicant resides. Use Fetch corporate constants API for a valid set of values.	Required	Required	Required	Required	Required	Required	Required
postcode	The postal code of the applicant. The minimum length is 3 and the maximum is 10 alphanumeric characters or spaces.	Required	Required	Required	Required	Required	Required	Required

contactDetails object

An object within the businessDetails.applicantDetails object that contains the applicant's contact information.

Property	Description	Association	Sole trader	Trust	Government	Private	Public	LLP
email	The applicant's email address. The maximum character length is 40 and needs to be a valid email address. See Email regex.	Required	Required	Required	Required	Required	Required	Required
countryCode	The country code of the applicant's phone number.	Required	Required	Required	Required	Required	Required	Required
contactNo	The applicant's phone number. The maximum length is 20 numeric characters.	Required	Required	Required	Required	Required	Required	Required

documentDetails object

An array of objects within the businessDetails.applicantDetails object that contains the applicant's document information.

Property	Description	Association	Sole trader	Trust	Government	Private	Public	LLP
documentType	The type of document. Use Fetch corporate constants API for a valid set of values.	Required	Required	Required	Required	Required	Required	Required
documentNumber	The ID number for the given document type.	Required	Required	Required	Required	Required	Required	Required
documentIssuanceCountry	The country that issued the business document. Use Fetch corporate constants API for a valid set of values. Note: This field is required if documentType = PASSPORT.	Required *	Required *	Required*	Required	Required*	Required*	Required*
documentExpiryDate	The date the document expires in the YYYY-MM-DD format. This field is required if documentType = PASSPORT. Expiry date cannot be a past date.	Required *	Required *	Required*	Required	Required*	Required*	Required*
document	The copy of the document. Note: This is required for POWER_OF_ATTORNEY. This field is an array.	Required *	Required *	Required*	Required	Required*	Required*	Required*

document object

An array of objects within the businessDetails.applicantDetails.documentDetails object that contains a copy of the document.

* This object is required for POWER_OF_ATTORNEY.

Property	Description	Association	Sole trader	Trust	Government	Private	Public	LLP
fileName	The name of the file.	Required *	Required *	Required*	Required	Required*	Required*	Required*
fileType	The type of the file. Valid types are application/pdf, image/jpeg, image/jpg, image/png, jpeg, jpg, and png.	Required *	Required *	Required*	Required	Required*	Required*	Required*
document	The copy of the document.	Required *	Required *	Required*	Required	Required*	Required*	Required*

additionalInfo object

An object within the businessDetails.applicantDetails object that contains additional information about the applicant.

Property	Description	Association	Sole trader	Trust	Government	Private	Public	LLP
isPep	This field accepts Yes or No to indicate if the applicant is a politically exposed person.	Required	Required	Required	Required	Required	Required	Required

deviceDetails object

This object contains the information about the customer's device and IP address where the onboarding request originated.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
countryIP	Country of the IP address e.g. US. Use Fetch corporate constants API for valid values.	Required	Required	Required
deviceInfo	Information of the device e.g. Mac OS.	Required	Required	Required
ipAddress	IP address of the device e.g. 45.48.241.198	Required	Required	Required
sessionId	A unique identifier for the session, generated by your application.	Required	Required	Required

expectedAccountUsage object

This object contains the details regarding the expected usage of the account

Property	Description	Association Sole trader Trust	Government Private Public	LLP
debit	Object containing expected account usage of all outward transactions.	Required	Required	Required
credit	Object containing expected account usage of all inward transactions. Applicable if client is enabled for Payins.	Required/\*	Required/\*	Required/\*
intendedUses	Array of intended uses of the account. Use Fetch corporate constants API for valid values.	Required	Required	Required
intendedUsesDescription	Text field description of the intended use of the account of the corporate customer if other is passed in the intendedUses field.	Required\*	Required\*	Required\*

debitobject

This object containing expected account usage of all outward transactions

Property	Description	Association Sole trader Trust	Government Private Public	LLP
monthlyTransactionVolume	Estimated monthly volume of payout for the corporate customer. Use Fetch corporate constants API for a valid set of values.	Required	Required	Required
monthlyTransactions	Estimated count of payout transactions per month for the corporate customer. Use Fetch corporate constants API for a valid set of values.	Required	Required	Required
averageTransactionValue	Estimated average transaction value per payout for the corporate customer. Use Fetch corporate constants API for a valid set of values.	Required	Required	Required
topTransactionCountries	Array of top payout countries. Use Fetch corporate constants API for a valid set of values.	Required	Required	Required
topBeneficiaries	Array of expected primary beneficiaries. Can be specific companies or types of entities (e.g., Ryan Air, Ketan Meheta, Employees of corporate).	Required	Required	Required

creditobject

This object containing expected account usage of all inward transactions. Applicable if the client is enabled for Payins.

note

In case the client is enabled for Payins from Nium, but a particular customer is not enabled for payins, the client is expected to send the minimum bracket within the allowed ranges for monthlyTransactionVolume, monthlyTransactions, averageTransactionValue.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
monthlyTransactionVolume	Estimated monthly volume of payin for the corporate customer. Use Fetch corporate constants API for a valid set of values.	Required\*	Required\*	Required\*
monthlyTransactions	Estimated count of payin transactions per month for the corporate customer. Use Fetch corporate constants API for a valid set of values.	Required\*	Required\*	Required\*
averageTransactionValue	Estimated average transaction value per payin for the corporate customer. Use Fetch corporate constants API for a valid set of values.	Required\*	Required\*	Required\*
topTransactionCountries	Array of top payin countries. Use Fetch corporate constants API for a valid set of values.	Required\*	Required\*	Required\*
topRemitters	Array of expected primary remitters. Can be specific companies or types of entities (e.g., Ryan Air, Ketan Meheta, Employees of corporate).	Required\*	Required\*	Required\*

natureOfBusiness object

Nature of Business object is mandatory for all business types in EU

Property	Description	Required
industryCodes	An array of industry sector codes that apply for the corporate customer's business. Use Fetch corporate constants API for a valid set of values using industrySector category	Yes
industryDescription	Text field explaining the business of the corporate customer in 2-3 sentences. Max Character limit: 300	Yes

riskAssessmentInfo object

An object that contains the following details required to determine a corporate customer's risk profile.

Property	Description	Association Sole trader Trust	Government Private Public	LLP
totalEmployees	The corporate customer's total number of employees. Use Fetch corporate constants API for a valid set of values.	Required	Required	Required
annualTurnover	The corporate customer’s annual turnover.If the company is less than one year old, provide the expected turnover; otherwise, provide the turnover from the previous year. Turnover refers to the total revenue generated by the business. Use Fetch corporate constants API for a valid set of values.	Required	Required	Required
countryOfOperation	Array to accept a list of all the countries the corporate customer operates in. Use Fetch corporate constants API for a valid set of values. This field is an array. Ex: ["IN", "FR", "LT"]	Required	Required	Required

tags object

This object contains the user-defined key-value pairs that the client provides. The maximum number of tags is 15.

Property	Description	Association	Sole trader	Trust	Government	Private	Public	LLP
key	The name of the tag. The maximum character length is 128. Key should be unique.	Optional	Optional	Optional	Optional	Optional	Optional	Optional
value	The value of the tag. The maximum character length is 256.	Optional	Optional	Optional	Optional	Optional	Optional	Optional