Required Parameters

The API fields shown on this page are relevant to the United Kingdom 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 regulatory region where the corporate customer is being onboarded. Use UK to onboard a customer based in the United Kingdom.	Yes
businessDetails	Details about the business, including information about the applicant and stakeholders.	Yes
riskAssessmentInfo	Business profile details, such as total employees and annual turnover.	Yes
deviceDetails	Information about the device and IP address used to submit the onboarding request.	Yes
expectedAccountUsage	Details about how the customer intends to use the account.	Yes
natureOfBusiness	Information about the company’s industry and type of business activity.	Yes
tags	Optional metadata tags you can use to identify customer accounts.	No
customerHashId	The unique customer identifier generated when creating the customer record. Returned in the response to the Onboard Corporate Customer request. Required to reinitiate the KYB process.

note

Only customers registered in GB, CH, MC are eligible to be onboarded under UK region. Please contact your account manager, in case you need to onboard customers registered outside of these countries. See Regulatory region for details.

Table entity API fields

Table entity API fields

The below object table columns apply to the following entity types:

• ASSOCIATION
• GOVERNMENT_ENTITY
• LIMITED_LIABILITY_PARTNERSHIP
• PRIVATE_COMPANY
• PUBLIC_COMPANY
• SOLE_TRADER
• TRUST
• UNINCORP_PARTNERSHIP
• OTHERS

businessDetails object

An object that contains business details about the corporate customer.

Property	Description	Required
referenceId	The universally unique identifier (UUID) that Nium uses to identify the businessDetails entity. If not provided, Nium generates one. Used when responding to an RFI or uploading documents for the business entity.	No
businessName	The registered legal name of the business.	Yes
businessRegistrationNumber	The official registration number issued to the business.	Yes
tradeName	The name the business operates under. If unavailable, set tradeName to the same value as businessName.	Yes
website	The business’s website. If unavailable, provide a social media profile (for example, Instagram or Facebook). If neither is available, upload a document with documentType PROOF_OF_BUSINESS.	No
businessType	The legal entity type of the business, such as Private or Public Company. Use the Fetch corporate constants API with category: businessType.	Yes
legalDetails	Legal and registration details for the business.	Yes
addresses	The registered and operating business addresses.	Yes
documentDetails	An array of business documents. Required for UK required documents.	Yes*
stakeholders	Details about the business’s stakeholders, such as directors or ultimate beneficial owners (UBOs).	Yes
applicantDetails	Information about the applicant associated with the business.	Yes
additionalInfo	Optional supplementary information related to the application.	No

legalDetails object

An object within the businessDetails object that contains legal details.

Property	Description	Required
registeredDate	The date the business was registered entered in the YYYY-MM-DD format. Registered date cannot be future date.	Yes
registeredCountry	The country where the business is registered. Use Fetch corporate constants request with category set to countryName.	Yes

addresses object

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

Property	Description	Required
registeredAddress	The address where the business is registered.	Yes
businessAddress	The address where the business is mainly conducted, if different than the registered address. Not required if isSameBusinessAddress is Yes and passed under businessDetails.additionalInfo.	Yes

registeredAddress object

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

Property	Description	Required
addressLine1	The first address line of the registered address.	Yes
addressLine2	The second address line of the registered address.	No
city	The city or suburb of the registered address.	No
state	The state or province of the registered address.	No
country	The country where the corporate customer is registered. Use Fetch corporate constants API with category=countryName.	Yes
postcode	The postal code where the corporate customer is registered.	Yes

businessAddress object

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

Optional if isSameBusinessAddress is Yes under businessDetails.additionalInfo. :::

Property	Description	Required
addressLine1	The first address line of the business address.	Yes
addressLine2	The second address line of the business address.	No
city	The city or suburb of the business address.	No
state	The state or province of the business address.	No
country	The country of the business address. Use the Fetch corporate constants request with category=countryName.	Yes
postcode	The postal code of the business address.	Yes

documentDetails array

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

* This object is required if either of the following are true:

• Manual KYB is used.
  • searchId is nor passed.
• eKYB is used and businessDetails.businessType is one of the following:
  • LIMITED_LIABILITY_PARTNERSHIP
  • TRUST
  • UNINCORP_PARTNERSHIP

