CA required parameters

The API fields shown on this page are relevant to Canada 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 a Canada -based customer, use the `CA` value.	Yes
businessDetails	An object that accepts 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 accepts the Nium client ID of 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 accepts the unique customer identifier generated at the time of 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 header API fields

The below table headers refer to the businessType fields:

Public	Trust	Other entity
`PUBLIC_COMPANY`	`TRUST` `WIDELY_HELD_TRUST`	`PRIVATE_COMPANY` `CHARITY` `PARTNERSHIP` `SOLE_TRADER`

`businessDetails` object

An object that accepts business details about the corporate customer.

Property	Description	Public	Trust	Other entity
`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. For US customers, pass only the employer identification number (TIN). This field accepts only 9 digits.	Required	Required	Required
`tradeName`	Another name that the corporate customer uses to do business under, which is different than their licensed business name.	Optional	Optional	Optional
`website`	A company's set of related web pages located under a single domain name.	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
`description`	A brief overview of the business. Max character length is 65535.	Required	Required	Required
`stockSymbol`	The publicly traded stock or ticker symbol of the business.	Optional	N/A	N/A
taxDetails	An array of objects for Tax identification number of the entity	Required	Required	Required
legalDetails	An object that contains the legal details.	Required	Required	Required
addresses	An object that contains the registered address and the business address of the corporate customer.	Required	Required	Required
documentDetails	An array of object that contains the business documents. Note: This object is required for `MANUAL_KYB`.	Required *	Required *	Required *
stakeholders	An array of object 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

taxDetails array

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

Property	Description	Required
`country`	This field will be CA	Required
`taxNumber`	The tax ID number of the business as found in tax filings.	Required

`legalDetails` object

An object within the businessDetails object that accepts legal details.

Property	Description	Required
`registeredDate`	The date the business is registered entered in the `YYYY-MM-DD` format. Registered date cannot be future date.	Required \| Optional for Charity
`registeredCountry`	The country where the business is registered. Use Fetch corporate constants API for a valid set of values.	Required \| Optional for Charity
`listedExchange`	The exchange where the business is publicly listed. Use Fetch corporate constants API for a valid set of values.	Required for Public Company

`addresses` object

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

Property	Description	Required
registeredAddress	An object that contains the address where the business is registered.	Required
businessAddress	An object that contains the address where the business correspondence can be conducted, if different than the registered address. This will also be the communication address. Note: This is required if `isSameBusinessAddress=No`	Required *

`registeredAddress` object

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

Property	Description	Required
`addressLine1`	The first address line of the registered business.	Required
`addressLine2`	The second address line of the registered business.	Optional
`city`	The city where the corporate customer is registered.	Required
`state`	The state where the corporate customer is registered. Use Fetch corporate constants API for a valid set of values.	Required
`country`	The country where the corporate customer is registered. Use Fetch corporate constants API for a valid set of values.	Required
`postcode`	The postal code where the corporate customer is registered. `postcode` is alphanumeric and follows the format 'A1A 1A1' e.g. , K1A 0T6	Required

`businessAddress` object

An object within the businessDetails.address object that accepts the address details where the business correspondence can be conducted, if different than the registered address

* This object is required if isSameBusinessAddress = No.

Property	Description	Required
`addressLine1`	The first address line of the principal place of business if different than the registered business.	Required *
`addressLine2`	The second address line of the principal place of business if different than the registered business.	Optional
`city`	The city of the principal place of business if different than the registered address.	Required *
`state`	The state of the principal place of business if different than the registered address. Use Fetch corporate constants API for a valid set of values.	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 *
`postcode`	The postal code where the principal place of business occurs if different than the registered address. `postcode` is alphanumeric and follows the format 'A1A 1A1' e.g. , K1A 0T6	Required *

`documentDetails` array

An array of objects within the businessDetails object that accepts 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.	Required *
document	An object that contains a document copy.	Required *

`document` array

An array of objects within the businessDetails.documentDetails object.

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

`stakeholders` object

An array of objects within the businessDetails object that accepts one or many stakeholders' information.

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

Property	Description	Required
`referenceId`	The 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
stakeholderDetails	An object that contains the details about the individual stakeholder.	Required
businessPartner	An object that contains the details of the corporate stakeholder, if available.	Required

`stakeholderDetails` object

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

Property	Description	Required
`kycMode`	The KYC mode for verifying the individual stakeholder. You can ignore this field as stakeholder KYC is not required.	Optional
`firstName`	The first name of the individual stakeholder.	Required
`middleName`	The middle name of the individual stakeholder.	Optional
`lastName`	The last name of the individual stakeholder.	Required
`nationality`	The nationality of the individual stakeholder.	Required
`dateOfBirth`	The date the individual stakeholder was born in the `YYYY-MM-DD` format. Date of birth cannot be a future date.	Required if the position is `UBO`
professionalDetails	The professional details of the individual stakeholder. This field is an array.	Required
address	An object that contains the residential address of the individual stakeholder.	Required if the position is `UBO`
contactDetails	An object that contains the contact details of the individual stakeholder	Optional

`professionalDetails` object

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

Property	Description	Required
`position`	The position of the individual stakeholder. Use Fetch corporate constants API for a valid set of values.	Required
`sharePercentage`	The share percentage of the individual stakeholder in the company.	Required when Position is `UBO`

`addresses` 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.	Required
`addressLine2`	The second address line of the individual stakeholder.	Optional
`city`	The city or suburb of the individual stakeholder.	Required
`state`	The state of the individual stakeholder.	Required
`country`	The country where the individual stakeholder resides, specified in ISO 3166 format.	Required
`postcode`	The postal code of the individual stakeholder.	Required

`contactDetails` object

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

Property	Description	Public	Trust	Other entity
`email`	The individual stakeholder's email address.	Optional	Optional	Optional
`contactNo`	The contact phone number of the individual stakeholder.	Optional	Optional	Optional

`businessPartner`

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

* This object is required if there's a corporate stakeholder.

Property	Description	Required
`businessName`	The registered business name of the corporate stakeholder.	Required
`businessRegistrationNumber`	The business registration number.	Required
`businessEntityType`	The position of the corporate stakeholder in the company. Use Fetch corporate constants API for a valid set of values.	Required
`sharePercentage`	The share percentage of the corporate stakeholder in the company. Note: If the corporate stakeholder’s position is `UBO`, then the share percentage is a required input parameter.	Required *
legalDetails	An object that contains the legal details of the corporate stakeholder.	Required

`legalDetails` object

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

Property	Description	Public	Trust	Other entity
`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	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.	Optional
`kycMode`	The KYC mode for verifying the identity of the applicant. Valid values are `E_KYC` , `E_DOC_VERIFY`, and `MANUAL_KYC`.	Required
`firstName`	The first name of the applicant. The maximum length is 40 alphabetic characters or spaces.	Required
`middleName`	The middle name of the applicant. The maximum length is 40 alphabetic characters or spaces.	Optional
`lastName`	The last name or the applicant. The maximum length is 40 alphabetic characters or spaces.	Required
`nationality`	The nationality of the applicant.	Required
`dateOfBirth`	The date when the applicant is born in the `YYYY-MM-DD` format. Date of birth cannot be a future date. Applicant cannot be less than 18 yrs of age.	Required
`occupation`	Occupation of applicant. Use Fetch corporate constants API for a valid set of values.	Required
professionalDetails	An array of objects that contains the professional details of the applicant.	Required
address	An object that contains the address of the applicant.	Required
contactDetails	An object that contains the contact details of the applicant.	Required
documentDetails	An array of objects that contains the document details of the applicant.	Required if `kycMode` is `MANUAL_KYC`
additionalInfo	An object that contains additional information about the applicant.	Required

