Skip to main content

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 US region. The endpoint accepts both individual and corporate customers.

For a breakdown of the request and parameters, see Create Customer v5.

Create Customer v5​

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

Path parameters​

ParameterTypeRequiredDescription
clientHashIdstringYesUnique client identifier, generated and shared before the integration is set up.

Body parameters​

Field (M/O/C)DescriptionData typeAccepted values
type (M)Customer type.enumindividual, corporate
kycType (M)KYC type performed for this customer.enumminimum, full
region (M)Regulatory region the customer is onboarded under.enumUse US
externalId (O)Customer-provided reference ID.stringMax 36 chars; alphanumeric; unique per customer under a client.

Individual Customers​

billingAddress​

Field (M/O/C)DescriptionData typeAccepted values
billingAddress (M)Customer billing address.object—
billingAddress.addressLine1 (M)Address line 1.stringMax 100 chars
billingAddress.addressLine2 (O)Address line 2.stringMax 100 chars
billingAddress.city (M)City.stringMax 50 chars
billingAddress.state (M)State/region.string/enumenum: icategory=isoState for countryCode=xx (e.g., US, SG). If enum list is empty, pass as string (max 50 chars).
billingAddress.postcode (M)Postal/ZIP code.stringMax 10 chars; alphanumeric and spaces
billingAddress.country (M)Country.enumcategory: countryName

expectedAccountUsage​

Field (M/O/C)DescriptionData typeAccepted values
expectedAccountUsage (M)Account usage activity profile.object—
expectedAccountUsage.credit (M)Expected account usage for payins.object—
expectedAccountUsage.credit.monthlyTransactionVolume (M)Monthly transaction volume range.enumcategory: monthlyTransactionVolume
expectedAccountUsage.credit.topTransactionCountries (M)Top 5 countries where funding is expected to originate.array of enumscategory: countryName
expectedAccountUsage.debit (M)Expected account usage for payouts.object—
expectedAccountUsage.debit.monthlyTransactionVolume (M)Monthly transaction volume range.enumcategory: monthlyTransactionVolume
expectedAccountUsage.debit.topTransactionCountries (M)Top 5 countries for payouts.array of enumscategory: countryName
expectedAccountUsage.intendedUses (M)Intended uses of the account.array of enumscategory: intendedUseOfAccount
expectedAccountUsage.intendedUsesDescription (C)Required if intendedUses includes Others.stringMax 500–1000 chars (varies by flow)

bankAccountDetails​

Field (M/O/C)DescriptionData typeAccepted values
bankAccountDetails (M)Bank account details used to return funds (returns/refunds).object—
bankAccountDetails.accountName (M)Account holder name as registered with the bank.stringAlphanumeric plus: & . , ( ) _ ' / -; max 140 chars
bankAccountDetails.accountNumber (M)Bank account number for returns/refunds.stringAlphanumeric; max 35 chars
bankAccountDetails.bankCountry (M)Country where the bank account is held (ISO 3166-1 alpha-2).stringcategory: countryName
bankAccountDetails.bankAccountType (C)Bank account type (e.g., savings, checking, current).stringUse the Bene schema endpoint to fetch exact requirements.
bankAccountDetails.bankName (C)Full legal bank name.stringMax 255 chars
bankAccountDetails.currency (M)Bank account currency (ISO 4217).stringExample: USD, INR
bankAccountDetails.routingCodes.type (M)Routing identifier type.stringACH CODE, SWIFT
bankAccountDetails.routingCodes.value (M)Routing identifier value for the specified type.string—

deviceDetails​

Field (M/O/C)DescriptionData typeAccepted values
deviceDetails (M)Device/session details (security/risk).object—
deviceDetails.ipCountryCode (M)Country of origin for the IP address.enumcategory: countryName
deviceDetails.deviceInfo (M)Device operating system information.string—
deviceDetails.ipAddress (M)Device IP address.stringValid IPv4 address
deviceDetails.sessionId (M)Session ID that initiated the request.string—

declarations​

Field (M/O/C)DescriptionData typeAccepted values
applicantDeclaration (M)Applicant confirmation they accept the declaration.booleanMust be true
applicantDeclarationTimeStamp (M)Timestamp when the declaration was accepted.date—

tags​

