Required Parameters

The following details the required parameters for the Customer Onboarding v5 request, along with validation rules and sample requests.

Use this request to create customers to onboard in the HK region. The endpoint accepts both individual and corporate customers.

For API reference, see Create Customer v5.

Create Customer v5

POST /api/v5/client/{clientHashId}/customers

Path parameters

Parameter	Type	Required	Description
`clientHashId`	string	Yes	Unique client identifier, generated and shared before the integration is set up.

Body Parameters

Parameter	Type	Required	Accepted Values / Notes
`type`	string	Yes	`individual` or `corporate`.
`kycType`	string	Yes	`minimum` or `full`. Use `full` when onboarding for payouts.
`region`	string	Yes	Use `HK`.
`externalId`	string	Optional	Client-defined unique ID (max 36). Returned in webhooks and GET APIs.

Individual Customers

Personal Information

Field	Type	Required	Notes
`firstName`	string	Yes	Max 40.
`middleName`	string	Optional	Max 40.
`lastName`	string	Yes	Max 40.
`email`	string	Yes	Max 60; must match the valid email regex.
`nationality`	enum	Yes	Category: `countryName`.
`mobile`	numeric	Yes	Without country code; max 15 digits.
`mobileCountryCode`	numeric	Yes	Max 6 digits.
`dateOfBirth`	date	Yes	`YYYY-MM-DD`; age ≥ 18.

`billingAddress` Object

Field	Type	Required	Notes
`addressLine1`	string	Yes	Max 100.
`addressLine2`	string	Optional	Max 100.
`city`	string	Yes	Max 50.
`state`	enum/string	Conditional	category=isoState for countryCode=xx (e.g., HK, IN). If enum list is empty, pass state manually (max 50 chars).
`postcode`	string	Yes	Max 10.
`country`	enum	Yes	Category: `countryName`.

`expectedAccountUsage` Object

Field	Required	Notes
`credit.monthlyTransactionVolume`	Yes	Category: `monthlyTransactionVolume`.
`credit.topTransactionCountries`	Yes	Category: `countryName`.
`debit.monthlyTransactionVolume`	Yes	Category: `monthlyTransactionVolume`.
`debit.topTransactionCountries`	Yes	Destination countries for payouts.
`intendedUses`	Yes	Category: `intendedUseOfAccount`.
`intendedUsesDescription`	Conditional	Required if `Other` is selected. Max 300 chars.

Corporate Customers (Full KYC)

Business Information

Field	Type	Required	Notes
`businessType`	enum	Yes	Category: `businessType`.
`businessName`	string	Yes	Max 80.
`tradeName`	string	Yes	If not available, set equal to `businessName`.
`businessRegistrationNumber`	string	Yes	Max 30.
`registeredDate`	date	Yes	`YYYY-MM-DD`; past date.
`registeredCountry`	enum	Yes	Category: `countryName`.
`website`	string	Optional	website or verified social profile; else upload `PROOF_OF_BUSINESS`.
`isMultiLayeredCompany`	boolean	Yes	`true`/`false`. If `true` upload `CORPORATE_STRUCTURE`

`addresses` Object

Field	Type	Required	Notes
`registeredAddress.addressLine1`	string	Yes	Max 100.
`registeredAddress.addressLine2`	string	Optional	Max 100.
`registeredAddress.city`	string	Yes	Max 50.
`registeredAddress.state`	enum/string	Conditional	category=isoState for countryCode=xx (e.g., US, CA). If enum list is empty, pass state manually (max 50 chars).
`registeredAddress.postcode`	string	Yes	Max 10.
`registeredAddress.country`	enum	Yes	Category: `countryName`.
`isBusinessAddressSameAsRegisteredAddress`	boolean	Yes	If `false`, provide businessAddress details

`documents` (array of object)

Provide business documents

Field	Type	Required	Notes
`type`	enum	Yes	category: `documentType` Check Required Documents
`fileIds`	uuid	Yes	Received from the response of Upload file API

`applicant` object

Field	Type	Required	Notes
`externalId`	string	Optional	referenceId to identify the applicant.
`firstName`	string	Yes	Max 40 each.
`lastName`	string	Yes	Max 40 each.
`dateOfBirth`	date	Yes	Past date; age ≥ 18.
`email`	string	Yes	Max 60; valid email.
`mobile`	numeric	Yes	15 digit limits.
`mobileCountryCode`	numeric	Yes	1–3 digits
`nationality`	string	Yes	Max 2 char.
`sharePercentage`	numeric	Optional	Required only if position title is `UBO`/`SHAREHOLDER`.
`positions.title`	array of object	Yes	Include `DIRECTOR`, `REPRESENTATIVE`, `UBO` as applicable.
`documents`	array of object	Conditional	`LOA` required if applicant is not a UBO/ DIRECTOR/ PARTNER.
`address`	object	Yes	address of the applicant

