NZ Required Parameters

The API fields shown on this page are relevant to New Zealand 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 NZ-based customer, use the `NZ` value.	Yes
businessDetails	An object that contains business details about the corporate customer.	Yes
riskAssessmentInfo	An object that contains the risk assessment information.	Yes
expectedAccountUsage	An object that contains the expected usage of the account	Yes
tags	An object that contains the tags.	No
deviceDetails	An object that contains information about the customer's device and IP address.	Yes
`clientId`	This field contains the Nium client ID of the customer. It's received in the response of 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 of 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 page:

Association Private Sole trader	Government Partnership Public	Trust
`CLUB_ASSOCIATION` `PRIVATE_COMPANY` `SOLE_TRADER` `CO_OPERATIVE`	`GOVERNMENT_ENTITY` `GENERAL_PARTNERSHIP` `LIMITED_PARTNERSHIP` `PUBLIC_COMPANY`	`TRUST`

`businessDetails` object

An object that contains business details about the corporate customer.

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
`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. This fields accepts only 13-digit BRN	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
`hasNominee`	Boolean value stating if the entity has nominee stakeholder	Required	Required	Required
`isCashIntensiveBusiness`	Boolean value stating if the entity is a cash-intensive. Following question should be asked to the customer as is for this question. "Do you deal in physical cash in your business or collect cash deposits?. Example: Casino, Supermarket, Foreign exchange Store"	Required	Required	Required
`website`	The corporate customer's website.	Optional	Optional	Optional
`businessType`	The legal entity type of the business. Use Fetch corporate constants API for valid values.	Required	Required	Required
legalDetails	An object that contains the legal details.	Required	Required	Required
regulatoryDetails	The regulatory details about the corporate customer.	N/A	N/A	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. Required when the `businessDetails.businessType` is one of the following: `GENERAL_PARTNERSHIP` `LIMITED_PARTNERSHIP` `TRUST`	Optional	Required *	Required
bankAccountDetails	An object that contains the bank account details of the corporate customer.	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 the corporate customer's legal details.

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
`registeredDate`	The date the business is 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 valid values.	Required	Required	Required
`isRegistered`	Boolean value if the club, association or co-operative is registered. Required only for `CLUB_ASSOCIATION`, `CO_OPERATIVE`	Optional	N/A	N/A
`listedExchange`	The exchange where the business is publicly listed. Use Fetch corporate constants API for valid values. Note: This field is required for a `PUBLIC_COMPANY`.	N/A	Required *	N/A

`regulatoryDetails` object

An object within the businessDetails object that contains the regulatory details about the corporate customer.

This object is required if businessDetails.businessType is TRUST.

Property	Description	Trust
`unregulatedTrustType`	The unregulated trust type detail. Use Fetch corporate constants API for valid values. This field is an array.	Required

`addresses` object

An object within the businessDetails object that contains one or more business addresses.

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
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.addresses object that contains the address details where the corporate customer is registered.

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
`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 valid values.	Required	Required	Required
`postcode`	The postal code where the corporate customer is registered.	Required	Required	Required

`businessAddress` object

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

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

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
`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 valid 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.

Mandatory if businessDetails.businessType is one of the following:

PARTNERSHIP
TRUST

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

`document` object

An array of objects within the businessDetails.documentDetails object.

Property	Description	Association Private Sole trader	Government Partnership Public	Tust
`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

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

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`	Currency of the bank account	Yes *
`routingType`	Routing type of the bank account.	Yes *
`routingValue`	Routing value of the bank account. This field can contain alphanumeric characters. The valid length is either eight or ten characters.	Yes *
routingType2	Additional routing type of the bank account if applicable	No
routingValue2	Routing value for the additional bank account type if applicable	No

`additionalInfo` object

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

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
`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.	Optional	Optional	Optional