Field (M/O/C)DescriptionData typeAccepted values
tags (O)User-defined metadata.object—
tags.key (O)User-defined key.stringExample: merchantID
tags.value (O)User-defined value.stringExample: MID123

Corporate Customers​

corporateCustomerFields​

Field (M/O/C)DescriptionData typeAccepted values
businessType (M)Business type for the corporate customer.enumcategory: businessType
businessName (M)Legal business name.stringMax 80 chars
tradeName (M)Doing-business-as name (if different from legal name).stringMax 80 chars
businessRegistrationNumber (M)Business registration number (EIN). Sole traders may submit TIN/SSN if EIN is unavailable.string9 digits
registeredDate (M)Business registration date.dateYYYY-MM-DD; must be a past date
registeredCountry (M)Country of registration.enumcategory: countryName
website (C)Business website. If unavailable, provide a proof-of-business document.stringMax 255 chars
isMultiLayeredCompany (M)Whether the business has multi-layer ownership (via intermediaries).boolean—
listedExchange (C)Required for public companies.enum—
stockSymbol (O)Public ticker symbol (public companies).string—
trustType (C)Unregulated trust type (trust companies).string—

registeredAddress​

Field (M/O/C)DescriptionData typeAccepted values
registeredAddress (M)Registered address for the corporate customer.object—
registeredAddress.addressLine1 (M)Address line 1.stringMax 100 chars
registeredAddress.addressLine2 (O)Address line 2.stringMax 100 chars
registeredAddress.city (M)City.stringMax 50 chars
registeredAddress.state (M)State/region.string/enumenum: icategory=isoState for countryCode=xx (e.g., US, SG). If enum list is empty, pass as string (max 50 chars).
registeredAddress.postcode (M)Postal/ZIP code.stringMax 10 chars; alphanumeric and spaces
registeredAddress.country (M)Country.enumcategory: countryName

businessAddress​

Field (M/O/C)DescriptionData typeAccepted values
businessAddress (M)Communication/business address.object—
businessAddress.addressLine1 (M)Address line 1.stringMax 100 chars
businessAddress.addressLine2 (O)Address line 2.stringMax 100 chars
businessAddress.city (M)City.stringMax 50 chars
businessAddress.state (M)State/region.string/enumenum: icategory=isoState for countryCode=xx (e.g., US, SG). If enum list is empty, pass as string (max 50 chars).
businessAddress.postcode (M)Postal/ZIP code.stringMax 10 chars; alphanumeric and spaces
businessAddress.country (M)Country.enumcategory: countryName

natureOfBusiness​

Field (M/O/C)DescriptionData typeAccepted values
natureOfBusiness (M)Business profile for the corporate customer.object—
natureOfBusiness.operatingCountries (M)Countries where the business operates.array of enumscategory: countryOfOperation
natureOfBusiness.industryCodes (M)Industry sectors the business operates in (multiple allowed).array of enumscategory: industrySector
natureOfBusiness.industryDescription (M)Description of the business.stringMax 1000 chars

sizeOfBusiness​

Field (M/O/C)DescriptionData typeAccepted values
sizeOfBusiness (M)Business size profile.object—
sizeOfBusiness.totalEmployees (M)Total number of employees.enum—
sizeOfBusiness.annualTurnover (M)Annual revenue/turnover range.enumcategory: annualTurnover

applicant​

Field (M/O/C)DescriptionData typeAccepted values
applicant (M)Individual submitting the application on behalf of the customer.object—
applicant.externalId (O)Applicant reference identifier.stringMax 36 chars; alphanumeric; unique across applicant + stakeholders
applicant.firstName (M)Applicant first name.stringMax 40 chars
applicant.middleName (O)Applicant middle name.stringMax 40 chars
applicant.lastName (M)Applicant last name.stringMax 40 chars
applicant.dateOfBirth (M)Applicant date of birth.date/stringYYYY-MM-DD; must be a past date
applicant.nationality (M)Applicant nationality.enumcategory: countryName
applicant.email (M)Applicant email.stringMax 60 chars; valid email
applicant.mobile (M)Mobile number (without country code).stringMax 15 chars
applicant.mobileCountryCode (M)Mobile country calling code.stringMax 6 chars
applicant.sharePercentage (O)Applicant ownership share percentage.numeric0–100 (decimal). Required if applicant is UBO/shareholder.