`professionalDetails` object

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

Property	Description	Required
`position`	The position of the applicant. Use Fetch corporate constants API for a valid set of values.	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 when `position`is `UBO` or `PARTNER`

`address` object

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

Property	Description	Public	Trust	Other entity
`addressLine1`	The first address line of the applicant. The maximum character length is 40.	Required	Required	Required
`addressLine2`	The second address line of the applicant. The maximum character length is 40.	Optional	Optional	Optional
`city`	The city of the applicant. The maximum character length is 20.	Required	Required	Required
`state`	The state of the applicant. The Maximum character length is 30.	Required	Required	Required
`country`	The country where the applicant resides, specified in ISO 3166 format.	Required	Required	Required
`postcode`	The postal code of the applicant. The minimum length is 3 and the maximum length is 10 alphanumeric characters or spaces.	Required	Required	Required

`contactDetails` object

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

Property	Description	Public	Trust	Other entity
`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
`countryCode`.	The country code of the applicant's phone number.	Required	Required	Required
`contactNo`	The applicant's phone number. The maximum length is 20 numeric characters.	Required	Required	Required

`documentDetails` object

An 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.	Required
`documentNumber`	The ID number for the given document type.	Required
`documentIssuanceCountry`	The country that issued the business document, specified in the ISO 3166 format.	Required
`documentExpiryDate`	The date the document expires in the `YYYY-MM-DD` format. Note: This field is required if `documentType = PASSPORT or DRIVER_LICENCE`. Expiry date cannot be a past date.	Required *
document	An array of objects that contains the copy of the document. Note: This field is required for `MANUAL_KYC`.	Required *

`document` object

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

* This object is required for MANUAL_KYC.

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

`additionalInfo` object

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

While building the form, you should ensure that the applicant declaration is a checkbox that is collected on a separate page after the applicant has already filled the Stakeholder information. This page should show the list of all stakeholders in view mode. The applicant declaration text should imply the following statements objectively:

The List of UBOs and their details provided are complete and verified by the applicant
The List of directors and their details provided are complete and verified by the applicant
All the other information provided by the applicant is complete and verified.

Property	Description	Required
`applicantDeclaration`	This field accepts the declaration from the Applicant. The only valid value is `Yes`.	Required

`additionalInfo` object

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

Property	Description	Public	Trust	Other entity
`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 field is required if `Yes`; optional if `No`.	Optional	Optional	Optional

