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

PropertyDescriptionRequired
regionThe 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
businessDetailsAn object that contains business details about the corporate customer.Yes
riskAssessmentInfoAn object that contains the risk assessment information.Yes
deviceDetailsAn object that contains information about the customer's device and IP address.Yes
tagsAn object that contains the tags.No
clientIdThis 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 *
customerHashIdThis 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_OFFICE
  • GENERAL_PARTNERSHIP
  • LIMITED_PARTNERSHIP
  • PRIVATE_COMPANY
  • PUBLIC_COMPANY
  • SOLE_TRADER

businessDetails object

An object that contains business details about the corporate customer.

PropertyDescriptionRequired
referenceIdThe 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
businessNameThe name a corporate customer is registered under.Yes
businessRegistrationNumberThe business registration number.Yes
tradeNameIn case the corporate customer is doing business under a different name than their licensed business name.Yes
websiteThe corporate customer's website.No
businessTypeThe legal entity type of the business. Use Fetch corporate constants API for a valid set of values.Yes
legalDetailsAn object that contains the legal details.Yes
addressesAn object that contains the registered and business addresses of the corporate customer.Yes
bankAccountDetailsAn object that contains the bank account details of the corporate customer.
Note: This is required if a client is configured for auto sweep.
Yes *
documentDetailsAn array of objects that contains the business documents.
Note: This is required per HK required documents.
Yes
stakeholdersAn array of objects that contains the individual and corporate stakeholders about the corporate customer.Yes
applicantDetailsAn object that contains the applicant's details.Yes
additionalInfoAn object that contains additional information about the business.No

legalDetails object

An object within the businessDetails object that contains legal details.

PropertyDescriptionRequired
registeredDateThe date the business was registered entered in the YYYY-MM-DD format. Registered date cannot be a future date.Yes
registeredCountryThe country where the business is registered. Use Fetch corporate constants API for a valid set of values.Yes

addresses object

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

PropertyDescriptionRequired
registeredAddressAn object that contains the address where the business is registered.Yes
businessAddressAn 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

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

PropertyDescriptionRequired
addressLine1The first address line of the registered business.Yes
addressLine2The second address line of the registered business.No
cityThe city where the corporate customer is registered.Yes
stateThe state where the corporate customer is registered.Yes
countryThe country where the corporate customer is registered. Use Fetch corporate constants API for a valid set of values.Yes
postcodeThe postal code where the corporate customer is registered. Pass 0000 for postcode in HK.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.

PropertyDescriptionRequired
addressLine1The first address line of the principal place of business if different than the registered business.
* Note: This is required if isSameBusinessAddress = No.
Yes *
addressLine2The second address line of the principal place of business if different than the registered business.No
cityThe city of the principal place of business if different than the registered address.
* Note: This is required if isSameBusinessAddress = No.
Yes *
stateThe state of the principal place of business if different than the registered address.
* Note: This is required if isSameBusinessAddress = No.
Yes *
countryThe 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 *
postcodeThe 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

An 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.

PropertyDescriptionRequired
accountNameThe 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 *
bankNameThe name of the bank. The maximum length is 255 characters.Yes *
accountNumberAccount number. This field can contain alphanumeric characters for a maximum length of 35 characters.Yes *
currencyThe 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 *
routingTypeRouting type of the bank account. The only valid value is SWIFT.Yes *
routingValueRouting value of the bank account. This field can contain alphanumeric characters. The valid length is either eight or ten characters.Yes *

documentDetails array

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

PropertyDescriptionRequired
documentTypeThe type of business document. Use Fetch corporate constants API for a valid set of values.Yes
documentAn array of object that contains a copy of the document.Yes

document object

An array of objects within the businessDetails.documentDetails object.

PropertyDescriptionRequired
fileNameThe name of the file.Yes
fileTypeThe type of the file. Valid types are application/pdf, image/jpeg, image/jpg, image/png, jpeg, jpg, and png.Yes
documentThe file as a base64 encoded string.Yes

stakeholders object

An 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.

PropertyDescriptionRequired
referenceIdThe 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
stakeholderDetailsAn object that contains the details of the individual stakeholder.Yes *
businessPartnerAn object that contains the details of the corporate stakeholder. Required if a corporate stakeholder exists.Yes *

stakeholderDetails object

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

PropertyDescriptionRequired
kycModeThe KYC mode for verifying the individual stakeholder. Valid value is MANUAL_KYC.Yes
firstNameThe first name of the individual stakeholder.Yes
middleNameThe middle name of the individual stakeholder.No
lastNameThe last name of the individual stakeholder.Yes
nationalityThe nationality of the individual stakeholder.Yes
dateOfBirthThe date the individual stakeholder was born in the YYYY-MM-DD format. Date of birth cannot be a future date.Yes
professionalDetailsThe professional details of the individual stakeholder. This is an array.Yes
addressAn object that contains the residential address of the individual stakeholder.Yes
contactDetailsAn object that contains the contact details of the individual stakeholder.No
documentDetailsAn object that contains the document details of the individual stakeholder. This is an array.Yes

professionalDetails object

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

PropertyDescriptionBusiness entity type
positionThe position of the individual stakeholder. Use Fetch corporate constants API for a valid set of values.Yes
sharePercentageThe 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

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