Stakeholders

Stakeholders can be individuals or corporates with position such as UBO, Director, Partner, Trustee, Shareholder.

`stakeholders.individual` object

Field	Type	Required	Notes
`externalId`	string	Optional	referenceId to identify the applicant.
`firstName`	string	Yes	Max 40 each.
`lastName`	string	Yes	Max 40 each.
`dateOfBirth`	date	Yes	Past date; age ≥ 18.
`email`	string	Optional	Max 60; valid email.
`mobile`	numeric	Optional	15 digit limits.
`mobileCountryCode`	numeric	Optional	1–3 digits
`nationality`	string	Yes	Max 2 char.
`sharePercentage`	numeric	Optional	Required only if position title is `UBO`/`SHAREHOLDER`.
`positions.title`	array of object	Yes	Include `DIRECTOR`, `REPRESENTATIVE`, `UBO` as applicable.
`address`	object	Yes	address of the applicant

`stakeholders.corporate` object

Field	Required	Notes
`externalId`	Optional	unique Id
`businessName`	Yes	Registered name.
`businessRegistrationNumber`	Yes	Max 30.
`registeredCountry`	Yes	Category: `countryName`.
`positions.title`	Yes	For example, `UBO`, `Shareholder`, `Trustee`.
`sharePercentage`	Conditional	Required for UBO/Shareholder/Partner.

`natureOfBusiness` object

Field	Required	Notes
`operatingCountries`	Yes	category:`countryOfOperation` All countries where the business operates.
`industryCodes`	Yes	Category: `industrySector`. Industry sectors that the corporate customer operates in. Multiple allowed.
`industryDescription`	Conditional	2–3 sentences if “Other” is selected in industryCodes

See Prohibited Business Categories.

`expectedAccountUsage` object

Field	Required	Notes
`credit.monthlyTransactionVolume`	Yes	Estimated total payins (HKD).
`credit.monthlyTransactions`	Yes	Estimated count of monthly payins.
`credit.averageTransactionValue`	Yes	Average payin value (HKD).
`credit.topTransactionCountries`	Yes	Origin countries.
`debit.monthlyTransactionVolume`	Yes	Estimated total payouts (CAD).
`debit.monthlyTransactions`	Yes	Estimated count of monthly payouts.
`debit.averageTransactionValue`	Yes	Average payout value (CAD).
`debit.topTransactionCountries`	Yes	Destination countries.
`intendedUses`	Yes	Category: `intendedUseOfAccount`.
`intendedUsesDescription`	Conditional	Required if `Other`.

`sizeOfBusiness` object

Field	Required	Notes
`totalEmployees`	Yes	Category: `totalEmployees`.
`annualTurnover`	Yes	Category: `annualTurnover`. If business is less than 1 year old, provide expected turnover.

`bankAccountDetails` object (for refunds/returns- applicable for individual and corporate)

Field	Type	Required	Notes
`accountName`	string	Yes	Registered bank name; max 140.
`accountNumber`	string	Yes	Max 35.
`bankCountry`	string	Yes	ISO 3166-1 alpha-2.
`bankName`	string	Yes	Max 255.
`currency`	string	Yes	ISO 4217 (for example, `USD`, `HKD`).
`routingCodes.type`	string	Yes	Pass `SWIFT` etc.
`routingCodes.value`	string	Yes	Matches the selected type.
`bankCode`	string	Optional	Bank code

`applicantDeclaration` (applicable for individual and corporate)

Field	Type	Required	Description
`applicantDeclaration`	boolean	Yes	Indicates acceptance of the declaration.
`applicantDeclarationTimestamp`	timestamp	Yes	Format: `YYYY-MM-DD HH:MM:SS`

`devicedetails` object (applicable for individual and corporate)

Field	Type	Required	Notes
`ipCountryCode`	enum	Yes	Country of origin of the IP; category: `countryName`.
`deviceInfo`	string	Yes	OS of the device initiating the request.
`ipAddress`	string	Yes	Valid IPv4 address.
`sessionId`	string	Yes	Session identifier for the request.

`tags` object (applicable for individual and corporate)

Field	Type	Required	Notes
`tags`	object	Optional	Up to 15 client-defined key/value pairs.
`tags.key`	string	Optional	Max 128; keys must be unique.
`tags.value`	string	Optional	Max 255.