`stakeholders` array

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.

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
`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	Optional	Optional
stakeholderDetails	An object that contains the details about the individual stakeholders.	Required *	Optional	Required *
businessPartner	An object that contains the details about the corporate stakeholders, if available. Note: This is required only if a business partner exists.	Required *	Optional	Required *

`stakeholderDetails` object

An object within the stakeholders object that contains the details about an individual stakeholder. This object is required if individual stakeholder

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
`kycMode`	The KYC mode for verifying the individual stakeholder. Valid values are `E_KYC` and `MANUAL_KYC`.	Required	Required	Required
`firstName`	The given name of the individual stakeholder.	Required	Required	Required
`middleName`	The middle name of the individual stakeholder.	Optional	Optional	Optional
`lastName`	The last name 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
professionalDetails	An array of objects that contains the individual stakeholder's professional details.	Required	Required	Required
address	An object that contains the residential address of the individual stakeholder.	Required	Required	Required
documentDetails	An array of object that contains the document details about the individual stakeholder.	Required	Required	Required

`professionalDetails` array

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

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
`position`	The position of the individual stakeholder. Use Fetch corporate constants API for valid values.	Required	Required	Required
`capitalContribution`	The capital contribution of the individual stakeholder. Use Fetch corporate constants API for valid values using `annualTurnover` as the key	Required	Required	Required
`hasDistributionRight`	Boolean value stating if the stakeholder has distribution rights	Required	Required	Required
`interestPercentage`	Number between 0-100 stating the interest percentage of the stakeholder. Trust beneficiary interest percentage to be collected for trust beneficiary position. Partner interest percentage to be collected for partner position	N/A	Required*	Required*
`trusteeClass`	Class of trustees. Applicable only if the stakeholder position is a trustee. Use Fetch corporate constants API for valid values.	N/A	N/A	Required
`votingRights`	Array of voting rights of the stakeholder. Use Fetch corporate constants API for valid values.	Required	Required	Required
`sharePercentage`	Number between 0-100 stating the percentage of Shares owned by the stakeholder. Required only for UBOs.	Required*	Required*	Required*

`address` object

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

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
`addressLine1`	The first address line of the individual stakeholder's residential address. If `kycMode = E_KYC` then the following needs to be passed in this field as comma-separated values: unit number (if available) street number street name	Required *	Required *	Required *
`addressLine2`	The second address line of the individual stakeholder's residential address. Note: If `kycMode = E_KYC` then `streetType` needs to be passed in this field. Use Fetch corporate constants API for valid values.	Required *	Required *	Required *
`city`	The city or suburb of the individual stakeholder. If `kycMode = E_KYC` then suburb needs to be passed in this.	Required *	Required *	Required *
`state`	The state of the individual stakeholder's residential address.	Required *	Required *	Required *
`country`	The country of the individual stakeholder's residential address. Use Fetch corporate constants API for valid values.	Required *	Required *	Required *
`postcode`	The postal code of the individual stakeholder's residential address.	Required *	Required *	Required *

`documentDetails` object

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

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
`documentType`	The type of document. Use Fetch corporate constants API for valid 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 valid values.	Required	Required	Required
`documentRerefenceNumber`	Reference number of the document. Required only for Drivers License.	Required *	Required *	Required *
`documentExpiryDate`	The date the document expires in the `YYYY-MM-DD` format. Date of expiry cannot be a past date. Required only for Passport	Required *	Required *	Required *
document	A copy of the document.	Required *	Required *	Required *

`document`

An array of object within the businessDetails.stakeholders.stakeholderDetails.documentDetails object that contains a copy of the document.

* This object is required if kycMode = MANUAL_KYC.

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

`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 for any businessType .

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
`businessName`	The registered business name of the corporate stakeholder.	Required *	Required *	Required *
`businessRegistrationNumber`	The business registration number.	Required *	Required *	Required *
`businessType`	The legal entity type of the business.	Required *	Required *	Required *
`businessEntityType`	The position of the corporate stakeholder in the company. Use Fetch corporate constants API for valid values.	Required *	Required *	Required *
legalDetails	The corporate stakeholder's legal details.	Required *	Required *	Required *

`legalDetails` object

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

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
`registeredCountry`	The country where the corporate stakeholder is registered. Use Fetch corporate constants API for valid values.	Required *	Required *	Required *

`applicantDetails` object

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

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
`referenceId`	The UUID associated with the applicant and the 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	Optional	Optional
`kycMode`	The KYC mode for verifying the identity of the applicant. Valid values are `E_KYC` , `E_DOC_VERIFY`, and `MANUAL_KYC`.	Required	Required	Required
`firstName`	The first name of the applicant. The maximum length is 40 alphabetic characters or spaces.	Required	Required	Required
`middleName`	The middle name of the applicant. The maximum length is 40 alphabetic characters or spaces.	Optional	Optional	Optional
`lastName`	The last name or the applicant. The maximum length is 40 alphabetic characters or spaces.	Required	Required	Required
`nationality`	The nationality of the applicant. Use Fetch corporate constants API for valid values.	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 cannot be below 18 years of age.	Required	Required	Required
professionalDetails	An array of objects that contains the applicant's professional details.	Required	Required	Required
address	An object that contains the applicant's residential address.	Required	Required	Required
contactDetails	The contact details of the applicant.	Required	Required	Required
documentDetails	An array of objects that contains the applicant's document details.	Required	Required	Required

`professionalDetails` array

An array of objects within the businessDetails.applicantDetails object to contain the professional details about the applicant.

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
`position`	The position of the applicant. Use Fetch corporate constants API for valid values.	Required	Required	Required
`sharePercentage`	Number between 0-100 stating the percentage of Shares owned by the stakeholder. Required for UBOs.	Required	Required	Required