address​

Field (M/O/C)DescriptionData typeAccepted values
address (M)Residential address (used for applicant and individual stakeholders).object—
address.addressLine1 (M)Address line 1.stringMax 100 chars
address.addressLine2 (O)Address line 2.stringMax 50–100 chars (varies by flow)
address.city (M)City.stringMax 50 chars
address.state (M)State/region.string/enumenum: icategory=isoState for countryCode=xx (e.g., US, SG). If enum list is empty, pass as string (max 50 chars).
address.country (M)Country.enumcategory: countryName
address.postcode (M)Postal/ZIP code.stringMax 10 chars; alphanumeric and spaces

positions​

Field (M/O/C)DescriptionData typeAccepted values
positions (M)Positions held (multiple allowed).array of objects—
positions.title (M)Position title (e.g., authorised representative, director, UBO).enumcategory: positions / position

documents​

Field (M/O/C)DescriptionData typeAccepted values
documents (C)Documents for the customer or applicant.array of objectsExamples: PROOF_OF_BUSINESS, OWNERSHIP_CHART (varies by flow)
documents.type (C)Document type.enumcategory: documentType
documents.fields (C)File IDs returned by the Upload Document endpoint.——

stakeholders​

Field (M/O/C)DescriptionData typeAccepted values
stakeholders (O)Stakeholders who hold positions in the corporate customer (as shown in official records).objectAt least one control prong must exist between applicant and individual stakeholder.
stakeholders.individual (O)Individual stakeholders (natural persons).array of objects—
stakeholders.corporate (O)Corporate stakeholders (organizations).array of objects—

bankAccountDetails​

Field (M/O/C)DescriptionData typeAccepted values
bankAccountDetails (M)Bank account details used to return funds (returns/refunds).object—
bankAccountDetails.accountName (M)Account holder name as registered with the bank.stringAlphanumeric plus: & . , ( ) _ ' / -; max 140 chars
bankAccountDetails.accountNumber (M)Bank account number for returns/refunds.stringAlphanumeric; max 35 chars
bankAccountDetails.bankCountry (M)Country where the bank account is held (ISO 3166-1 alpha-2).stringcategory: countryName
bankAccountDetails.bankAccountType (C)Bank account type (e.g., savings, checking, current).stringUse the Bene schema endpoint to fetch exact requirements.
bankAccountDetails.bankName (C)Full legal bank name.stringMax 255 chars
bankAccountDetails.currency (M)Bank account currency (ISO 4217).stringExample: USD, INR
bankAccountDetails.routingCodes.type (M)Routing identifier type.stringACH CODE, SWIFT
bankAccountDetails.routingCodes.value (M)Routing identifier value for the specified type.string—

deviceDetails​

Field (M/O/C)DescriptionData typeAccepted values
deviceDetails (M)Device/session details (security/risk).object—
deviceDetails.ipCountryCode (M)Country of origin for the IP address.enumcategory: countryName
deviceDetails.deviceInfo (M)Device operating system information.string—
deviceDetails.ipAddress (M)Device IP address.stringValid IPv4 address
deviceDetails.sessionId (M)Session ID that initiated the request.string—

declarations​

Field (M/O/C)DescriptionData typeAccepted values
applicantDeclaration (M)Applicant confirmation they accept the declaration.booleanMust be true
applicantDeclarationTimeStamp (M)Timestamp when the declaration was accepted.date—

tags​

Field (M/O/C)DescriptionData typeAccepted values
tags (O)User-defined metadata.object—
tags.key (O)User-defined key.stringExample: merchantID
tags.value (O)User-defined value.stringExample: MID123

Note : For all data type as enum, please refer to the category mentioned in the column - “Accepted values” in the above table and pass that as a query parameter to the <FetchConstant> API. The API response contains an array of code-description pairs that are valid for the given field. Please refer to the sample request for more clarity.

Sample Request​

Sample Request - Individual Customer​

