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

Request parameters

PropertyDescriptionRequired
regionThe country or geographic region where the corporate end customer is located and is onboarded. To onboard a US-based customer, use the US value.Yes
businessDetailsAn object that accepts business details about the corporate customer.Yes
riskAssessmentInfoAn object that contains the risk assessment information.Yes
tagsAn object that contains the tags.No
clientIdThis 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 *
customerHashIdThis 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:

PublicTrustOther entity
PUBLIC_COMPANYTRUST
  • CORPORATION
  • ESTATE
  • GENERAL_PARTNERSHIP
  • LIMITED_LIABILITY_PARTNERSHIP
  • SOLE_TRADER
  • UNICORP_PARTNERSHIP
  • businessDetails object

    An object that accepts business details about the corporate customer.

    PropertyDescriptionPublicTrustOther entity
    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.OptionalOptionalOptional
    businessNameThe name a corporate customer is registered under.RequiredRequiredRequired
    businessRegistrationNumberThe business registration number. For US customers, pass only the employer identification number (TIN). This field accepts only 9 digits.RequiredRequiredRequired
    tradeNameAnother name that the corporate customer uses to do business under, which is different than their licensed business name.OptionalOptionalOptional
    websiteA company's set of related web pages located under a single domain name.OptionalOptionalOptional
    businessTypeThe legal entity type of the business. Use Fetch corporate constants API for a valid set of values.RequiredRequiredRequired
    descriptionA brief overview of the business.RequiredRequiredRequired
    stockSymbolThe publicly traded stock or ticker symbol of the business.OptionalN/AN/A
    legalDetailsAn object that contains the legal details.RequiredRequiredRequired
    regulatoryDetailsAn object that contains the regulatory details.N/ARequiredN/A
    addressesAn object that contains the registered address and the business address of the corporate customer.RequiredRequiredRequired
    documentDetailsAn array of object that contains the business documents.
    Note: This object is required for MANUAL_KYB.
    Required *Required *Required *
    stakeholdersAn array of object that contains the individual and corporate stakeholders of the corporate customer.RequiredRequiredRequired
    applicantDetailsAn object that contains the applicant's details.RequiredRequiredRequired
    additionalInfoAn object that contains additional information about the business.OptionalOptionalOptional

    legalDetails object

    An object within the businessDetails object that accepts legal details.

    PropertyDescriptionPublicTrustOther entity
    registeredDateThe date the business is registered entered in the YYYY-MM-DD format.RequiredRequiredRequired
    registeredCountryThe country where the business is registered. Use Fetch corporate constants API for a valid set of values.RequiredRequiredRequired
    listedExchangeThe exchange where the business is publicly listed. Use Fetch corporate constants API for a valid set of values.RequiredN/AN/A

    regulatoryDetails object

    An object within the businessDetails object that accepts the regulatory status of the client.

    PropertyDescriptionPublicTrustOther entity
    unregulatedTrustTypeThe array of one or more unregulated trust types. Use Fetch corporate constants API for a valid set of values. This field is an array.N/ARequiredN/A

    addresses object

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

    PropertyDescriptionPublicTrustOther entity
    registeredAddressAn object that contains the address where the business is registered.RequiredRequiredRequired
    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
    Required *Required *Required *

    registeredAddress object

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

    PropertyDescriptionPublicTrustOther entity
    addressLine1The first address line of the registered business.RequiredRequiredRequired
    addressLine2The second address line of the registered business.OptionalOptionalOptional
    cityThe city where the corporate customer is registered.RequiredRequiredRequired
    stateThe state where the corporate customer is registered. Use Fetch corporate constants API for a valid set of values.RequiredRequiredRequired
    countryThe country where the corporate customer is registered. Use Fetch corporate constants API for a valid set of values.RequiredRequiredRequired
    postcodeThe postal code where the corporate customer is registered.RequiredRequiredRequired

    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 required if isSameBusinessAddress = No.

    PropertyDescriptionPublicTrustOther entity
    addressLine1The first address line of the principal place of business if different than the registered business.Required *Required *Required *
    addressLine2The second address line of the principal place of business if different than the registered business.OptionalOptionalOptional
    cityThe city of the principal place of business if different than the registered address.Required *Required *Required *
    stateThe 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 *Required *Required *
    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.Required *Required *Required *
    postcodeThe 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 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.

    PropertyDescriptionPublicTrustOther entity
    documentTypeThe type of business document. Use Fetch corporate constants API for a valid set of values.Required *Required *Required *
    documentAn object that contains a document copy.Required *Required *Required *

    document object

    An array of objects within the businessDetails.documentDetails object.

    PropertyDescriptionPublicTrustOther entity
    fileNameThe name of the file.Required *Required *Required *
    fileTypeThe type of the file. Valid types are application/pdf, image/jpeg, image/jpg, image/png, jpeg, jpg, and png.Required *Required *Required *
    documentThe file as a base64 encoded string.Required *Required *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.

    PropertyDescriptionPublicTrustOther entity
    referenceIdThe 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.OptionalOptionalOptional
    stakeholderDetailsAn object that contains the details about the individual stakeholder.RequiredRequiredRequired
    businessPartnerAn object that contains the details of the corporate stakeholder, if available.RequiredRequiredRequired

    stakeholderDetails object

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

    PropertyDescriptionPublicTrustOther entity
    kycModeThe KYC mode for verifying the individual stakeholder. The valid values are E_KYC and MANUAL_KYC.RequiredRequiredRequired
    firstNameThe first name of the individual stakeholder.RequiredRequiredRequired
    middleNameThe middle name of the individual stakeholder.OptionalOptionalOptional
    lastNameThe last name of the individual stakeholder.RequiredRequiredRequired
    nationalityThe nationality of the individual stakeholder.RequiredRequiredRequired
    dateOfBirthThe date the individual stakeholder was born in the YYYY-MM-DD format.RequiredRequiredRequired
    professionalDetailsThe professional details of the individual stakeholder. This field is an array.RequiredRequiredRequired
    addressAn object that contains the residential address of the individual stakeholder.RequiredRequiredRequired
    contactDetailsAn object that contains the contact details of the individual stakeholder.OptionalOptionalOptional
    documentDetailsAn array of object that contains the document details of the individual stakeholder.RequiredRequiredRequired

    professionalDetails object

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

    PropertyDescriptionPublicTrustOther entity
    positionThe position of the individual stakeholder.
    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.
    RequiredRequiredRequired
    sharePercentageThe share percentage of the individual stakeholder in the company.
    Note: This field is a required input parameter If the individual stakeholder’s position is UBO.
    Required *Required *Required *

    addresses object

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

    PropertyDescriptionPublicTrustOther entity
    addressLine1The first address line of the individual stakeholder.RequiredRequiredRequired
    addressLine2The second address line of the individual stakeholder.OptionalOptionalOptional
    cityThe city or suburb of the individual stakeholder.RequiredRequiredRequired
    stateThe state of the individual stakeholder.RequiredRequiredRequired
    countryThe country where the individual stakeholder resides, specified in ISO 3166 format.RequiredRequiredRequired
    postcodeThe postal code of the individual stakeholder.RequiredRequiredRequired

    contactDetails object

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

    PropertyDescriptionPublicTrustOther entity
    emailThe individual stakeholder's email address.OptionalOptionalOptional
    contactNoThe contact phone number of the individual stakeholder.OptionalOptionalOptional

    documentDetails object

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

    PropertyDescriptionPublicTrustOther entity
    documentTypeThe type of document. Use Fetch corporate constants API for a valid set of values.RequiredRequiredRequired
    documentNumberThe ID number for the given document type.RequiredRequiredRequired
    documentIssuanceCountryThe country that issued the business document. Use Fetch corporate constants API for a valid set of values.RequiredRequiredRequired
    documentExpiryDateThe date the document expires in the YYYY-MM-DD format.
    Note: This field is required if documentType = PASSPORT or DRIVER_LICENCE.
    Required *Required *Required *
    documentA copy of the document.
    Note: This field is required for MANUAL_KYC. This field is an array.
    Required *Required *Required *

    document object

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

    * This object is required for MANUAL_KYC.

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

    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.

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

    legalDetails object

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

    PropertyDescriptionPublicTrustOther entity
    registeredCountryThe country where the corporate stakeholder is registered. Use Fetch corporate constants API for a valid set of values.RequiredRequiredRequired

    applicantDetails object

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

    PropertyDescriptionPublicTrustOther entity
    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.OptionalOptionalOptional
    kycModeThe KYC mode for verifying the identity of the applicant. Valid values are E_KYC , E_DOC_VERIFY, and MANUAL_KYC.RequiredRequiredRequired
    firstNameThe first name of the applicant. The maximum length is 40 alphabetic characters or spaces.RequiredRequiredRequired
    middleNameThe middle name of the applicant. The maximum length is 40 alphabetic characters or spaces.OptionalOptionalOptional
    lastNameThe last name or the applicant. The maximum length is 40 alphabetic characters or spaces.RequiredRequiredRequired
    nationalityThe nationality of the applicant. Use Fetch corporate constants API for valid values.RequiredRequiredRequired
    dateOfBirthThe date when the applicant is born in the YYYY-MM-DD format.RequiredRequiredRequired
    professionalDetailsAn array of objects that contains the professional details of the applicant.RequiredRequiredRequired
    addressAn object that contains the address of the applicant.RequiredRequiredRequired
    contactDetailsAn object that contains the contact details of the applicant.RequiredRequiredRequired
    documentDetailsAn array of objects that contains the document details of the applicant.RequiredRequiredRequired
    additionalInfoAn object that contains additional information about the applicant.RequiredRequiredRequired

    professionalDetails object

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

    PropertyDescriptionPublicTrustOther entity
    positionThe position of the applicant. Use Fetch corporate constants API for a valid set of values.RequiredRequiredRequired
    sharePercentageThe share percentage of the applicant in the company.
    Note: This field is a required input parameter if the applicant's position is UBO.
    Required *Required *Required *

    address object

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

    PropertyDescriptionPublicTrustOther entity
    addressLine1The first address line of the applicant. The maximum character length is 40.RequiredRequiredRequired
    addressLine2The second address line of the applicant. The maximum character length is 40.OptionalOptionalOptional
    cityThe city of the applicant. The maximum character length is 20.RequiredRequiredRequired
    stateThe state of the applicant. The Maximum character length is 30.RequiredRequiredRequired
    countryThe country where the applicant resides, specified in ISO 3166 format.RequiredRequiredRequired
    postcodeThe postal code of the applicant. The minimum length is 3 and the maximum length is 10 alphanumeric characters or spaces.RequiredRequiredRequired

    contactDetails object

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

    PropertyDescriptionPublicTrustOther entity
    emailThe applicant's email address. The maximum character length is 40 and needs to be a valid email address.RequiredRequiredRequired
    countryCode.The country code of the applicant's phone number.RequiredRequiredRequired
    contactNoThe applicant's phone number. The maximum length is 20 numeric characters.RequiredRequiredRequired

    documentDetails object

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

    PropertyDescriptionPublicTrustOther entity
    documentTypeThe type of document. Use Fetch corporate constants API for a valid set of values.RequiredRequiredRequired
    documentNumberThe ID number for the given document type.RequiredRequiredRequired
    documentIssuanceCountryThe country that issued the business document, specified in the ISO 3166 format.RequiredRequiredRequired
    documentExpiryDateThe date the document expires in the YYYY-MM-DD format.
    Note: This field is required if documentType = PASSPORT or DRIVER_LICENCE.
    Required *Required *Required *
    documentAn array of objects that contains the copy of the document.
    Note: This field is required for MANUAL_KYC.
    Required *Required *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.

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

    additionalInfo object

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

    PropertyDescriptionPublicTrustOther entity
    applicantDeclarationThis field accepts the declaration from the Applicant. The only valid value is Yes.RequiredRequiredRequired

    additionalInfo object

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

    PropertyDescriptionPublicTrustOther entity
    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 field is required if Yes; optional if No.
    OptionalOptionalOptional

    riskAssessmentInfo object

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

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

    tags object

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

    PropertyDescriptionPublicTrustOther entity
    keyThe name of the tag. The maximum character length is 128.OptionalOptionalOptional
    valueThe value of the tag. The maximum character length is 256.OptionalOptionalOptional