Business Customer Prefill
Overview
Through this solution, Noah enables you to provide KYB details for a Business Customer via API. Submit any KYB data you have already collected and the information you provide will undergo manual review by Noah. Once the Business Customer is approved, you will receive a Customer Event webhook confirming approval. Additional onboarding questions may be required during the review process.
Use the POST onboarding/:CustomerID/prefill endpoint to prefill business customer data, with the type parameter set to BusinessCustomerPrefill.
Complete the onboarding process using the POST onboarding/:CustomerID endpoint to collect:
- Missing compliance data through dynamic forms or hosted sessions
- Terms and Conditions acceptance for regulatory compliance
- Fiat currency selection configured during hosted onboarding
Note: Noah automatically identifies gaps in compliance data and collects only what's missing.
For more details on this process, see the Hosted Onboarding recipe.
Recipe
Implement a scenario as described above by following the steps below.
1. Provide Business Customer Details
Provide the applicable business customer details via the POST onboarding/:CustomerID/prefill endpoint. In this step, you query the POST onboarding/:CustomerID/prefill endpoint, selecting the BusinessCustomerPrefill type:
curl -L 'https://api.sandbox.noah.com/v1/onboarding/:CustomerID/prefill' \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: <X-Api-Key>' \
-d '{
"Type": "BusinessCustomerPrefill",
"RegistrationCountry": "US",
"CompanyName": "Example Corp",
"RegistrationNumber": "12345678",
"LegalAddress": {
"Street": "123 Main St",
"City": "New York",
"PostCode": "10001",
"State": "NY",
"Country": "US"
},
"IncorporationDate": "2020-01-15",
"EntityType": "Corporation",
"TaxID": "12-3456789",
"PrimaryWebsite": "https://example.com",
"Associates": [
{
"ID": "550e8400-e29b-41d4-a716-446655440000",
"RelationshipTypes": ["UBO", "Representative"],
"FullName": {
"FirstName": "John",
"LastName": "Doe"
},
"DateOfBirth": "1980-05-15"
}
]
}'
As can be seen above, include your API Key in the header, along with all the business customer details that are relevant in your context.
While the above is a typical request in this context, below is a comprehensive request, with all the available parameters and comments included.
{
"Type": "BusinessCustomerPrefill",
// ISO 3166-1 alpha-2 country code
"RegistrationCountry": "US",
// Name of the company (1-100 characters)
"CompanyName": "Example Corporation Inc.",
// Registration number of the business (1-100 characters)
"RegistrationNumber": "12345678",
// Legal address of the business
"LegalAddress": {
"Street": "123 Main Street", // Street: the primary name of an address street (2-200 characters)
"Street2": "Floor 10", // Street2: the secondary name of an address street
"City": "New York", // City: name of an address city or town (1-100 characters)
"PostCode": "10001", // PostCode: the address postcode (1-20 characters)
"State": "NY", // State: the address state/province/county. For USA and Canada, state code in ISO 3166-2 code (e.g. CA) is required (1-100 characters)
"Country": "US" // ISO 3166-1 alpha-2 country code
},
// Incorporation date (YYYY-MM-DD format)
"IncorporationDate": "2020-01-15",
// Entity type for business entities
// Options: LimitedLiabilityCompany, PublicCompany, SoleProprietorship,
// Partnership, Corporation, Trust, PrivateFoundation, Charity,
// NonProfitOrganization, PublicAgency
"EntityType": "Corporation",
// Tax ID of the business (1-100 characters)
"TaxID": "12-3456789",
// Primary website of the business (1-100 characters)
"PrimaryWebsite": "https://example.com",
// Trade name of the business (DBA)
"TradeName": "Example Corp DBA",
// List of your registered foreign branches, including registered country
// and any applicable registration numbers
"RegisteredForeignBranches": [
{
"Name": "Example UK Branch", // Name of the registered foreign branch
"RegistrationCountry": "GB", // ISO 3166-1 alpha-2 country code
"RegistrationNumber": "UK987654" // Registration number of the registered foreign branch
}
],
// Primary physical address of the business
"PrimaryPhysicalAddress": {
"Street": "456 Business Ave",
"Street2": "Suite 400",
"City": "San Francisco",
"PostCode": "94105",
"State": "CA",
"Country": "US"
},
// Ownership type
// Options: Private, PublicListed, GovernmentOwned, Partnership, SoleProprietorship,
// NonProfit, Cooperative, JointVenture, ForeignOwned, Subsidiary, TrustOwned,
// CommunityOwned, FoundationOwned, LLC
"OwnershipType": "Private",
// Legal entity identifier (LEI) code of the business
"LegalEntityIdentifier": "123456789012345678XX",
// Please provide your NAICS (North American Industry Classification System) code
// If you do not have a NAICS code, please select the closest corresponding code
// that best matches your industry classification
// See: https://www.naics.com/search/
"NAICSCode": "541512",
// What will be the source of incoming funds to your account?
// Options: Revenue, Investments, LoansCredits, TradingIncome, CryptoMining,
// ClientFunds
"SourceOfFunds": "Revenue",
// Financial information in USD
"FinancialsUsd": {
// What is the estimated monthly turnover for your account, including both
// incoming and outgoing transactions?
// Options: UpTo15k, UpTo50k, UpTo100k, UpTo500k, Above500k
"EstimatedMonthlyTurnover": "UpTo100k",
// Please specify the planned value of one-time transaction
// Options: UpTo5k, UpTo15k, UpTo50k, UpTo100k, Above100k
"EstimatedTransactionValue": "UpTo50k"
},
// What is the expected frequency of transactions per month?
// Options: UpTo10, UpTo20, UpTo50, Above50
"MonthlyTransactionFrequency": "UpTo20",
// Information about UBOs (25% or more of ownership) and Representatives
"Associates": [
{
// Associate ID (UUID format)
"ID": "550e8400-e29b-41d4-a716-446655440001",
// Relationship types
// Options: UBO (Ultimate Beneficial Owner), Representative
"RelationshipTypes": ["UBO", "Representative"],
// Full name of the associate
"FullName": {
"FirstName": "John", // user's first name (1-50 characters)
"MiddleName": "Michael", // user's middle name (1-50 characters)
"LastName": "Doe" // user's last name/family name (1-50 characters)
},
// Date of birth (YYYY-MM-DD format)
"DateOfBirth": "1980-05-15",
// Identity documents
"Identities": [
{
"IssuingCountry": "US", // Issuing country of the identity, ISO 3166-1 alpha-2 country code
"IDNumber": "123456789", // ID number (1-36 characters)
// IDType options: DrivingLicense, NationalIDCard,
// Passport, AddressProof, ResidencePermit, TaxID
"IDType": "Passport",
"IssuedDate": "2020-01-01", // Issue date (YYYY-MM-DD format)
"ExpiryDate": "2030-01-01" // Expiry date (YYYY-MM-DD format)
}
],
// Tax residence country (ISO 3166-1 alpha-2 country code)
"TaxResidenceCountry": "US",
// UBO email address (1-100 characters)
"Email": "john.doe@example.com",
// Phone number (format: +[0-9]{6,15})
"PhoneNumber": "+12125551234",
// Residential address
"ResidentialAddress": {
"Street": "789 Residential Blvd",
"City": "Brooklyn",
"PostCode": "11201",
"State": "NY",
"Country": "US"
},
// UBO specific information
"UBO": {
// Percentage of ownership held by the UBO (0-100)
"OwnershipPercentage": 40
}
},
{
"ID": "550e8400-e29b-41d4-a716-446655440002",
"RelationshipTypes": ["UBO"],
"FullName": {
"FirstName": "Jane",
"LastName": "Smith"
},
"DateOfBirth": "1985-08-20",
"Identities": [
{
"IssuingCountry": "US",
"IDNumber": "987654321",
"IDType": "DrivingLicense",
"ExpiryDate": "2028-08-20"
}
],
"TaxResidenceCountry": "US",
"Email": "jane.smith@example.com",
"PhoneNumber": "+12125555678",
"ResidentialAddress": {
"Street": "321 Park Avenue",
"City": "New York",
"PostCode": "10022",
"State": "NY",
"Country": "US"
},
"UBO": {
"OwnershipPercentage": 35
}
}
],
// Information about Corporate Shareholders (25% or more of ownership)
"BusinessAssociates": [
{
// Shareholder ID (UUID format)
"ID": "550e8400-e29b-41d4-a716-446655440003",
// Shareholder's registration country (ISO 3166-1 alpha-2 country code)
"RegistrationCountry": "DE",
// Shareholder's company name
"CompanyName": "Corporate Shareholder GmbH",
// Shareholder's registration number
"RegistrationNumber": "HRB123456",
// Entity type (see EntityEnum options above)
"EntityType": "Corporation",
// Incorporation date (YYYY-MM-DD format)
"IncorporationDate": "2015-03-10",
// Shareholder's ownership percentage (0-100)
"OwnershipPercentage": 25
}
],
// This section is required if the business is subject to regulatory oversight
// that requires compliance with Anti-Money Laundering (AML) regulations
"AMLCTFRegulated": {
// Please provide the name of the supervisory authority
"SupervisoryAuthorityName": "Financial Crimes Enforcement Network",
// Please provide the license number
"LicenseNumber": "MSB-123456789",
// Has the business appointed an MLRO (Money Laundering Reporting Officer)?
"HasAppointedMLRO": true,
// Indicate in % how many low-risk, medium-risk, and high-risk customers
// the company has
"CustomerRiskSplit": {
"LowRisk": 70, // Low-risk customers (percentage)
"MediumRisk": 25, // Medium-risk customers (percentage)
"HighRisk": 5 // High-risk customers (percentage)
},
// Does the company prohibit the opening and keeping of anonymous and fictitious
// named accounts?
"ProhibitsAnonOrFictiousAccounts": true,
// Does the company prohibit the opening and keeping of accounts for unlicensed
// or shell customers?
"ProhibitsAccountsForUnlicensedOrShellCustomers": true,
// If the company verifies the identity of the customer (including ultimate
// beneficial owners, company directors and representatives),
// specify whether the company uses an automated or manual screening method
"CustomerIdentityVerification": {
// Does the company integrate an automated or manual screening?
// Options: Automated, Manual
"Method": "Automated",
// If the method is Automated, please specify the system/software
"System": "Sumsub KYC Platform"
},
// If the company screens its customers against PEP and sanctions,
// specify whether the company uses an automated or manual PEP and sanctions
// screening method
"PEPAndSanctions": {
// Options: Automated, Manual
"Method": "Automated",
"System": "Dow Jones Risk & Compliance"
},
// If the company does not screen its customers against PEP and sanctions,
// indicate what sanctions lists the Company uses to screen customers
"SanctionLists": [
"OFAC SDN List",
"EU Sanctions List",
"UN Sanctions List"
],
// Does the due diligence process result in customers receiving a risk
// classification?
"CustomerRiskClassificationFromDueDiligence": true,
// Does the company apply an enhanced due diligence process?
"EDDProcess": true,
// Does the Company integrate automated or manual transaction monitoring methods?
"TransactionMonitoring": {
"Method": "Automated",
"System": "ComplyAdvantage Transaction Monitoring"
},
// Does the company have procedures to identify transactions structured to avoid
// large cash/transactions reporting requirements?
"ProceduresForTransactionMonitoring": true,
// Has the company been subject to a money laundering or terrorist financing
// investigation? If yes, please provide further details
"SubjectToMLOrTFInvestigation": "No previous investigations",
// Has the company been the subject, in the past two years, of regulatory
// enforcement for inadequate AML/CTF policies and procedures
// and/or breaches of AML/CTF? If yes, please provide further details
"SubjectToRegulatoryEnforcementPast2Years": "No regulatory enforcement actions",
// Does the company confirm that it does not provide services to individuals or
// entities which are residents of sanctioned countries
"ConfirmsNoServiceToSanctionedCountries": true,
// If the client's funds are transferred to the Company's external wallet
// or bank account, will they be accessible through:
// ClosedLoop – Funds can only be withdrawn by the client as instructed
// OpenLoop – Funds can be accessed and used freely by the client
// NotTransferred - Client funds will not be transferred to the external
// company wallet
// Options: ClosedLoop, OpenLoop, NotTransferred
"ClientFundsAccessibility": "ClosedLoop",
// Has the company had AML/CTF audit?
"AMLCTFAudit": true,
// If AMLCTFAudit is false, please clarify when the AML/CTF audit is
// planned (YYYY-MM-DD format)
"AuditDate": "2024-06-15"
}
}
2. Initiate a Hosted Onboarding Session
Submit a call to the POST onboarding/:CustomerID endpoint, to collect the prerequisite Terms and Conditions acceptance from your customer (and any missing data as per the prefill above):
curl -L 'https://api.sandbox.noah.com/v1/onboarding/:CustomerID' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Api-Key: <X-Api-Key>' \
-d '{
"Metadata": {},
"ReturnURL": "https://example.com",
"FiatOptions": [
{
"FiatCurrencyCode": "USD"
}
]
}'
As can be seen above, in your request, include your API Key in the header along with a CustomerID, the URL to which the user is redirected at the end of the Hosted Onboarding session, and the list of fiat options to be supported by the customer.
note
Noah expects a full ReturnURL value, including the https://.
View the POST onboarding/:CustomerID endpoint for detailed instructions on initiating a session.
The response will consist of a HostedURL, where the Hosted Onboarding session is ready for the
customer to enter their details:
{"HostedURL":"https://checkout.sandbox.noah.com/kyc?session=xyz"}
3. Direct the Customer to Hosted Onboarding
Redirect your customer to the HostedURL to enter their details in the Hosted Onboarding session.
4. Customer Status Updates via Webhooks
Set up to receive notifications through webhooks about the status of the Hosted Onboarding session,
which can be Pending, Approved, or Declined.
For more details, see Customer Webhooks.
5. Close the Hosted Onboarding Session
Noah emits a postMessage once the onboarding process is complete. You can listen to this event in your application, as follows:
window.addEventListener('message', (event) => {
if (event.data?.type === 'kycCompleted') {
closeHostedSession(); // <-- Replace this with platform-specific close method
}
});
tip
- The message sent is:
{ type: 'kycCompleted' } - It is sent once a valid KYC review status is detected.