{
        "type": "individual",
        "kycType": "full",
        "region": "US",
        "externalId": "C2ZfvtLAek9FKMmSHY",
        "firstName": "Sharma",
        "middleName": "",
        "lastName": "Test",
        "email": "pasumarthi.sashank+480@nium.com",
        "nationality": "FR",        
        "dateOfBirth": "2000-08-01",        
        "mobile": "2000000467",
        "mobileCountryCode": "31",  
        "applicantDeclaration": true,
        "applicantDeclarationTimeStamp": "2025-08-20 15:49:30",
        "tags": [
            {
                "key": "testing",
                "value": "Automation"
            },
            {
                "key": "key1",
                "value": "value1"
            }
        ],
        "deviceDetails": {
            "ipCountryCode": "us",
            "deviceInfo": "MAC",
            "ipAddress": "192.168.1.16",
            "sessionId": "hello-world"
        },
        "expectedAccountUsage": {
            "intendedUsesDescription": "",
            "credit": {
                "monthlyTransactionVolume": "MVUS01",                
                "topTransactionCountries": [
                    "SG"
                ]
            },
            "intendedUses": [
                "IU104"
            ],
            "debit": {
                "monthlyTransactionVolume": "MVUS01",                
                "topTransactionCountries": [
                    "SG"
                ]
            }
        },
        "bankAccountDetails": {
            "accountName": "Shane Sahrma",
            "bankName": "Bank of Australia Limited",
            "accountNumber": "77802",
            "bankCountry": "US",
            "currency": "USD",
            "bankAccountType": "saving",
            "routingCodes": [
                {
                    "type": "ACH CODE",
                    "value": "BOSHHKHH"
                }
            ]
        },
        "billingAddress": {
            "addressLine1": "Test Add 123, Building 1, Block 2, Area 3",
            "streetType" : "street type",
            "addressLine2": "Test Add 123, Building 1, Block 2, Area 3",
            "city": "Lorem ipsum dolor sit amet, consectetuer.",
            "state": "ddfd",
            "postcode": "SW1W",
            "country": "US"
        }
    }

Sample Request - Corporate Customer​