For a complete list of required documents, see UK Required Documents.

Property	Description	Required
documentType	The type of business document. Use Fetch corporate constants API for a valid set of values.	Yes
document	An array of object that contains a copy of the document.	Yes

document object

An array of objects within the businessDetails.documentDetails object.

Property	Description	Required
fileName	The name of the file.	Yes
fileType	The type of the file. Valid types are application/pdf, image/jpeg, image/jpg, image/png, jpeg, jpg, and png.	Yes
document	The file as a base64 encoded string.	Yes

additionalInfo object

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

Property	Description	Required
isSameBusinessAddress	Indicates whether the principal place of business is the same as the registered business address. Accepts Yes or No. If set to Yes, the business address can be skipped.	No
searchId	Used for eKYB. Returned in the response from the Exhaustive Corporate Details using Business ID request. The required business documents depend on this value.	No

stakeholders object

An array of objects within the businessDetails object that contains information about one or many stakeholders including Directors and UBOs.

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

Property	Description	Required
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.	No
stakeholderDetails	An object that contains the details of the individual stakeholder.	Yes
businessPartner	An object that contains the details of the corporate stakeholder. Required if a corporate stakeholder exists.	Yes

stakeholderDetails object

Each item in the stakeholders object represents an individual stakeholder (natural person).

Include all Signatories, Directors, Ultimate Beneficial Owners (UBOs), Trustees, Settlors, and Partners listed in the Business Registration Document, Register of Directors, or Register of Shareholders for all business types.

To add positions:

• Directors: Include all active management directors as stakeholders. Board members who do not participate in daily operations are not required.

• Ultimate Beneficial Owners (UBOs): Add all individuals who own more than 25% of the business (directly or indirectly).

  • For sole traders, the business owner is considered the UBO.
  • For high-risk businesses, Nium may request via RFI that all individuals owning more than 10% of shares be declared as UBOs.

• Control Person:
  If no individual owns 25% or more of the business, identify and submit a Control Person along with the Control Person Declaration.
  See UK Required Documents for details.

• Signatory or Representative:
  Add individuals authorized to conduct transactions or manage user access.

  • The applicant is considered a Representative by default and must be included.
  • You can add other users as Representatives in the application or later by emailing usermanagement@nium.com. Each Representative must complete KYC as instructed.

• Other Roles:
  Include other applicable roles—such as Partner, Trustee, or Settlor—according to position mapping requirements.

Property	Description	Required
kycMode	The KYC mode for verifying the individual stakeholder. Valid values are E_KYC , E_DOC_VERIFY, MANUAL_KYC. The kycMode is required only when the position of the individual stakeholder is UBO, TRUSTEE, PARTNER, or MEMBER or REPRESENTATIVE or SIGNATORY and can be ignored for other positions. For details, see Stakeholder KYC	Yes
firstName	The first name of the individual stakeholder.	Yes
middleName	The middle name of the individual stakeholder.	No
lastName	The last name of the individual stakeholder.	Yes
nationality	The nationality of the individual stakeholder. Use Fetch corporate constants API with category=countryName.	Yes
dateOfBirth	The date the individual stakeholder was born in the YYYY-MM-DD format. Date of birth cannot be a future date.	Yes
professionalDetails	An array of objects to accept the positions held by the stakeholder in the business of the corporate customer and details related to the positions held.	Yes
address	An object that contains the residential address of the individual stakeholder.	Yes
contactDetails	An object that contains the contact details of the individual stakeholder.	No
documentDetails	An object that contains the document details of the individual stakeholder. Note: This is required if kycMode = MANUAL_KYC.	Yes *
additionalInfo	An object that contains additional information required about the individual stakeholder such as isPEP.	Yes

professionalDetails object

An array of objects within businessDetails.stakeholders.stakeholderDetails that defines each stakeholder’s professional details.

A stakeholder can hold multiple positions (for example, Director and UBO). Select all applicable positions for each individual.