Examples

Corporate customer — request

{
    "type": "corporate",
    "kycType": "full",
    "region": "HK",
    "externalId": "eaaac4cd-5730-4dba-8d67-e9242025b",
    "businessName": "Greenholt West Inc",
    "website": "https://monserrat.biz",
    "businessDescription": "Technology solutions and consulting services provider",
    "businessRegistrationNumber": "4567895",
    "registeredDate": "2015-03-15",
    "registeredCountry": "HK",
    "isMultiLayeredCompany": false,
    "businessType": "private_company",
    "tradeName": "Greenholt - West Inc",
    "bankAccountDetails": {
        "accountName": "Greenholt West Inc Corporate Account",
        "bankName": "HSBC",
        "accountNumber": "802731561",
        "currency": "HKD",
        "bankAccountType": "saving",
        "bankCountry": "HK",
        "bankCode": "004",
        "routingCodes": [
            {
               "type": "SWIFT",
               "value": "HSBCHKHHHKH"
        }
        ]
    },
    "applicantDeclaration": true,
    "applicantDeclarationTimeStamp": "2024-01-15 10:30:00",    
    "addresses": {
        "isBusinessAddressSameAsRegisteredAddress": false,
        "registeredAddress": {
            "addressLine1": "1234 Corporate Blvd Suite 100",
            "addressLine2": "Building A",
            "city": "Newark",
            "state": "US-DE",
            "postcode": "19801",
            "country": "US"
        },
        "businessAddress": {
            "addressLine1": "5678 Business Park Drive",
            "addressLine2": "Floor 5",
            "city": "Newark",
            "state": "US-CA",
            "postcode": "07102",
            "country": "US"
        }
    },
    "applicant": {
        "externalId": "95d4c75b-089b-4aad-a9ab-f3b2360aa171",
        "firstName": "Tierra",
        "middleName": "James",
        "lastName": "White",
        "dateOfBirth": "1985-06-20",        
        "nationality": "US",
        "email": "test@company.com",
        "mobile": "197894",
        "mobileCountryCode": "1",
        "sharePercentage": 45,
        "address": {
            "addressLine1": "789 Executive Lane",
            "addressLine2": "Apt 12B",
            "city": "Boston",
            "state": "US-DE",
            "postcode": "02101",
            "country": "US"
        },     
        "documents": [
            {
                "type": "loa",
                "fileIds": [
                    "a9f55262-77ea-44a0-a5b8-b01bca79cc84"
                ]
            }
        ],
        "positions": [
            {
                "title": "SIGNATORY",
                "startDate": "2015-03-15"
            }
        ]
    },
    "stakeholders": {
        "individual": [
            {
                "externalId": "2a902305-bf54-41df-bfaa-d80c94d16805",
                "firstName": "Stake1",
                "middleName": "Robert",
                "lastName": "Volkman",                
                "dateOfBirth": "1980-11-10",
                "nationality": "HK",
                "email": "Rickie9@gmail.com",
                "mobile": "197786",
                "mobileCountryCode": "1",
                "sharePercentage": 30,
                "address": {
                    "addressLine1": "456 Investor Street",
                    "addressLine2": "Unit 8",
                    "city": "New York",
                    "state": "US-NY",
                    "postcode": "10001",
                    "country": "US"
                },
                "positions": [
                    {
                        "title": "UBO",
                        "startDate": "2016-01-20"
                    }
                ]
            }            
        ],
        "corporate": [
            {
                "externalId": "859ac163-08f0-4152-b26a-e96fce664372",
                "businessName": "Investment Holdings LLC",
                "businessRegistrationNumber": "123456789",
                "registeredCountry": "US",
                "sharePercentage": 25,
                "positions": [
                    {
                        "title": "UBO"
                    }
                ]
            }
        ]
    },
    "natureOfBusiness": {
        "operatingCountries": [
            "US",
            "CA",
            "GB"
        ],
        "industryCodes": [
            "IS134"
        ],
        "industryDescription": "Comprehensive technology consulting and software development services specializing in enterprise solutions, cloud infrastructure, and digital transformation initiatives for Fortune 500 companies across North America and Europe"
    },
    "expectedAccountUsage": {
        "intendedUses": [
            "IU001"
        ],
        "intendedUsesDescription": "Business operations including vendor payments, payroll processing, and international transactions",
        "credit": {
            "monthlyTransactionVolume": "MVHK01",
            "monthlyTransactions": "ATC01",
            "averageTransactionValue": "ATVHK01",
            "topTransactionCountries": [
                "US",
                "CA",
                "GB"
            ]
        },
        "debit": {
            "monthlyTransactionVolume": "MVHK01",
            "monthlyTransactions": "ATC01",
            "averageTransactionValue": "ATVHK01",
            "topTransactionCountries": [
                "US",
                "CA",
                "MX"
            ]
        }
    },
    "sizeOfBusiness": {
        "totalEmployees": "EM006",
        "annualTurnover": "HK008"
    },
    "deviceDetails": {
        "ipCountryCode": "hk",
        "deviceInfo": "Mozilla/5.0 Windows",
        "ipAddress": "192.168.1.100",
        "sessionId": "15aaa7ad-7625-4047-a2ce-6fe4ac476728"
    },
    "tags": [
        {
            "key": "customer_type",
            "value": "enterprise"
        },
        {
            "key": "priority",
            "value": "high"
        }
    ],
    "documents": [
        {
            "type": "business_registration_doc",
            "fileIds": [
                "3bb4595c-2d1b-47b3-a951-08175b9013c2"
            ]
        },
        {
            "type": "nar1",
            "fileIds": [
                "3bb4595c-2d1b-47b3-a951-08175b9013c2"
            ]
        }
    ]
}