{
    "type": "corporate",
    "kycType": "full",
    "region": "US",
    "businessName": "ABC corporation",
    "businessRegistrationNumber": "12-3456789",
    "registeredDate": "2024-05-21",    
    "registeredCountry": "US",
    "website": "www.idfc348.com",
    "isMultiLayeredCompany": false,
    "listedExchange":" Listed Exchange value"
    "businessType": "public_company",
    "bankAccountDetails": {
        "accountName": "Name",
        "bankName": "Bank of Australia Limited",
        "accountNumber": "GB29NWBK6016133926820",
        "currency": "USD",
        "bankAccountType": "saving",
        "bankCountry": "US",
        "routingCodes": [
            {
                "type": "ACH CODE",
                "value": "DBSSSGSG"
            }
        ]
        },    
    "applicantDeclaration": true,
    "applicantDeclarationTimeStamp": "2025-08-20 15:49:30",
    "addresses": {
        "isBusinessAddressSameAsRegisteredAddress": false,
        "registeredAddress": {
            "addressLine1": "addressLine1",
            "addressLine2": "addressLine2",           
            "city": "city",
            "state": "US-AL",
            "postcode": "35203",
            "country": "US"
        },
        "businessAddress": {
            "addressLine1": "busaddressLine1",
            "addressLine2": "addressLine2",            
            "city": "city",
            "state": "US-AK",
            "postcode": "35203",
            "country": "US"
        }
    },
    "applicant": {        
        "firstName": "applicantFirst",
        "middleName": "applicantMiddle",
        "lastName": "applicantLast",
        "dateOfBirth": "1990-04-21",
        "nationality": "US",
        "email": "test.shank@trin.com",
        "mobile": "7337223608",
        "mobileCountryCode": "65",
        "sharePercentage": 98,
        "address": {
            "addressLine1": "applicantLine1",
            "addressLine2": "applicantLine2",           
            "city": "applicantCity",
            "state": "FR-20R",
            "postcode": "478547",
            "country": "FR"
        }, 
        "documents": [
            {
                "type": "power_of_attorney",
                "fileIds": [
                    "087244f3-b4f9-4c54-92df-b472123a6166"
                ]
            }
        ],
        "positions": [
            {
                "title": "officer",
                "startDate": "2025-04-21"
            }
        ]
    },
    "stakeholders": {
        "individual": [
            {
                "externalId": "10ab1818-ef2d-44ee-96c0-7d367842d861",
                "firstName": "stake1",
                "middleName": "stake1Mid",
                "lastName": "stake1Last",
                "dateOfBirth": "1990-04-21",               
                "nationality": "LT",
                "email": "test@nium.com",
                "mobile": "8106869840",
                "mobileCountryCode": "65",
                "sharePercentage": 80,
                "address": {
                    "addressLine1": "indiviAdd1",
                    "addressLine2": "indiviAdd2",                    
                    "city": "indiviCity",
                    "state": "US-CA",
                    "postcode": "63535",
                    "country": "US"
                },                
                "positions": [
                    {
                        "title": "director",
                        "startDate": "2025-04-21"
                    }
                ]
            },       
            {
                "externalId": "10ab1818-ef2d-44ee-96c0-7d367842d864",
                "firstName": "stake2",
                "middleName": "stake2Middle1",
                "lastName": "stake2Last1",
                "dateOfBirth": "2000-04-21",
                "nationality": "AU",
                "email": "test@nium.com",
                "mobile": "65656565656",
                "mobileCountryCode": "65",
                "sharePercentage": 80,
                "address": {
                    "addressLine1": "indiviAdd1",
                    "addressLine2": "indiviAdd2",                    
                    "city": "indiviCity",
                    "state": "FR-20R",
                    "postcode": "63535",
                    "country": "FR"
                },  
                "positions": [
                    {
                        "title": "SETTLOR",
                        "startDate": "2025-04-21"
                    }
                ]
            }
        ],
        "corporate": [
            {
                "externalId": "90ab1818-ef2d-44ee-96c0-7d367842d869",
                "businessName": "ABC Pvt Ltd",
                "businessRegistrationNumber": "BRN123456",
                "listedExchange": " Listed Exchange category"
                "registeredCountry": "SG",
                "positions": [
                    {
                        "title": "UBO"
                    }
                ]
            }
        ]
    },
    "natureOfBusiness": {
        "operatingCountries": [
            "EU"
        ],
        "industryCodes": [
            "IS134"
        ],
        "industryDescription": "<business Description>"
    },
    "expectedAccountUsage": {
        "intendedUses": [
            "IU001"
        ],
        "intendedUsesDescription": "intendedUsesDescription_78d7fdff1d03",
        "credit": {
            "monthlyTransactionVolume": "MVUS01",
            "monthlyTransactions": "ATC01",
            "averageTransactionValue": "ATVUS01",
            "topTransactionCountries": [
                "SG"
            ],            
        },
        "debit": {
            "monthlyTransactionVolume": "MVUS01",
            "monthlyTransactions": "ATC01",
            "averageTransactionValue": "ATVUS01",
            "topTransactionCountries": [
                "SG"
            ],            
        }
    },
    "sizeOfBusiness": {
        "totalEmployees": "EM006",
        "annualTurnover": "EU012"
    },
    "deviceDetails": {
        "ipCountryCode": "sg",
        "deviceInfo": "MAC",
        "ipAddress": "192.168.1.1",
        "sessionId": "40531ac01a6f11edafc28dba55d51275"
    },
    "tags": [
        {
            "key": "key_67cef24340df",
            "value": "value_56606dcf8aa4"
        }
    ],
    "tradeName": "tradeName_f57f429a7dfb",
    "documents": [
        {
            "type": "business_registration_doc",
            "fileIds": [
                "787244f3-b4f9-4c54-02af-b472123a6067"
            ]
        }
    ]
}

Responses​

Successful Response​

Individual Customer - Sample Response​