Property	Description	Required
position	The position of the individual stakeholder such as UBO, DIRECTOR, REPRESENATTIVE, SIGANTORY . Use the Fetch corporate constants request with categoryset to position for a valid set of values.	Yes
sharePercentage	The share percentage of the individual stakeholder in the company. Required if stakeholder’s position contains UBO or SHAREHOLDER. Else ignore. Sharepercentage should be a number between 0 and 100. Eg. 23.4	Yes

stakeholderDetails.address object

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

Property	Description	Required
addressLine1	The first address line of the individual stakeholder.	Yes
addressLine2	The second address line of the individual stakeholder.	No
city	The city or suburb of the individual stakeholder.	No
state	The state or province of the individual stakeholder.	No
country	The country where the individual stakeholder resides. Use Fetch corporate constants API with category=countryName.	Yes
postcode	The postal code of the individual stakeholder.	Yes

contactDetails object

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

Property	Description	Required
email	The individual stakeholder's email address.	No
contactNo	The contact phone number of the individual stakeholder.	No

stakeholderDetails.documentDetails object

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

Required for MANUAL_KYC. See UK required documents for stakeholders for more information.

Property	Description	Required
documentType	The type of document. Use the Fetch corporate constants request with categoryset to documentType.	Yes *
documentNumber	The ID number for the given document type.	Yes *
documentIssuanceCountry	The country that issued the business document. This field is required if documentType = PASSPORT or DRIVER_LICENSE or NATIONAL_ID. Use Fetch corporate constants API with category=countryName	Yes *
documentExpiryDate	The date the document expires in the YYYY-MM-DD format. This is required if documentType is PASSPORT or DRIVER_LICENSE.Expiry date cannot be a past date.	Yes *
document	An object that contains the document copy.	Yes *

documentDetails.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	Required
fileName	The name of the file.	Yes
fileType	The file type. Valid types are application/pdf, image/jpeg, image/jpg, image/png, jpeg, jpg, and png.	Yes
document	The document saved as a base64 encoded string.	Yes

stakeholderDetails.additionalInfo object

An object under businessDetails.stakeholders.stakeholderDetails that provides additional information about an individual stakeholder, such as if they are a politically exposed person (PEP).

Property	Description	Required
isPep	Indicates if the stakeholder is a politically exposed person. Accepts Yes or No. If set to Yes, include a SOURCE_OF_WEALTH document; otherwise, it may be requested later via a RFI.	Yes

A Politically Exposed Person (PEP) is someone who currently holds or has recently held a prominent public position and may therefore present a higher risk of involvement in bribery, corruption, or money laundering.

businessPartner

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

• If the customer is a multi-layered company where another corporate entity owns more than 25% of shares (directly or indirectly), declare all such corporate stakeholders in the application.
• See Multi-layered Ownership Structure for guidance on identifying multi-layered companies.
• Submit the corporate or ownership structure document to verify ownership under businessDetails.documentType set to CORPORATE_STRUCTURE.

For more information, see UK Required Documents.

Property	Description	Required
businessName	The registered business name of the corporate stakeholder.	Yes
businessRegistrationNumber	The official registration number of the corporate stakeholder.	Yes
businessEntityType	The primary role of the corporate stakeholder within the company. Use the Fetch Corporate Constants request with category set to position for valid values. Corporate stakeholders can typically hold positions such as UBO, Shareholder, Partner, or Trustee. In some cases, a corporate stakeholder may also act as a Director.	Yes
sharePercentage	The ownership percentage of the corporate stakeholder in the company. Note: Required if the stakeholder’s position is UBO or Shareholder. Otherwise, omit. The value must be a number between 0 and 100 (for example, 23.4).	Yes
legalDetails	The registration and legal details of the corporate stakeholder.	Yes

businessPartner.legalDetails object

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

Property	Description	Required
registeredCountry	The country where the corporate stakeholder is registered. Use the Fetch Corporate Constants request category set to countryName.	Yes

applicantDetails object

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

