HK required parameters
The API fields shown on this page are relevant to Hong Kong (HK) 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 corporate end customer is located and is onboarded. To onboard an HK-based customer, use the HK 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 |
| tags | An object that contains the tags. | No |
clientId | This field contains the Nium client ID about the customer. It's received in the response to the previously executed Onboard Corporate Customer API. 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 API. Note: This field is required to reinitiate the KYB process. | Yes * |
Table entity API fields
The below object table columns apply to the following entity types:
FOREIGN_COMPANY_OFFICEGENERAL_PARTNERSHIPLIMITED_PARTNERSHIPPRIVATE_COMPANYPUBLIC_COMPANYSOLE_TRADER
businessDetails object
businessDetails objectAn object that contains business details about the corporate customer.
| Property | Description | Required |
|---|---|---|
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. | No |
businessName | The name a corporate customer is registered under. | Yes |
businessRegistrationNumber | The business registration number. | Yes |
tradeName | In case the corporate customer is doing business under a different name than their licensed business name. | Yes |
website | The corporate customer's website. | No |
businessType | The legal entity type of the business. Use Fetch corporate constants API for a valid set of values. | Yes |
| legalDetails | An object that contains the legal details. | Yes |
| addresses | An object that contains the registered and business addresses of the corporate customer. | Yes |
| bankAccountDetails | An object that contains the bank account details of the corporate customer. Note: This is required if a client is configured for auto sweep. | Yes * |
| documentDetails | An array of objects that contains the business documents. Note: This is required per HK required documents. | Yes |
| stakeholders | An array of objects that contains the individual and corporate stakeholders about the corporate customer. | Yes |
| applicantDetails | An object that contains the applicant's details. | Yes |
| additionalInfo | An object that contains additional information about the business. | No |
legalDetails object
legalDetails objectAn 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 a future date. | Yes |
registeredCountry | The country where the business is registered. Use Fetch corporate constants API for a valid set of values. | Yes |
addresses object
addresses objectAn object within the businessDetails object that contains registered and business addresses.
| Property | Description | Required |
|---|---|---|
| registeredAddress | An object that contains the address where the business is registered. | Yes |
| 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 | Yes * |
registeredAddress object
registeredAddress objectAn 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 business. | Yes |
addressLine2 | The second address line of the registered business. | No |
city | The city where the corporate customer is registered. | Yes |
state | The state where the corporate customer is registered. | Yes |
country | The country where the corporate customer is registered. Use Fetch corporate constants API for a valid set of values. | Yes |
postcode | The postal code where the corporate customer is registered. Pass 0000 for postcode in HK. | Yes |
businessAddress object
businessAddress objectAn object within the businessDetails.address object that contains the address details about the principal place of business only when the registered address is different.
| Property | Description | Required |
|---|---|---|
addressLine1 | The first address line of the principal place of business if different than the registered business. * Note: This is required if isSameBusinessAddress = No. | Yes * |
addressLine2 | The second address line of the principal place of business if different than the registered business. | No |
city | The city of the principal place of business if different than the registered address. * Note: This is required if isSameBusinessAddress = No. | Yes * |
state | The state of the principal place of business if different than the registered address. * Note: This is required if isSameBusinessAddress = No. | Yes * |
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. * This is required if isSameBusinessAddress = No. | Yes * |
postcode | The postal code where the principal place of business occurs if different than the registered address. * Note: This is required if isSameBusinessAddress = No. Pass 0000 for postcode in HK. | Yes * |
bankAccountDetails object
bankAccountDetails objectAn object within the businessDetails object that contains the bank account details of the corporate customer.
* This is required if a client is configured for auto sweep.
| Property | Description | Required |
|---|---|---|
accountName | The name of the beneficiary for the bank account. This field can contain alphanumeric characters and the following special characters: & . , ( ) _ ' / -. The maximum length is 140 characters. | Yes * |
bankName | The name of the bank. The maximum length is 255 characters. | Yes * |
accountNumber | Account number. This field can contain alphanumeric characters for a maximum length of 35 characters. | Yes * |
currency | The currency in which the auto sweep has to occur. The valid value is SWIFT if the currency is USD or LOCAL if the currency is HKD. | Yes * |
routingType | Routing type of the bank account. The only valid value is SWIFT. | Yes * |
routingValue | Routing value of the bank account. This field can contain alphanumeric characters. The valid length is either eight or ten characters. | Yes * |
documentDetails array
documentDetails arrayAn array of objects within the businessDetails object that contains one or more business 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
document objectAn 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 |
stakeholders object
stakeholders objectAn array of objects within the businessDetails object that contains information about one or many stakeholders.
* 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
stakeholderDetails objectAn object within the stakeholders object that contains the details of an individual stakeholder.
| Property | Description | Required |
|---|---|---|
kycMode | The KYC mode for verifying the individual stakeholder. Valid value is MANUAL_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. | 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 | The professional details of the individual stakeholder. This is an array. | 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. This is an array. | Yes |
professionalDetails object
professionalDetails objectAn array of objects within the businessDetails.stakeholders.stakeholderDetails object that contains the individual stakeholder's professional details.
| Property | Description | Business entity type |
|---|---|---|
position | The position of the individual stakeholder. Use Fetch corporate constants API for a valid set of values. | Yes |
sharePercentage | The share percentage of the individual stakeholder in the company. Note: If the stakeholder’s position is UBO, then the share percentage is a required input parameter. | Yes * |
address object
address objectAn 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. | Yes |
state | The state of the individual stakeholder. | Yes |
country | The country where the individual stakeholder resides. Use Fetch corporate constants API for a valid set of values. | Yes |
postcode | The postal code of the individual stakeholder. Pass 0000 for postcode in HK. | Yes |
contactDetails object
contactDetails objectAn 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 |
documentDetails object
documentDetails objectAn array of objects within the businessDetails.stakeholders.stakeholderDetails object that contains the individual stakeholder's document details.
| Property | Description | Required |
|---|---|---|
documentType | The type of document. Use Fetch corporate constants API for a valid set of values. | Yes |
documentNumber | The ID number for the given document type. | Yes |
documentIssuanceCountry | The country that issued the business document. Use Fetch corporate constants API for a valid set of values. | Yes |
documentExpiryDate | The date the document expires in the YYYY-MM-DD format. This is required if documentType is PASSPORT. Expiry date cannot be a past date. | Yes * |
| document | An array of object that contains the document copy. | Yes |
document object
document objectAn 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 |
businessPartner
businessPartnerAn object within the businessDetails.stakeholders object that contains the business details about the corporate stakeholder.
* This object is required if a corporate stakeholder exists.
| Property | Description | Required |
|---|---|---|
businessName | The registered business name of the corporate stakeholder. | Yes |
businessRegistrationNumber | The business registration number. | Yes |
businessEntityType | The position of the corporate stakeholder in the company. Use Fetch corporate constants API for a valid set of values. | Yes |
sharePercentage | The share percentage of the corporate stakeholder in the company. Note: If the stakeholder’s position is UBO, then the share percentage is a required input parameter. | Yes * |
| legalDetails | An object that contains the legal details of the corporate stakeholder. | Yes |
legalDetails object
legalDetails objectAn 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 Fetch corporate constants API for a valid set of values. | Yes |
applicantDetails object
applicantDetails objectAn 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 valid values are E_DOC_VERIFY and MANUAL_KYC | Yes |
firstName | The first name of the applicant. The maximum length is 40 alphabetic characters or spaces. | Yes |
middleName | The middle name of the applicant. The maximum length is 40 alphabetic characters or spaces. | No |
lastName | The last name or the applicant. The maximum length is 40 alphabetic characters or spaces. | Yes |
nationality | Nationality of the applicant. Use Fetch corporate constants API 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 cannot be less than 18 yrs. | Yes |
| professionalDetails | An array of object that contains the professional details of the applicant. | Yes |
| address | An object that contains the address of the applicant. | Yes |
| contactDetails | An object that contains the contact details of the applicant. | Yes |
| documentDetails | An array of object that contains the document details of the applicant. | Yes |
professionalDetails object
professionalDetails objectAn array of object within the businessDetails.applicantDetails object that contains the professional details about the applicant.
| Property | Description | Required |
|---|---|---|
position | The position of the applicant. Use Fetch corporate constants API for a valid set of values. | Yes |
sharePercentage | The share percentage of the applicant in the company. Note: If the applicant's position is UBO, then the share percentage is a required input parameter. | Yes * |
address object
address objectAn 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 of the applicant. The maximum character length is 20. | Yes |
state | The state of the applicant. The maximum character length is 30. | Yes |
country | The country where the applicant resides. Use Fetch corporate constants API for a valid set of values. | Yes |
postcode | The postal code of the applicant. The minimum length is 3 and the maximum length is 10 alphanumeric characters or spaces. Pass 0000 for postcode in HK. | Yes |
contactDetails object
contactDetails objectAn object within the businessDetails.applicantDetails object that contains the applicant's contact information.
| Property | Description | Required |
|---|---|---|
email | The applicant's email address. The maximum 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 |
documentDetails object
documentDetails objectAn array of objects within the businessDetails.applicantDetails object that contains the applicant's document information.
| Property | Description | Required |
|---|---|---|
documentType | The type of document. Use Fetch corporate constants API for a valid set of values. | Yes |
documentNumber | The ID number for the given document type. | Yes |
documentIssuanceCountry | The country that issued the business document. Use Fetch corporate constants API for a valid set of values. | Yes |
documentExpiryDate | The date the document expires in the YYYY-MM-DD format. This is required if documentType is PASSPORT. Expiry date cannot be a past date. | Yes * |
| document | An object that contains a copy of the document | Yes * |
document object
document objectAn array of objects within the businessDetails.applicantDetails.documentDetails object that contains the document copy.
* This is required for MANUAL_KYC or if documentType is LOA.
| 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 * |
additionalInfo object
additionalInfo objectAn object within the businessDetails object that contains additional information about the business.
| Property | Description | Required |
|---|---|---|
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: This is required if Yes; it's optional if No. | Yes * |
riskAssessmentInfo object
riskAssessmentInfo objectAn object that contains the following details which are required to determine a corporate customer's risk profile.
| Property | Description | Required |
|---|---|---|
totalEmployees | The corporate customer's total number of employees. Use Fetch corporate constants API for a valid set of values. | Yes |
annualTurnover | The corporate customer's amount of annual turnover. Use Fetch corporate constants API for a valid set of values. | Yes |
industrySector | The corporate customer's industry sector. Use Fetch corporate constants API for a valid set of values. | Yes |
countryOfOperation | An array of countries the corporate customer operates in. Use Fetch corporate constants API for a valid set of values. | Yes |
transactionCountries | An array of countries where the transactions occur. Use Fetch corporate constants API for a valid set of values. | Yes |
intendedUseOfAccount | The customer's intended use of the account. Use Fetch corporate constants API for a valid set of values. | Yes |
deviceDetails object
deviceDetails objectThis object contains the information about the customer's device and IP address where the onboarding request originated.
| Property | Description | Required |
|---|---|---|
countryIP | Country of the IP address e.g. US. Use Fetch corporate constants API for valid values. | Yes |
deviceInfo | Information of the device e.g. Mac OS. | Yes |
ipAddress | IP address of the device e.g. 45.48.241.198 | Yes |
sessionId | A unique identifier for the session, generated by your application. | Yes |
tags object
tags objectAn optional object that contains the user-defined key-value pairs that the client provides. The maximum number of tags is 15.
| Property | Description | Required |
|---|---|---|
key | The name of the tag. The maximum character length is 128. Key should be unique. | No |
value | The value of the tag. The maximum character length is 256. | No |
Updated 6 months ago