{
    "wallets": [
        {
            "walletHashId": "a2f984d9-c978-4ec7-9dff-7281644efd65",
            "walletType": "base"
        }
    ],
    "customerHashId": "bec92c44-de95-4f09-8b54-3004548b6643",
    "status": "pending",
    "subStatus": null,
    "type": "individual",
    "kycType": "full",
    "region": "US",
    "externalId": "C2ZfvtLAek9FKMmSHY",
    "tags": [
        {
            "key": "testing",
            "value": "Automation"
        },
        {
            "key": "key1",
            "value": "value1"
        }
    ],
    "segment": null,
    "firstName": "Sharma",
    "middleName": "",
    "lastName": "Test",
    "email": "pasumarthi.sashank+480@nium.com",
    "nationality": "FR",
    "dateOfBirth": "2000-08-01",
    "mobile": "2000000467",
    "mobileCountryCode": "31",       
    "deviceDetails": {
        "ipCountryCode": "sg",
        "deviceInfo": "MAC",
        "ipAddress": "192.168.1.16",
        "sessionId": "hello-world"
    },
    "expectedAccountUsage": {
        "intendedUses": [
            "IU104"
        ],
        "intendedUsesDescription": "",
        "credit": {
            "averageTransactionValue": "",
            "monthlyTransactionVolume": "MVUS01",
            "topTransactionCountries": [
                "GB"
            ]
        },
        "debit": {
            "averageTransactionValue": "ATVUS01",
            "monthlyTransactionVolume": "MVUS01",
            "topTransactionCountries": [
                "GB"
            ]
        }
    },
    "bankAccountDetails": {
        "accountName": "Shane Sahrma",
        "accountNumber": "xxxxx",
        "bankAccountType": "saving",
        "bankName": "Bank of Australia Limited",
        "bankCountry": "US",
        "currency": "USD",
        "routingCodes": [
            {
                "type": "ACH CODE",
                "value": "xxxxxxxx"
            }
        ]
    },
    "billingAddress": {
        "addressLine1": "Test Add 123, Building 1, Block 2, Area 3",
        "addressLine2": "Test Add 123, Building 1, Block 2, Area 3",        
        "city": "Lorem ipsum dolor sit amet, consectetuer.",
        "postcode": "SW1W",
        "country": "US",
        "state": "ddfd"
    },
    "kycMode": null,
    "documents": null
}

Corporate Customer - Sample Response​