Property	Description	Required
referenceId	The universally unique identifier (UUID) associated with the applicant and applicant object. If the UUID isn't provided, Nium generates one. The UUID can be used to respond to an RFI or to upload required documents.	No
kycMode	The KYC mode for verifying the identity of the applicant. The only valid value is E_DOC_VERIFY.	Yes
firstName	The first name of the applicant. The maximum length is 40 characters or spaces.	Yes
middleName	The middle name of the applicant. The maximum length is 40 characters or spaces.	No
lastName	The last name or the applicant. The maximum length is 40 characters or spaces.	Yes
nationality	Nationality of the applicant. Use the Fetch corporate constants request with category set to countryName for valid values.	Yes
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 should be less than 18 yrs.	Yes
professionalDetails	An array of object that contains the professional details of the applicant.	Yes
address	The residential address of the applicant.	Yes
contactDetails	The contact details of the applicant.	Yes
documentDetails	The document details of the applicant. Required only for POWER_OF_ATTORNEY or SOURCE_OF_WEALTH.	Yes *
additionalInfo	Additional applicant information, such as isPEP.	Yes

professionalDetails object

Describes the roles held by the applicant in the corporate customer’s business.

Property	Description	Required
position	The position of the applicant. Use the Fetch corporate constants request with category set to countryName for valid values. An applicant is a REPRESENTATIVE by default. Additionally, all applicable positions like UBO or DIRECTOR should be added.	Yes
sharePercentage	The share percentage of the applicant in the company. If the applicant's position is UBO or SHAREHOLDER, then the share percentage is a required input parameter. Else ignore. sharePercentage should be a number between 0 and 100. Eg. 23.4	Yes

applicantDetails.address object

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

Property	Description	Required
addressLine1	The first address line of the applicant. The maximum character length is 40.	Yes
addressLine2	The second address line of the applicant. The maximum character length is 40.	No
city	The city or suburb of the applicant. The maximum character length is 20.	Yes
state	The state or province of the applicant. The maximum character length is 30.	No
country	The country of the applicant address. Use the Fetch corporate constants request with category set to countryName for valid values.	Yes
postcode	The postal code of the applicant. The minimum length is 3 and the maximum length is 10 alphanumeric characters or spaces. For UK postcodes, use the SW4 6EH format.	Yes

contactDetails object

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

Property	Description	Required
email	The applicant's email address. The maximum character length is 40 and needs to be a valid email address. See Email regex.	Yes
countryCode.	The country code of the applicant's phone number.	Yes
contactNo	The applicant's phone number. The maximum length is 20 numeric characters.	Yes

businessDetails.applicantDetails.documentDetails object

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

• If positions does not include DIRECTOR / UBO / PARTNER / TRUSTEE/ MEMBER then POWER_OF_ATTORNEY is required.
• If isPEP is Yes then SOURCE_OF_WEALTH is required.

Property	Description	Required
documentType	The type of document. Use the Fetch corporate constants request for a valid set of values.	Yes *
document	An array of objects that contains a copy of the document. Required for POWER_OF_ATTORNEY or SOURCE_OF_WEALTH. See UK Required Documents for required fields.	Yes

documentDetails.document object

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

• Required for POWER_OF_ATTORNEY or SOURCE_OF_WEALTH.

See UK Required Documents for the valid set of required fields.

Property	Description	Required
fileName	The name of the file.	Yes
fileType	The file type. Valid types are application/pdf, image/jpeg, image/jpg, image/png, jpeg, jpg, and png.	Yes
document	The document saved as a base64 encoded string.	Yes

applicantDetails.additionalInfo object

An object within businessDetails.applicantDetails that provides additional information about the applicant, such as whether they are a politically exposed person (PEP).

Property	Description	Required
isPep	Indicates whether the applicant is a politically exposed person. Accepts Yes or No. If set to Yes, include a SOURCE_OF_WEALTH document; otherwise, it may be requested later via RFI.	Yes

A Politically Exposed Person (PEP) is someone who currently holds or has recently held a prominent public position and may therefore present a higher risk of involvement in bribery, corruption, or money laundering.

expectedAccountUsage object

Contains information about how the corporate customer expects to use their account.

Property	Description	Required
debit	Expected usage for all outward (debit) transactions.	Yes
credit	Expected usage for all inward (credit) transactions.	Yes
intendedUses	Array of intended account uses. Include all applicable values. Use Fetch Corporate Constants with category = intendedUses for valid options.	Yes
intendedUsesDescription	Description of the intended account use if other is selected in intendedUses. Minimum 20 characters.	Yes*

