Required Parameters
The API fields shown on this page are relevant to the United States only. To see the full payload, refer to the Onboard Corporate Customer API Reference.
All fields have a maximum limit of 255 characters unless stated otherwise.
Request parameters
Property | Description | Required |
---|---|---|
region | The regulatory region under which the corporate customer is being onboarded. To onboard under the US region, use the US value. | Yes |
businessDetails | Contains information about the business, including the applicant and stakeholders. | Yes |
riskAssessmentInfo | Provides additional business profile information, such as total number of employees and annual turnover. | Yes |
deviceDetails | Includes the device and IP address from which the onboarding request originated. | Yes |
tags | Contains user-defined key-value pairs submitted by the client. | No |
customerHashId | A unique identifier returned in the response to the Onboard Corporate Customer request.Note:* Required only when reinitiating KYB after a rejection. | Yes * |
Table header API fields
The below table headers refer to the businessType
fields:
Public | Trust | Other entity |
---|---|---|
PUBLIC_COMPANY | TRUST | CORPORATION LIMITED_LIABILITY_COMPANY ESTATE GENERAL_PARTNERSHIP LIMITED_LIABILITY_PARTNERSHIP SOLE_TRADER UNICORP_ASSOCIATION LIMITED_PARTNERSHIP |
businessDetails
object
Contains information about the corporate customer, including the applicant and stakeholders.
Property | Description | Public | Trust | Other entity |
---|---|---|---|---|
referenceId | A unique identifier for the business entity. If not provided, Nium generates one. Used to respond to RFIs or upload documents. | Optional | Optional | Optional |
businessName | The registered name of the business. | Required | Required | Required |
businessRegistrationNumber | The business registration number. For US customers, pass only the employer identification number (EIN). This field accepts only 9 digits. Sole traders can submit TIN/ SSN in case EIN is not avialable | Required | Required | Required |
tradeName | The name the business operates under. If the business doesn't use a trade name, set businessName as tradeName | Required | Required | Required |
website | The business’s website. If not available, submit a social media profile (such as Instagram or Facebook). If neither is available, upload a document with documentType : PROOF_OF_BUSINESS. | Optional | Optional | Optional |
businessType | The legal entity type, such as a private or public company. Use the Fetch Corporate Constants requests with category : businessType . | Required | Required | Required |
description | A brief overview of the business. Max character length allowed is 65535. | Required | Required | Required |
stockSymbol | The publicly traded stock or ticker symbol of the business. | Optional | N/A | N/A |
legalDetails | Registration and legal information for the business. | Required | Required | Required |
regulatoryDetails | An object that contains the regulatory details. | N/A | Required | N/A |
addresses | An object that contains the registered address and the business address of the corporate customer. | Required | Required | Required |
documentDetails | Business documents. For details, see US Required Documents. | 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 |
legalDetails
object
An object within the businessDetails
object that accepts legal details.
Property | Description | Public | Trust | Other entity |
---|---|---|---|---|
registeredDate | The date the business is registered entered in the YYYY-MM-DD format. Registered date cannot be a future date. | Required | Required | Required |
registeredCountry | The country where the business is registered. Use Fetch corporate constants API for a valid set of values with category =countryName . | Required | Required | Required |
listedExchange | The exchange where the business is publicly listed. Use Fetch corporate constants API for a valid set of values with category =listedExchange . | Required | N/A | N/A |
regulatoryDetails
object
An object within the businessDetails
object that accepts the regulatory status of the client.
Property | Description | Public | Trust | Other entity |
---|---|---|---|---|
unregulatedTrustType | The array of one or more unregulated trust types. Use Fetch corporate constants API for a valid set of values with category =unregulatedTrustType . This field is an array. | N/A | Required | N/A |
addresses
object
An object within the businessDetails
object that accepts registered and business addresses.
Property | Description | Public | Trust | Other entity |
---|---|---|---|---|
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 not required if isSameBusinessAddress= Yes is passed under businessDetails.additionalInfo. | Required * | Required * | 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. | 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. Use Fetch corporate constants API for a valid set of values with category =state . | Yes |
country | The country where the corporate customer is registered. Use Fetch corporate constants API for a valid set of values 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 accepts the address details of the principal place of business only when the registered address is different.
* This object is not required if businessDetails.additionalInfo.isSameBusinessAddress = Yes.
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 of the business address. | Yes * |
state | The state of the business address. Use Fetch corporate constants API for a valid set of values with category =state . | Yes * |
country | The country of the business address. Use Fetch corporate constants API for a valid set of values with category =countryName . | Yes * |
postcode | The postal code of the business address. | Yes * |
documentDetails
object
An array of objects within the businessDetails
object that accepts one or more business documents.
* This object is required for MANUAL_KYB
.
For both manual KYB and eKYB, the CERTIFICATE_OF_GOOD_STANDING
document is required when the address.registeredAddress.state
field is DE
or NJ
.
Property | Description | Required |
---|---|---|
documentType | The type of business document. Use Fetch corporate constants API for a valid set of values with category =documentType . | Yes * |
document | An object that contains a document copy. | Yes * |
document
object
An array of objects within the businessDetails.documentDetails
object such as Business Registration Document or Partnership Deed. You can add multiple files under the same document object such as multiple pages of the Business Registration Document or addendum.
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 | 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 . | Yes * |
stakeholders
object
An array of objects within the businessDetails object that contains the stakeholders of the corporate customers such as Directors or UBOs. Stakeholder can be a business entity or a natural person. For every stakeholder object, you need to 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. | No |
stakeholderDetails | An object that contains the details about the individual stakeholder. | Yes |
businessPartner | An object that contains the details of the corporate stakeholder, if available. | Yes |
stakeholderDetails
object
An object within the stakeholders object that contains the details about an individual stakeholder (natural person). All the Signatories, Directors, UBOs, Trustees, Settlor, Partners as available in the registration documents or SOS filings should be added as stakeholders.
- Directors: All the officers declared during registration need to be added as Directors. Other Board of Directors should also be added as directors.
- UBO: All shareholders owning more than 25% of share (directly or indirectly) should be tagged as UBOs. In case no UBO is submitted, Nium’s team will identify the UBO. For sole traders, the owner should be declared as the UBO.
- CONTROL PRONG: Individuals with significant responsibility to control, manage, or direct the legal entity. This includes: CEO, CFO, COO, Managing Member, General Partner, President, etc. At least one Control Prong should be identified while submitting the application.
- Signatory: Individual(s) that will conduct transactions or add additional users should be declared as a Signatory. Applicant is considered as Signatory by default and should be added as such and will be eligible for conducting transactions. Any other users can be added as representatives as well. It is recommended to send all the users as part of the application. These users can be added later as well by sending an email to usermanagement@nium.com. KYC of such users should be completed as directed.
- Others: Other positions such as Partner/ Trustee / Settlor should be provided as applicable as per the Position mapping
Property | Description | Required |
---|---|---|
kycMode | The KYC mode for verifying the individual stakeholder. The valid values are E_KYC and 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 (e.g., US, IN). Use Fetch Corporate Constants requests for a valid set of values 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 array of object that contains the document details of the individual stakeholder. | Yes |
professionalDetails
object
An array of object within the businessDetails.stakeholders.stakeholderDetails
object that contains the individual stakeholder's professional details. Very often an individual can hold more that one position such as DIRECTOR/ UBO and all applicable positions must be selected.
Property | Description | Required |
---|---|---|
position | The position of the individual stakeholder such as UBO, DIRECTOR, SIGNATORY. At least one of the individual stakeholders should have a position as CONTROL_PRONG . Use Fetch corporate constants API for a valid set of values with category =position . | Yes |
sharePercentage | The share percentage of the individual stakeholder in the company. Sharepercentage should be a number between 0 and 100. Eg. 23.4 Note: This field is required if position is UBO or SHAREHOLDER. Else ignore. | Yes * |
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. | Yes |
addressLine2 | The second address line of the individual stakeholder. | No |
city | The city or suburb of the individual stakeholder. | Yes |
state | The state or province of the individual stakeholder. | Yes |
country | The country where the individual stakeholder resides, specified in ISO 3166 format 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 individual 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
An 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 with category =documentType . | Yes |
documentNumber | The identification number of the document. | Yes |
documentIssuanceCountry | The country that issued the 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. Note: This field is required if documentType = PASSPORT or DRIVER_LICENCE . Expiry date cannot be a past date. | Yes * |
document | A copy of the document. Note: This field is required for MANUAL_KYC . This field is an array. | Yes * |
document
object
An array of objects within the businessDetails.stakeholders.stakeholderDetails.documentDetails
object that contains the document copy. You can pass front and back of a passport etc.. as in array under the same documentDetails object.
* This object is required for MANUAL_KYC
.
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
An object within the businessDetails.stakeholders object that contains the business details of the corporate stakeholder.
If the customer is a multilayered company with another corporate owning more than 25% of share directly or indirectly then all such corporate stakeholders should be declared in the application. Refer Multi-layered ownership structure to understand if the customer is a multi-layered company. Additionally, Ownership chart document should be submitted to validate the structure under businessDetails.documentType = OWNERSHIP_CHART. Refer to US Required documents.
Property | Description | Required |
---|---|---|
businessName | The registered business name of the corporate stakeholder. | Yes |
businessRegistrationNumber | The business registration number. | Yes |
businessEntityType | The primary position of the corporate stakeholder in the business of the company. Use Fetch Corporate Constants requests with category = position for a valid set of values. Corporate stakeholders can typically hold positions such as UBO, SHAREHOLDER, PARTNER, TRUSTEE. Sometimes, corporate stakeholder can be a DIRECTOR as well. | Yes |
sharePercentage | The share percentage of the corporate stakeholder in the company. Note: This field is required if the stakeholder’s position is UBO or SHAREHOLDER. Else ignore. Sharepercentage should be a number between 0 and 100. Eg. 23.4 | Yes * |
legalDetails | An object that contains the registration and 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.
Property | Description | Required |
---|---|---|
registeredCountry | The country where the corporate stakeholder is registered. Use Fetch corporate constants API for a valid set of values with category =countryName . | Yes |
applicantDetails
object
Contains details about the individual applicant representing the corporate customer.
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. Valid values are E_KYC , 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 | The nationality of the applicant (e.g., US, IN). Use Fetch corporate constants API for valid values with category =countryName . | Yes |
dateOfBirth | The date when the applicant is born in the YYYY-MM-DD format. Date of birth cannot be a future date. Applicant age cannot cannot be less than 18 yrs. | Yes |
professionalDetails | An array of objects 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 objects that contains the document details of the applicant. | Yes |
additionalInfo | An object that contains additional information about the applicant such as applicant declaration. | Yes |
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 with category =position . An applicant is a REPRESENTATIVE by default. In addition, all applicable positions like UBO or DIRECTOR should be added. | Yes |
sharePercentage | The share percentage of the applicant in the company. Number between 0 and 100. Eg., 23.4 Note: This field is required if the position is UBO/ SHAREHOLDER. | Yes * |
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 of the applicant. The maximum character length is 20. | Yes |
state | The state or province of the applicant. The Maximum character length is 30. | Yes |
country | The country where the applicant resides. Use Fetch corporate constants API for valid values with category =countryName . | Yes |
postcode | The postal code of the applicant. The minimum length is 3 and the maximum length is 10 alphanumeric characters or spaces. | 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. Use Fetch corporate constants API for valid values with category =countryName . | Yes |
contactNo | The 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. For
- E_KYC, documentDetails are required. Document is required only for submitting an LOA.
- For E_DOC_VERIFY, documentDetails and documents are not required,unless for submitting an LOA.
- For Manual KYC, both are required.
Property | Description | E_DOC_VERIFY | E_KYC | MANUAL_KYC |
---|---|---|---|---|
documentType | The type of the document. Use Fetch corporate constants API for a valid set of values with category =documentType . | Yes * | Yes | Yes |
documentNumber | Identification number of the document. | No | Yes | Yes |
documentIssuanceCountry | The country that issued the document. Use Fetch corporate constants API for a valid set of values with category =documentType | No | Yes | Yes |
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 past date. | No | Yes* | Yes * |
document | An array of objects that contains the copy of the document. Note: This field is required for MANUAL_KYC or for submitting LOA . | Yes * | Yes* | Yes |
document
object
An array of objects within the businessDetails.applicantDetails.documentDetails
object that contains the document copy. You can pass front and back of passport etc.. as an array under the same documentDetails object.
* This object is required for MANUAL_KYC
or for submitting 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
An object within the businessDetails.applicantDetails
object that contains additional information about the applicant. See Applicant Declaration for details
Property | Description | Required |
---|---|---|
applicantDeclaration | This field accepts the declaration from the Applicant. The only valid value is Yes . | Yes |
applicantDeclarationTimestamp | The timestamp at which applicant accpeted the declaration in YYYY-MM-DD HH:MM:SS format in UTC timezone | Yes |
expectedAccountUsage
object
This object contains the details regarding the expected usage of the account
Property | Description | Required |
---|---|---|
debit | Object containing expected account usage of all outward transactions. | Yes |
credit | Object containing expected account usage of all inward transactions. | Yes |
intendedUses | Array of intended uses of the account. Send all applicable values. Use Fetch Corporate Constants with category = intendedUses for valid values. | Yes |
intendedUsesDescription | Text field description of the intended use of the account of the corporate customer. Min 20 characters. | No |
debit
object
This object containing expected account usage of all outward transactions
Property | Description | Required |
---|---|---|
monthlyTransactionVolume | Estimated total monthly payout transaction amount converted to USD . Use Fetch Corporate Constants requests with category =monthlyTransactionVolume for a valid set of values. | Yes |
monthlyTransactions | Estimated count of payout transactions per month for the corporate customer. Use Fetch Corporate Constants requests with category =monthlyTransactions for a valid set of values. | Yes |
averageTransactionValue | Estimated average transaction value per payout for the corporate customer converted to USD . Use Fetch Corporate Constants requests with category =annualTurnover for a valid set of values. | Yes |
topTransactionCountries | Array of top payout countries. Use Fetch Corporate Constants requests with category = countryName for a valid set of values. | Yes |
credit
object
This object containing expected account usage of all inward transactions.
- In case the customer is not enabled for payins, the client is expected to send the minimum bracket within the allowed ranges for
monthlyTransactionVolume
,monthlyTransactions
,averageTransactionValue
. - The entire credit object is not applicable if the client is a Payroll client and/ or have requested Nium to switch off third party funding.
Property | Description | Required |
---|---|---|
monthlyTransactionVolume | Estimated total monthly payin transaction amount converted to USD . Use Fetch Corporate Constants requests with category =monthlyTransactionVolume for a valid set of values. | Yes |
monthlyTransactions | Estimated count of payin transactions per month for the corporate customer. Use Fetch Corporate Constants requests with category =monthlyTransactions for a valid set of values. | Yes |
averageTransactionValue | Estimated average transaction value per payin for the corporate customer converted to USD . Use Fetch Corporate Constants category =annualTurnover for a valid set of values. | Yes |
topTransactionCountries | Array of top payin countries. Use Fetch Corporate Constants requests with category = countryName for a valid set of values. | Yes |
topRemitters | Array of expected primary remitters. Can be specific companies or types of entities (e.g., Ryan Air, Ketan Meheta, Employees of corporate). | Yes |
natureOfBusiness
object
An object within the businessDetails.natureOfBusiness
object to provide the nature of business such as industrySector.
* If the industrySector contains any prohibited industries, additional documentation might be requested and can affect the overall approval TAT. Refer to Prohibited and Restricted Business Categories
Property | Description | Required |
---|---|---|
industryCodes | An array of industry sector codes that apply for the corporate customer's business. Send all applicable values. Use Fetch Corporate Constants for a valid set of values using industrySector category | Yes |
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 requests for a valid set of values with category =totalEmployees . | Yes |
annualTurnover | The corporate customer’s annual turnover.If the company is less than one year old, provide the expected turnover; otherwise, provide the turnover from the previous year. Turnover refers to the total revenue generated by the business. Use Fetch Corporate Constants with category = annualTurnover for a valid set of values. | Yes |
countryOfOperation | An array of all the countries the corporate customer has presence and does business. List all the countries you have branches, operations, factories etc… Use Fetch Corporate Constants with category =countryName for a valid set of values. This field is an array. Ex: ["IN", "FR", "LT"] | Yes |
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 with category =countryName . | Yes |
deviceInfo | Information of the device e.g. Mac OS. | Yes |
ipAddress | IP address of the device in IPV4 format e.g. 45.48.241.198 | Yes |
sessionId | A unique identifier for the session, generated by your system. | Yes |
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. | No |
value | The value of the tag. The maximum character length is 256. | No |