PropertyDescriptionRequired
addressLine1The first address line of the individual stakeholder.Yes
addressLine2The second address line of the individual stakeholder.No
cityThe city or suburb of the individual stakeholder.Yes
stateThe state of the individual stakeholder.Yes
countryThe country where the individual stakeholder resides. Use Fetch corporate constants API for a valid set of values.Yes
postcodeThe postal code of the individual stakeholder. Pass 0000 for postcode in HK.Yes

contactDetails object

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

PropertyDescriptionRequired
emailThe individual stakeholder's email address.No
contactNoThe contact phone number of the individual stakeholder.No

documentDetails object

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

PropertyDescriptionRequired
documentTypeThe type of document. Use Fetch corporate constants API for a valid set of values.Yes
documentNumberThe ID number for the given document type.Yes
documentIssuanceCountryThe country that issued the business document. Use Fetch corporate constants API for a valid set of values.Yes
documentExpiryDateThe 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 *
documentAn array of object that contains the document copy.Yes

document object

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

PropertyDescriptionRequired
fileNameThe name of the file.Yes
fileTypeThe file type. Valid types are application/pdf, image/jpeg, image/jpg, image/png, jpeg, jpg, and png.Yes
documentThe document saved as a base64 encoded string.Yes

businessPartner

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

* This object is required if a corporate stakeholder exists.

PropertyDescriptionRequired
businessNameThe registered business name of the corporate stakeholder.Yes
businessRegistrationNumberThe business registration number.Yes
businessEntityTypeThe position of the corporate stakeholder in the company. Use Fetch corporate constants API for a valid set of values.Yes
sharePercentageThe 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 *
legalDetailsAn object that contains the legal details of the corporate stakeholder.Yes

legalDetails object

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

PropertyDescriptionRequired
registeredCountryThe country where the corporate stakeholder is registered. Use Fetch corporate constants API for a valid set of values.Yes

applicantDetails object

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

PropertyDescriptionRequired
referenceIdThe 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
kycModeThe KYC mode for verifying the identity of the applicant. The valid values are E_DOC_VERIFY and MANUAL_KYCYes
firstNameThe first name of the applicant. The maximum length is 40 alphabetic characters or spaces.Yes
middleNameThe middle name of the applicant. The maximum length is 40 alphabetic characters or spaces.No
lastNameThe last name or the applicant. The maximum length is 40 alphabetic characters or spaces.Yes
nationalityNationality of the applicant. Use Fetch corporate constants API for valid values.Yes
dateOfBirthThe 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
professionalDetailsAn array of object that contains the professional details of the applicant.Yes
addressAn object that contains the address of the applicant.Yes
contactDetailsAn object that contains the contact details of the applicant.Yes
documentDetailsAn array of object that contains the document details of the applicant.Yes

professionalDetails object

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

PropertyDescriptionRequired
positionThe position of the applicant. Use Fetch corporate constants API for a valid set of values.Yes
sharePercentageThe 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

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

PropertyDescriptionRequired
addressLine1The first address line of the applicant. The maximum character length is 40.Yes
addressLine2The second address line of the applicant. The maximum character length is 40.No
cityThe city of the applicant. The maximum character length is 20.Yes
stateThe state of the applicant. The maximum character length is 30.Yes
countryThe country where the applicant resides. Use Fetch corporate constants API for a valid set of values.Yes
postcodeThe 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

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

PropertyDescriptionRequired
emailThe applicant's email address. The maximum length is 40 and needs to be a valid email address. See Email regexYes
countryCode.The country code of the applicant's phone number.Yes
contactNoThe applicant's phone number. The maximum length is 20 numeric characters.Yes

documentDetails object

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

PropertyDescriptionRequired
documentTypeThe type of document. Use Fetch corporate constants API for a valid set of values.Yes
documentNumberThe ID number for the given document type.Yes
documentIssuanceCountryThe country that issued the business document. Use Fetch corporate constants API for a valid set of values.Yes
documentExpiryDateThe 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 *
documentAn object that contains a copy of the documentYes *

document object

An 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.

PropertyDescriptionRequired
fileNameThe name of the file.Yes *
fileTypeThe file type. Valid types are application/pdf, image/jpeg, image/jpg, image/png, jpeg, jpg, and png.Yes *
documentThe document saved as a base64 encoded string.Yes *

additionalInfo object

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

PropertyDescriptionRequired
isSameBusinessAddressThis 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

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

PropertyDescriptionRequired
totalEmployeesThe corporate customer's total number of employees. Use Fetch corporate constants API for a valid set of values.Yes
annualTurnoverThe corporate customer's amount of annual turnover. Use Fetch corporate constants API for a valid set of values.Yes
industrySectorThe corporate customer's industry sector. Use Fetch corporate constants API for a valid set of values.Yes
countryOfOperationAn array of countries the corporate customer operates in. Use Fetch corporate constants API for a valid set of values.Yes
transactionCountriesAn array of countries where the transactions occur. Use Fetch corporate constants API for a valid set of values.Yes
intendedUseOfAccountThe customer's intended use of the account. Use Fetch corporate constants API for a valid set of values.Yes

deviceDetails object

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

PropertyDescriptionRequired
countryIPCountry of the IP address e.g. US. Use Fetch corporate constants API for valid values.Yes
deviceInfoInformation of the device e.g. Mac OS.Yes
ipAddressIP address of the device e.g. 45.48.241.198Yes
sessionIdA unique identifier for the session, generated by your application.Yes

tags object

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

PropertyDescriptionRequired
keyThe name of the tag. The maximum character length is 128. Key should be unique.No
valueThe value of the tag. The maximum character length is 256.No