`riskAssessmentInfo` object

An object that contains the following details that 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.	Required
`annualTurnover`	The corporate customer's amount of annual turnover. Use Fetch corporate constants API for a valid set of values.	Required
`industrySector`	The corporate customer's industry sector. Use Fetch corporate constants API for a valid set of values.	Required
`countryOfOperation`	An array of countries the corporate customer operates in. Use Fetch corporate constants API for a valid set of values.	Required
`transactionCountries`	An array of countries where the transactions occur. Use Fetch corporate constants API for a valid set of values.	Required
`intendedUseOfAccount`	The customer's intended use of the account. Use Fetch corporate constants API for a valid set of values.	Required

`deviceDetails` object

This 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.	Required
`deviceInfo`	Information of the device e.g. Mac OS.	Required
`ipAddress`	IP address of the device e.g. 45.48.241.198	Required
`sessionId`	A unique identifier for the session, generated by your application.	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	Required
`key`	The name of the tag. The maximum character length is 128. Key should be unique.	Optional
`value`	The value of the tag. The maximum character length is 256.	Optional

📘Note

Request parameters

Table header API fields

businessDetails object

taxDetails array

legalDetails object

addresses object

registeredAddress object

businessAddress object

documentDetails array

document array

stakeholders object

stakeholderDetails object

professionalDetails object

addresses object

contactDetails object

businessPartner

legalDetails object

applicantDetails object

professionalDetails object

address object

contactDetails object

documentDetails object

document object

additionalInfo object

additionalInfo object

riskAssessmentInfo object

deviceDetails object

tags object

📘
Note

`businessDetails` object

`legalDetails` object

`addresses` object

`registeredAddress` object

`businessAddress` object

`documentDetails` array

`document` array

`stakeholders` object

`stakeholderDetails` object

`professionalDetails` object

`addresses` object

`contactDetails` object

`businessPartner`

`legalDetails` object

`applicantDetails` object

`professionalDetails` object

`address` object

`contactDetails` object

`documentDetails` object

`document` object

`additionalInfo` object

`additionalInfo` object

`riskAssessmentInfo` object

`deviceDetails` object

`tags` object