`address` object

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

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
`addressLine1`	The first address line of the applicant. The maximum character length is 40. If `kycMode = E_KYC` then the following needs to be passed in this field as comma-separated values: unit number (if available) street number street name	Required	Required	Required
`addressLine2`	The second address line of the applicant. The maximum character length is 40. If `kycMode = E_KYC` then `StreetType` needs to be passed in this field. Use Fetch corporate constants API for valid values.	Required	Required	Required
`city`	The city or suburb of the applicant. The maximum character length is 20. If `kycMode = E_KYC` then suburb needs to be passed in this field.	Required	Required	Required
`state`	The state of the applicant. The maximum character length is 30. Use Fetch corporate constants API for valid values.	Required	Required	Required
`country`	The country where the applicant resides. Use Fetch corporate constants API for valid values.	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 to contain the applicant's contact information.

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
`email`	The applicant's email address. The maximum character length is 40 and needs to be a valid email address. See Regex for email	Required	Required	Required
`countryCode`.	The country code of the applicant's phone number. Use Fetch corporate constants API for valid values.	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.

* This object is required if kycMode is MANUAL_KYC or E_DOC_VERIFY. In E_KYC, LOA is required if the applicant isn't a DIRECTOR/ UBO.

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
`documentType`	The type of document. Use Fetch corporate constants API for valid 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 valid values.	Required *	Required *	Required *
`documentExpiryDate`	The date the document expires in the `YYYY-MM-DD` format. Date of the expiry cannot be a past date.	Required *	Required *	Required *
`documentReferenceNumber`	Document reference number. Required for Drivers License. `driversLicenceVersionNumber` must be passed in this field	Required *	Required *	Required *
document	An array of objects that contains a copy of the document. Note: This object is required only for `MANUAL_KYC`. In `E_KYC` or `E_DOC_VERIFY`, `LOA` is required if the applicant isn't a `DIRECTOR`/ `UBO`.	Required	Required	Required

`document` object

An array of objects within the businessDetails.applicantDetails.documentDetails object that contains the document copy. This object is required only for MANUAL_KYC.

LOA is required if the applicant isn't a DIRECTOR/ UBO even for E_KYC and E_DOC_VERIFY

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

`riskAssessmentInfo` object

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

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
`totalEmployees`	The corporate customer's total number of employees. Use Fetch corporate constants API for valid values.	Required	Required	Required
`annualTurnover`	The corporate customer's amount of annual turnover. Use Fetch corporate constants API for valid values.	Required	Required	Required
`industrySector`	The corporate customer's industry sector. Use Fetch corporate constants API for valid values.	Required	Required	Required
`countryOfOperation`	An array of countries the corporate customer operates in. Use Fetch corporate constants API for valid values.	Required	Required	Required
`transactionCountries`	An array of countries where the transactions occur. Use Fetch corporate constants API for valid values.	Required	Required	Required

`expectedAccountUsage` object

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

Property	Description	Association Private Sole trader	Government Partnership Public	Trust
`intendedUses`	Array of Intended uses of the account. Use Fetch corporate constants API for a valid set of values.	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 Private Sole trader	Government Partnership Public	Trust
`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

`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 Private Sole trader	Government Partnership Public	Trust
`key`	The name of the tag. The maximum character length is 128. Key should be unique.	Optional	Optional	Optional
`value`	The value of the tag. The maximum character length is 256.	Optional	Optional	Optional

📘Note

Request parameters

Table header API fields

businessDetails object

legalDetails object

regulatoryDetails object

addresses object

registeredAddress object

businessAddress object

documentDetails object

document object

bankAccountDetails object

additionalInfo object

stakeholders array

stakeholderDetails object

professionalDetails array

address object

documentDetails object

document

businessPartner

legalDetails object

applicantDetails object

professionalDetails array

address object

contactDetails object

documentDetails object

document object

riskAssessmentInfo object

expectedAccountUsage object

deviceDetails object

tags object

📘
Note

`businessDetails` object

`legalDetails` object

`regulatoryDetails` object

`addresses` object

`registeredAddress` object

`businessAddress` object

`documentDetails` object

`document` object

`bankAccountDetails` object

`additionalInfo` object

`stakeholders` array

`stakeholderDetails` object

`professionalDetails` array

`address` object

`documentDetails` object

`document`

`businessPartner`

`legalDetails` object

`applicantDetails` object

`professionalDetails` array

`address` object

`contactDetails` object

`documentDetails` object

`document` object

`riskAssessmentInfo` object

`expectedAccountUsage` object

`deviceDetails` object

`tags` object