{
    "wallets": [
        {
            "walletHashId": "d2b709b2-be2b-46ac-aade-3132da8d534e",
            "walletType": "base"
        }
    ],
    "customerHashId": "14235ce5-a979-4d22-9692-2bdaf486f2d1",
    "status": "pending",
    "subStatus": null,
    "type": "corporate",
    "kycType": "full",
    "region": "US",
    "externalId": null,
    "tags": [
        {
            "key": "key_67cef24340df",
            "value": "value_56606dcf8aa4"
        }
    ],
    "segment": null,
    "businessName": "ABC Pvt Ltd",
    "businessRegistrationNumber": "ABC26_127",
    "registeredDate": "2024-05-21",
    "registeredCountry": "SG",
    "website": "www.idfc348.com",
    "businessType": "public_company",
    "applicantDeclaration": true,
    "applicantDeclarationTimeStamp": "2025-08-20 15:49:30",
    "tradeName": "tradeName_f57f429a7dfb",
    "isMultiLayeredCompany": false,
    "addresses": {
        "registeredAddress": {
            "addressLine1": "addressLine1",
            "addressLine2": "addressLine2",
            "city": "city",
            "postcode": "4857832",
            "country": "FR",
            "state": "FR-20R"
        },
        "isBusinessAddressSameAsRegisteredAddress": false,
        "businessAddress": {
            "addressLine1": "busaddressLine1",
            "addressLine2": "addressLine2",
            "city": "city",
            "postcode": "387593",
            "country": "FR",
            "state": "FR-20R"
        }
    },
    "natureOfBusiness": {
        "operatingCountries": [
            "SG"
        ],
        "industryCodes": [
            "IS134"
        ],
        "industryDescription": "industryDescription_864de5f58049"
    },
    "expectedAccountUsage": {
        "intendedUses": [
            "IU001"
        ],
        "intendedUsesDescription": "intendedUsesDescription_78d7fdff1d03",
        "credit": {
            "averageTransactionValue": "ATVUS01",
            "monthlyTransactionVolume": "MVUS01",
            "monthlyTransactions": "ATC01",
            "topTransactionCountries": [
                "SG"
            ],
            "topRemitters": [
                "TEST"
            ]
        },
        "debit": {
            "averageTransactionValue": "ATVUS01",
            "monthlyTransactionVolume": "MVUS01",
            "monthlyTransactions": "ATC01",
            "topTransactionCountries": [
                "SG"
            ],
            "topBeneficiaries": [
                "topBeneficiaries_7aaf5e207bab"
            ]
        }
    },
    "sizeOfBusiness": {
        "totalEmployees": "EM006",
        "annualTurnover": "EU012"
    },
    "deviceDetails": {
        "ipCountryCode": "us",
        "deviceInfo": "MAC",
        "ipAddress": "192.168.1.1",
        "sessionId": "40531ac01a6f11edafc28dba55d51275"
    },
    "bankAccountDetails": {
        "accountName": "Name",
        "accountNumber": "xxxxxxxxxxxxxxxxxxxxx",
        "bankAccountType": "saving",
        "bankName": "Bank of Australia Limited",
        "bankCountry": "US",
        "currency": "USD",
        "routingCodes": [
            {
                "type": "ACH Code",
                "value": "xxxxxxxx"
            }
        ]
    },
    "applicant": {
        "externalId": null,
        "firstName": "applicantFirst",
        "middleName": "applicantMiddle",
        "lastName": "applicantLast",
        "dateOfBirth": "1990-04-21",
        "nationality": "SG",
        "email": "test@nium.com",
        "mobile": "7337223608",
        "mobileCountryCode": "65",
        "sharePercentage": 98,
        "address": {
            "addressLine1": "applicantLine1",
            "addressLine2": "applicantLine2",
            "city": "applicantCity",
            "postcode": "478547",
            "country": "FR",
            "state": "FR-20R"
        },        
        "positions": [
            {
                "title": "ubo",
                "startDate": "2025-04-21"
            }
        ],        
        "documents": [
            {
                "type": "power_of_attorney",
                "fileIds": [
                    "087244f3-b4f9-4c54-92df-b472123a6166"
                ],
                "identificationNumber": null,
                "issuanceCountry": null,
                "expiryDate": null
            }
        ],
        "referenceId": "b4b42891-29c3-4cbb-a6eb-236e2a491598"
    },
    "stakeholders": {
        "individual": [
            {
                "externalId": "10ab1818-ef2d-44ee-96c0-7d367842d861",
                "firstName": "stake1",
                "middleName": "stake1Mid",
                "lastName": "stake1Last",
                "dateOfBirth": "1990-04-21",
                "nationality": "LT",
                "email": "test@nium.com",
                "mobile": "8106869840",
                "mobileCountryCode": "65",
                "sharePercentage": 80,
                "address": {
                    "addressLine1": "indiviAdd1",
                    "addressLine2": "indiviAdd2",
                    "city": "indiviCity",
                    "postcode": "63535",
                    "country": "FR",
                    "state": "FR-20R"
                },
                "positions": [
                    {
                        "title": "DIRECTOR",
                        "startDate": "2025-04-21"
                    }
                ],
                "kycMode": null,
                "documents": null,
                "referenceId": "8d8a36d9-0909-43e9-88a4-7907454afccc"
            }          
       ],
        "corporate": [
            {
                "externalId": "90ab1818-ef2d-44ee-96c0-7d367842d869",
                "businessName": "ABC Pvt Ltd",
                "businessRegistrationNumber": "BRN123456",
                "registeredCountry": "SG",
                "sharePercentage": null,
                "positions": [
                    {
                        "title": "UBO",
                        "startDate": null
                    }
                ],
                "referenceId": "5d866918-06d6-44fb-bf34-0041ecfb6f3b"
            },
         ]
    },
    "documents": [
        {
            "type": "business_registration_doc",
            "fileIds": [
                "787244f3-b4f9-4c54-02af-b472123a6067"
            ]
        }
    ]
}

Failure Response​

ScenarioError codeHTTP codeDescriptionComments
Missing mandatory fieldsmissing_required_fields400Position title is invalid for stakeholder AAAA BBB. Value: DIRECTORRRRRThe response includes a field attribute showing the exact path, for example: stakeholders.individual[0].positions[1].title.
externalId must be unique for stakeholders and applicantduplicate_externalId400externalId is duplicated for stakeholder AAAA BBB. Value: XXXX-YYYMultiple error objects may be returned—one per duplicate. The response includes the field path, for example: applicant.externalId.
Client (as customer) not available before MinKYC creationincomplete_client_setup422Request cannot be accepted because compliance is not completed for the auto-sweep customer.—
KYC incomplete for client as customerincomplete_client_setup422Request cannot be accepted because the auto-sweep customer is not found.—
Field value not acceptedinvalid_input400Field A is invalid for stakeholder AAAA BBB. Value: XXXXXX.—
Customer already existscustomer_exists400Customer already exists for the provided %fieldName.The response may include a field value such as externalId or businessName.