Individual customer — request

{
    "type": "individual",
    "kycType": "full",
    "region": "HK",
    "externalId": "Jek2Vm6cw96xUA6GniQxKSd52VoaAXoBpp",
    "firstName": "Nium",  
    "lastName": "HK Test",
    "email": "pasumarthi.sashank+2118@nium.com",    
    "nationality": "HK",
    "mobile": "2000002105",
    "mobileCountryCode": "1",
    "dateOfBirth": "2008-02-25",
    "applicantDeclarationTimeStamp": "2025-08-20 15:49:30",
    "applicantDeclaration": "true",    
    "deviceDetails": {
        "ipCountryCode": "hk",
        "deviceInfo": "MAC",
        "ipAddress": "192.168.1.16",
        "sessionId": "hello-world"
    },
    "expectedAccountUsage": {        
        "credit": {
            "monthlyTransactionVolume": "MVHK01",
            "topTransactionCountries": [
                "GB",
                "GB",
                "GB",
                "IN"
            ]
        },
        "debit": {
            "monthlyTransactionVolume": "MVHK01",
            "topTransactionCountries": [
                "Gb",
                "GB",
                "GB",
                "IN",
                "US"
            ]
        },
        "intendedUses": [
            "Iu108",
            "IU107"
        ], 
        "intendedUsesDescription": "test intendedintendedtest",
    },
       "bankAccountDetails": {
        "accountName": "Greenholt West Inc Corporate Account",
        "bankName": "HSBC",
        "accountNumber": "802731561",
        "currency": "HKD",
        "bankAccountType": "saving",
        "bankCountry": "HK",
        "bankCode": "004",
        "routingCodes": [
            {
               "type": "SWIFT",
               "value": "HSBCHKHHHKH"
        }
        ]
    },
    "billingAddress": {
        "addressLine1": "Test Add 123, Building 1Test Add 123",
        "addressLine2": "Building 1Taa",
        "city": "Test Add 123, Building 1, Block 2, Area 3Test Add1",
        "state": "CA-ab",
        "postcode": "K1A 0B1",
        "country": "CA"
    }
}

For response check Response Codes.

Adding Positions

Directors: Add all management directors as stakeholders.
UBOs: Tag anyone owning ≥ 25% (direct or indirect). If none, the most senior director becomes the UBO.
Representatives/Signatories: Add individuals authorized to transact or manage users (applicant is a Representative by default).
Partners/Trustees/Settlors: Include when applicable by entity type.
Multi-layered companies: Include all corporate stakeholders with ≥ 25% ownership and upload a Corporate Structure document (documentType: CORPORATE_STRUCTURE).

See Position Mapping for the stakeholders required per business type.

Create Customer v5​

Path parameters​

Body Parameters​

Individual Customers​

Personal Information​

billingAddress Object​

expectedAccountUsage Object​

Corporate Customers (Full KYC)​

Business Information​

addresses Object​

documents (array of object)​

applicant object​

Stakeholders​

stakeholders.individual object​

stakeholders.corporate object​

natureOfBusiness object​

expectedAccountUsage object​

sizeOfBusiness object​

bankAccountDetails object (for refunds/returns- applicable for individual and corporate)​

applicantDeclaration (applicable for individual and corporate)​

devicedetails object (applicable for individual and corporate)​

tags object (applicable for individual and corporate)​

Examples​

Corporate customer — request​

Individual customer — request​

Adding Positions​