debit object

Describes the expected usage for all outward (debit) transactions.

Property	Description	Required
monthlyTransactionVolume	Estimated total monthly payout volume, converted to GBP. Use Fetch Corporate Constants with category set to monthlyTransactionVolume for valid options.	Yes
monthlyTransactions	Estimated number of monthly payout transactions. Use Fetch Corporate Constants with category set to monthlyTransactions for valid options.	Yes
averageTransactionValue	Estimated average payout transaction value, converted to GBP. Use Fetch Corporate Constants with category set to averageTransactionValue for valid options.	Yes
topTransactionCountries	Array of top payout destination countries. Use Fetch Corporate Constants with category set to countryName for valid options.	Yes

credit object

Describes the expected usage for all inward (credit) transactions.

• If the customer is not enabled for pay-ins, provide the lowest valid bracket for monthlyTransactionVolume, monthlyTransactions, and averageTransactionValue.
• This object is not applicable to Payroll clients or clients who have disabled third-party funding.

Property	Description	Required
monthlyTransactionVolume	Estimated total monthly pay-in volume, converted to GBP. Use Fetch Corporate Constants with category set to monthlyTransactionVolume for valid options.	Yes
monthlyTransactions	Estimated number of monthly pay-in transactions. Use Fetch Corporate Constants with category set to monthlyTransactions for valid options.	Yes
averageTransactionValue	Estimated average pay-in transaction value, converted to EUR. Use Fetch Corporate Constants with category set to averageTransactionValue for valid options.	Yes
topTransactionCountries	Array of top pay-in source countries. Use Fetch Corporate Constants with category set to countryName for valid options.	Yes

natureOfBusiness object

Contains information about the business’s nature and industry.

• If the industrySector includes any restricted or prohibited industries, Nium may request additional documentation, which can affect approval timelines.
  See Prohibited and Restricted Business Categories for more details.

Property	Description	Required
industryCodes	Array of industry sector codes applicable to the business. Include all relevant values. Use Fetch Corporate Constants with category set to industrySector for valid options.	Yes
industryDescription	Brief description (2–3 sentences) of the business. Maximum 300 characters; minimum 20 characters.	No

riskAssessmentInfo object

Contains information about the business’s operational and financial profile.

Property	Description	Required
totalEmployees	Total number of employees. Use Fetch Corporate Constants with category set to totalEmployees for valid options.	Yes
annualTurnover	Annual turnover. If the business is less than one year old, provide the expected turnover; otherwise, use the previous year’s turnover. “Turnover” refers to total annual revenue. Use Fetch Corporate Constants with category set to annualTurnover for valid options.	Yes
countryOfOperation	Array of countries where the business operates or maintains a presence. Include all countries where the company has offices, factories, or operations. Example: ["IN", "FR", "LT"]. Use Fetch Corporate Constants for valid country codes.	Yes
travelRestrictedCountry	Indicates whether the customer (for example, an Online Travel Agency) facilitates travel to any travel-restricted countries. Accepts Yes or No. Applicable when JPMC Virtual Account is enabled.	Yes*
restrictedCountries	Array of restricted countries to which the OTA facilitates travel. Required if travelRestrictedCountry = Yes. Use Fetch Corporate Constants for valid country codes.	Yes*
ofacLicencePresent	Indicates whether the OTA holds an OFAC license. Accepts Yes or No. Required if travelRestrictedCountry = Yes.	Yes*

deviceDetails object

Contains information about the customer’s device and IP address used during onboarding.

Property	Description	Required
countryIP	Country associated with the device’s IP address (for example, US). Use Fetch Corporate Constants with category set to countryName for valid country codes.	Yes
deviceInfo	Device information (for example, macOS).	Yes
ipAddress	Device IP address (for example, 45.48.241.198).	Yes
sessionId	Unique session identifier generated by the client application.	Yes

tags object

An optional object containing up to 15 user-defined key-value pairs provided by the client.

Property	Description	Required
key	Name of the tag. Maximum 128 characters. Each key must be unique.	No
value	Value of the tag. Maximum 256 characters.	No