US request examples
To onboard your entity, you can call the Onboard Corporate Customer API. For an example call that you can customize with your information, see:
Public companies
The following is an API request example call where businessType = PUBLIC_COMPANY.
{
"region": "US",
"businessDetails": {
"businessName": "Jubliant Public Corporations10",
"businessRegistrationNumber": "52940398934",
"businessType": "PUBLIC_COMPANY",
"description": "Public company in US to facilitate agro payments",
"legalDetails": {
"registeredCountry": "US",
"registeredDate": "2021-08-10",
"listedExchange": "EX103"
},
"stockSymbol": "MLFP",
"addresses": {
"registeredAddress": {
"addressLine1": "999 Park Street",
"addressLine2": "Near Airport",
"city": "Newark",
"state": "New Jersey",
"country": "US",
"postcode": "07071"
}
},
"documentDetails": [
{
"documentType": "PROOF_OF_EXISTENCE",
"document": [
{
"fileName": "POE",
"fileType": "application/pdf",
"document": "iVBORw0KGgoAAAANSUhEUgAAAOEAAADhCAMAAAAJbSJIAAAAJFBMVEX/////QAAAAADnOQCnIAD19vZSXV7dNgCkpqf1PQDNzs7P0NCe8r63AAAAoUlEQVR4nO3Wiw3DIAwFQGI+Ccn++1ZNM0IpEr2b4D1ZGKcEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAMC31FpnRxjqbBHRztkxxjmi5J5LHLODjHLGvr3tcc2OMkgr20dps6OMUSM/DXOsuW5q9KdhX7bh6jNc/x3+wS5d/z9M6bpvmmUneFv9LgUAAAAAAAAAAAAAAAAAAAAAAAAAAAAA+K0XNkoBrhhCyKYAAAAASUVORK5CYII="
}
]
}
],
"stakeholders": [
{
"stakeholderDetails": {
"kycMode": "MANUAL_KYC",
"firstName": "MARTHA",
"lastName": "JONES",
"nationality": "US",
"dateOfBirth": "1961-08-11",
"professionalDetails": [
{
"position": "CONTROL_PRONG"
}
],
"address": {
"addressLine1": "Park Street",
"city": "Newark",
"state": "New Jersey",
"country": "US",
"postcode": "07071"
},
"documentDetails": [
{
"documentType": "NATIONAL_ID",
"documentNumber": "555456789",
"documentIssuanceCountry": "US",
"document": [
{
"fileName": "POI.png",
"fileType": "images/png",
"document": "gtudfsdfgegetg"
}
]
}
]
}
},
{
"businessPartner": {
"businessName": "Lightsaber Fintech Venture",
"businessRegistrationNumber": "987609384",
"businessEntityType": "UBO",
"sharePercentage": "15",
"legalDetails": {
"registeredCountry": "US"
}
}
}
],
"applicantDetails": {
"kycMode": "E_KYC",
"firstName": "John",
"lastName": "Arch",
"nationality": "US",
"dateOfBirth": "1982-07-10",
"professionalDetails": [
{
"position": "SIGNATORY"
}
],
"contactDetails": {
"countryCode": "US",
"contactNo": "9974922222",
"email": "[email protected]"
},
"address": {
"addressLine1": "Apt X 99, Green Avenue",
"city": "West Hartford",
"state": "Connecticut",
"postcode": "06110",
"country": "US"
},
"documentDetails": [
{
"documentType": "NATIONAL_ID",
"documentNumber": "123456789",
"documentIssuanceCountry": "US"
}
],
"additionalInfo": {
"applicantDeclaration": "Yes"
}
},
"additionalInfo": {
"isSameBusinessAddress": "Yes"
}
},
"riskAssessmentInfo": {
"totalEmployees": "EM009",
"annualTurnover": "US011",
"industrySector": "IS144",
"intendedUseOfAccount": "IU003",
"countryOfOperation": [
"US",
"SG",
"HK",
"AU"
],
"transactionCountries": [
"SG",
"AU",
"EU"
]
},
"tags": [
{
"key": "tag1",
"value": "tag1value"
},
{
"key": "tag2",
"value": "tag2value"
}
]
}
Trusts
The following is an API request example call where businessType = TRUST.
{
"region": "US",
"businessDetails": {
"businessName": "Farhampton Children Trust25",
"businessRegistrationNumber": "52940397834",
"businessType": "TRUST",
"description": "Trust in US to support specially abled children",
"legalDetails": {
"registeredCountry": "US",
"registeredDate": "2021-08-10"
},
"addresses": {
"registeredAddress": {
"addressLine1": "999 Park Street",
"addressLine2": "Near Airport",
"city": "Newark",
"state": "New Jersey",
"country": "US",
"postcode": "07071"
}
},
"regulatoryDetails": {
"unregulatedTrustType": [
"TT002"
]
},
"documentDetails": [
{
"documentType": "TRUST_DEED",
"document": [
{
"fileName": "TRUSTDEED",
"fileType": "application/pdf",
"document": "iVBORw0KGgoAAAANSUhEUgAAAOEAAADhCAMAAAAJbSJIAAAAJFBMVEX/////QAAAAADnOQCnIAD19vZSXV7dNgCkpqf1PQDNzs7P0NCe8r63AAAAoUlEQVR4nO3Wiw3DIAwFQGI+Ccn++1ZNM0IpEr2b4D1ZGKcEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAMC31FpnRxjqbBHRztkxxjmi5J5LHLODjHLGvr3tcc2OMkgr20dps6OMUSM/DXOsuW5q9KdhX7bh6jNc/x3+wS5d/z9M6bpvmmUneFv9LgUAAAAAAAAAAAAAAAAAAAAAAAAAAAAA+K0XNkoBrhhCyKYAAAAASUVORK5CYII="
}
]
}
],
"stakeholders": [
{
"stakeholderDetails": {
"kycMode": "MANUAL_KYC",
"firstName": "KATIE",
"lastName": "WINCELET",
"nationality": "US",
"dateOfBirth": "1961-08-11",
"professionalDetails": [
{
"position": "CONTROL_PRONG"
}
],
"address": {
"addressLine1": "Park Street",
"city": "Newark",
"state": "New Jersey",
"country": "US",
"postcode": "07071"
},
"documentDetails": [
{
"documentType": "NATIONAL_ID",
"documentNumber": "555456789",
"documentIssuanceCountry": "US",
"document": [
{
"fileName": "POI.png",
"fileType": "images/png",
"document": "gtudfsdfgegetg"
}
]
}
]
}
},
{
"businessPartner": {
"businessName": "Amanda Corp",
"businessRegistrationNumber": "987609384",
"businessEntityType": "UBO",
"sharePercentage": "15",
"legalDetails": {
"registeredCountry": "US"
}
}
}
],
"applicantDetails": {
"kycMode": "E_KYC",
"firstName": "Tom",
"lastName": "Cruise",
"nationality": "US",
"dateOfBirth": "1982-07-10",
"professionalDetails": [
{
"position": "SIGNATORY"
}
],
"contactDetails": {
"countryCode": "US",
"contactNo": "9974922222",
"email": "[email protected]"
},
"address": {
"addressLine1": "Apt X 99, Green Avenue",
"city": "West Hartford",
"state": "Connecticut",
"postcode": "06110",
"country": "US"
},
"documentDetails": [
{
"documentType": "NATIONAL_ID",
"documentNumber": "123456789",
"documentIssuanceCountry": "US"
}
],
"additionalInfo": {
"applicantDeclaration": "Yes"
}
},
"additionalInfo": {
"isSameBusinessAddress": "Yes"
}
},
"riskAssessmentInfo": {
"totalEmployees": "EM009",
"annualTurnover": "US011",
"industrySector": "IS144",
"intendedUseOfAccount": "IU003",
"countryOfOperation": [
"US",
"SG",
"HK",
"AU"
],
"transactionCountries": [
"SG",
"AU",
"EU"
]
},
"tags": [
{
"key": "tag1",
"value": "tag1value"
},
{
"key": "tag2",
"value": "tag2value"
}
]
}
Other entities
The following is an API request example call where businessType = CORPORATION. Examples for other entity types listed below are similar.
- Corporations
- Estates
- General partnerships
- Limited liability company
- Limited liability partnership firms
- Limited partnerships
- Sole traders
- Unincorporated associations
{
"region": "US",
"businessDetails": {
"businessName": "Soylent Corporation68s",
"businessRegistrationNumber": "529403988",
"businessType": "CORPORATION",
"description": "Corporation in US to facilitate payments to business",
"tradeName": "Soylent Corp",
"legalDetails": {
"registeredCountry": "US",
"registeredDate": "2021-08-10"
},
"addresses": {
"registeredAddress": {
"addressLine1": "999 Park Street",
"addressLine2": "Near Airport",
"city": "Newark",
"state": "New Jersey",
"country": "US",
"postcode": "07071"
}
},
"documentDetails": [
{
"documentType": "BUSINESS_REGISTRATION_DOC",
"document": [
{
"fileName": "BRD",
"fileType": "application/pdf",
"document": "iVBORw0KGgoAAAANSUhEUgAAAOEAAADhCAMAAAAJbSJIAAAAJFBMVEX/////QAAAAADnOQCnIAD19vZSXV7dNgCkpqf1PQDNzs7P0NCe8r63AAAAoUlEQVR4nO3Wiw3DIAwFQGI+Ccn++1ZNM0IpEr2b4D1ZGKcEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAMC31FpnRxjqbBHRztkxxjmi5J5LHLODjHLGvr3tcc2OMkgr20dps6OMUSM/DXOsuW5q9KdhX7bh6jNc/x3+wS5d/z9M6bpvmmUneFv9LgUAAAAAAAAAAAAAAAAAAAAAAAAAAAAA+K0XNkoBrhhCyKYAAAAASUVORK5CYII="
}
]
}
],
"stakeholders": [
{
"stakeholderDetails": {
"kycMode": "MANUAL_KYC",
"firstName": "MICHAEL",
"lastName": "JONES",
"nationality": "US",
"dateOfBirth": "1961-08-11",
"professionalDetails": [
{
"position": "CONTROL_PRONG"
}
],
"address": {
"addressLine1": "Park Street",
"city": "Newark",
"state": "New Jersey",
"country": "US",
"postcode": "07071"
},
"documentDetails": [
{
"documentType": "NATIONAL_ID",
"documentNumber": "555456789",
"documentIssuanceCountry": "US",
"document": [
{
"fileName": "POI.png",
"fileType": "images/png",
"document": "gtudfsdfgegetg"
}
]
}
]
}
},
{
"businessPartner": {
"businessName": "Vehement Capital Partners",
"businessRegistrationNumber": "987609384",
"businessEntityType": "UBO",
"sharePercentage": "15",
"legalDetails": {
"registeredCountry": "US"
}
}
}
],
"applicantDetails": {
"kycMode": "E_KYC",
"firstName": "Tom",
"lastName": "Arch",
"nationality": "US",
"dateOfBirth": "1982-07-10",
"professionalDetails": [
{
"position": "SIGNATORY"
}
],
"contactDetails": {
"countryCode": "US",
"contactNo": "9974922222",
"email": "[email protected]"
},
"address": {
"addressLine1": "Apt X 99, Green Avenue",
"city": "West Hartford",
"state": "Connecticut",
"postcode": "06110",
"country": "US"
},
"documentDetails": [
{
"documentType": "NATIONAL_ID",
"documentNumber": "123456789",
"documentIssuanceCountry": "US"
}
],
"additionalInfo": {
"applicantDeclaration": "Yes"
}
},
"additionalInfo": {
"isSameBusinessAddress": "Yes"
}
},
"riskAssessmentInfo": {
"totalEmployees": "EM009",
"annualTurnover": "US011",
"industrySector": "IS144",
"intendedUseOfAccount": "IU003",
"countryOfOperation": [
"US",
"SG",
"HK",
"AU"
],
"transactionCountries": [
"SG",
"AU",
"EU"
]
},
"tags": [
{
"key": "tag1",
"value": "tag1value"
},
{
"key": "tag2",
"value": "tag2value"
}
]
}
Simulate various scenarios
You can generate the following scenarios by using the below example requests to call the Onboard Corporate Customer API.
| Simulated Scenario | condition on BRN | Example |
|---|---|---|
| Auto-approval | Starts with 101 | 101567889 |
| Action required | Starts with 102 | 102567898 |
| In progress with documents required | Any BRN | 101789123 |
| In progress with redirectURL | Pattern on applicantDetails.contactDetails.contactNo |
Note:
It may take 5 to 10 minutes for you to get the next webhook after submission in sandbox.
Request example: auto-approval
{
"region": "US",
"businessDetails": {
"businessName": "TESSERACT LLC WFWEF",
"businessRegistrationNumber": "101402356",
"businessType": "LIMITED_LIABILITY_COMPANY",
"description": "Limited liability company in US for IT services",
"legalDetails": {
"registeredCountry": "US",
"registeredDate": "2021-08-10"
},
"addresses": {
"registeredAddress": {
"addressLine1": "223, Grand St.",
"addressLine2": "",
"city": "New York",
"state": "NY",
"country": "US",
"postcode": "10013"
}
},
"stakeholders": [
{
"stakeholderDetails": {
"kycMode": "E_KYC",
"firstName": "MARTHA",
"lastName": "ENGLISH REBORN",
"nationality": "US",
"dateOfBirth": "1961-08-11",
"professionalDetails": [
{
"position": "CONTROL_PRONG"
}
],
"address": {
"addressLine1": "Park Street",
"city": "Newark",
"state": "New Jersey",
"country": "US",
"postcode": "07071"
},
"documentDetails": [
{
"documentType": "NATIONAL_ID",
"documentNumber": "555456789",
"documentIssuanceCountry": "US"
}
]
}
},
{
"businessPartner": {
"businessName": "CUZEK PRIVATE VENTURES",
"businessRegistrationNumber": "987609384",
"businessEntityType": "UBO",
"sharePercentage": "15",
"legalDetails": {
"registeredCountry": "US"
}
}
}
],
"applicantDetails": {
"kycMode": "E_KYC",
"firstName": "MARTHA",
"lastName": "ENGLISH REBORN",
"nationality": "US",
"dateOfBirth": "1961-08-11",
"professionalDetails": [
{
"position": "SIGNATORY"
}
],
"contactDetails": {
"countryCode": "US",
"contactNo": "9974922222",
"email": "[email protected]"
},
"address": {
"addressLine1": "Apt X 99, Green Avenue",
"city": "West Hartford",
"state": "Connecticut",
"postcode": "06110",
"country": "US"
},
"documentDetails": [
{
"documentType": "NATIONAL_ID",
"documentNumber": "555456789",
"documentIssuanceCountry": "US"
}
],
"additionalInfo": {
"applicantDeclaration": "Yes"
}
},
"additionalInfo": {
"isSameBusinessAddress": "Yes"
}
},
"riskAssessmentInfo": {
"totalEmployees": "EM009",
"annualTurnover": "US011",
"industrySector": "IS141",
"intendedUseOfAccount": "IU003",
"countryOfOperation": [
"US",
"SG",
"HK",
"AU"
],
"transactionCountries": [
"SG",
"AU",
"EU"
]
},
"tags": [
{
"key": "tag1",
"value": "tag1value"
},
{
"key": "tag2",
"value": "tag2value"
}
]
}
Request example: action required
{
"region": "US",
"businessDetails": {
"businessName": "TESSERACT LLC WFRRF",
"businessRegistrationNumber": "102404336",
"businessType": "LIMITED_LIABILITY_COMPANY",
"description": "Limited liability company in US for IT services",
"legalDetails": {
"registeredCountry": "US",
"registeredDate": "2021-08-10"
},
"addresses": {
"registeredAddress": {
"addressLine1": "Random Address",
"addressLine2": "",
"city": "Gotham City",
"state": "NY",
"country": "US",
"postcode": "10013"
}
},
"stakeholders": [
{
"stakeholderDetails": {
"kycMode": "E_KYC",
"firstName": "MARTHA WAS",
"lastName": "ENGLISH IS",
"nationality": "US",
"dateOfBirth": "1961-08-11",
"professionalDetails": [
{
"position": "CONTROL_PRONG"
}
],
"address": {
"addressLine1": "Park Street",
"city": "Newark",
"state": "New Jersey",
"country": "US",
"postcode": "07071"
},
"documentDetails": [
{
"documentType": "NATIONAL_ID",
"documentNumber": "555456789",
"documentIssuanceCountry": "US"
}
]
}
},
{
"businessPartner": {
"businessName": "CUZEK PRIVATE VENTURES",
"businessRegistrationNumber": "987609384",
"businessEntityType": "UBO",
"sharePercentage": "15",
"legalDetails": {
"registeredCountry": "US"
}
}
}
],
"applicantDetails": {
"kycMode": "E_KYC",
"firstName": "MARTHA IS",
"lastName": "ENGLISH WAS",
"nationality": "US",
"dateOfBirth": "1961-08-11",
"professionalDetails": [
{
"position": "SIGNATORY"
}
],
"contactDetails": {
"countryCode": "US",
"contactNo": "9974922222",
"email": "[email protected]"
},
"address": {
"addressLine1": "Apt X 99, Green Avenue",
"city": "West Hartford",
"state": "Connecticut",
"postcode": "06110",
"country": "US"
},
"documentDetails": [
{
"documentType": "NATIONAL_ID",
"documentNumber": "555456789",
"documentIssuanceCountry": "US"
}
],
"additionalInfo": {
"applicantDeclaration": "Yes"
}
},
"additionalInfo": {
"isSameBusinessAddress": "Yes"
}
},
"riskAssessmentInfo": {
"totalEmployees": "EM007",
"annualTurnover": "US008",
"industrySector": "IS144",
"intendedUseOfAccount": "IU003",
"countryOfOperation": [
"US",
"SG",
"HK",
"AU"
],
"transactionCountries": [
"SG",
"AU",
"EU"
]
},
"tags": [
{
"key": "tag1",
"value": "tag1value"
},
{
"key": "tag2",
"value": "tag2value"
}
]
}
Request example: in progress with documents required
{
"region": "US",
"businessDetails": {
"businessName": "TESSERACT LLC WFWEF",
"businessRegistrationNumber": "101402356",
"businessType": "LIMITED_LIABILITY_COMPANY",
"description": "Limited liability company in US for IT services",
"legalDetails": {
"registeredCountry": "US",
"registeredDate": "2021-08-10"
},
"addresses": {
"registeredAddress": {
"addressLine1": "223, Grand St.",
"addressLine2": "",
"city": "New York",
"state": "NY",
"country": "US",
"postcode": "10013"
}
},
"stakeholders": [
{
"stakeholderDetails": {
"kycMode": "E_KYC",
"firstName": "MARTHA",
"lastName": "ENGLISH REBORN",
"nationality": "US",
"dateOfBirth": "1961-08-11",
"professionalDetails": [
{
"position": "CONTROL_PRONG"
}
],
"address": {
"addressLine1": "Park Street",
"city": "Newark",
"state": "New Jersey",
"country": "US",
"postcode": "07071"
},
"documentDetails": [
{
"documentType": "NATIONAL_ID",
"documentNumber": "555456789",
"documentIssuanceCountry": "US"
}
]
}
},
{
"businessPartner": {
"businessName": "CUZEK PRIVATE VENTURES",
"businessRegistrationNumber": "987609384",
"businessEntityType": "UBO",
"sharePercentage": "15",
"legalDetails": {
"registeredCountry": "US"
}
}
}
],
"applicantDetails": {
"kycMode": "MANUAL_KYC",
"firstName": "MARTHA",
"lastName": "ENGLISH REBORN",
"nationality": "US",
"dateOfBirth": "1961-08-11",
"professionalDetails": [
{
"position": "SIGNATORY"
}
],
"contactDetails": {
"countryCode": "US",
"contactNo": "9974922222",
"email": "[email protected]"
},
"address": {
"addressLine1": "Apt X 99, Green Avenue",
"city": "West Hartford",
"state": "Connecticut",
"postcode": "06110",
"country": "US"
},
"additionalInfo": {
"applicantDeclaration": "Yes"
}
},
"additionalInfo": {
"isSameBusinessAddress": "Yes"
}
},
"riskAssessmentInfo": {
"totalEmployees": "EM009",
"annualTurnover": "US011",
"industrySector": "IS144",
"intendedUseOfAccount": "IU003",
"countryOfOperation": [
"US",
"SG",
"HK",
"AU"
],
"transactionCountries": [
"SG",
"AU",
"EU"
]
},
"tags": [
{
"key": "tag1",
"value": "tag1value"
},
{
"key": "tag2",
"value": "tag2value"
}
]
}
Completing applicant eDocVerify
The applicant eDocVerify is done via the third-party vendor Onfido. Applicant KYC via Onfido takes place for the EU region when the KYC mode is E_DOC_VERIFY.
To simulate different success and error responses of the eDocVerify flow, use the following conditions on the applicant's phone number. In all cases, the applicant needs to open the redirect URL in their browser. You either land on the vendor’s page or receive a success/failure redirection back to your KYC redirect URL without any actions needed on the UI. The redirectURL has isSuccess, errorCode, and errorMessage parameters as described in Applicant KYC.
Based on businessDetails.applicantDetails.contactDetail.contactNumber, there are two outcomes:
First two digits of contactNumber | Resulting situation |
|---|---|
| Doesn't contain any of the simulated patterns | Onfido's sandbox page is opened and the applicant needs to complete the simulated authentication on the UI. This can be used for end-to-end testing. |
| Does contain any of the simulated patterns | The customer's browser redirects to your KYC redirect URL without the need of any actions on the UI. Redirection will contain the following Redirection parameters |
Redirection parameters
| Return code | Query parameters in the redirection |
|---|---|
| 91 | isSuccess=true ; errorCode=;errorMessage= |
| 41 | isSuccess = false ; errorCode = R403; errorMessage = documentAlreadySubmitted |
| 51 | isSuccess = false ; errorCode = I500; errorMessage = unexpectedError |
| 61 | isSuccess = false ; errorCode = R408; errorMessage = redirectUrlExpired |
Request example: in progress with redirectURL
{
"region": "US",
"businessDetails": {
"businessName": "TESSERACT LLC WFWEF",
"businessRegistrationNumber": "101402356",
"businessType": "LIMITED_LIABILITY_COMPANY",
"description": "Limited liability company in US for IT services",
"legalDetails": {
"registeredCountry": "US",
"registeredDate": "2021-08-10"
},
"addresses": {
"registeredAddress": {
"addressLine1": "223, Grand St.",
"addressLine2": "",
"city": "New York",
"state": "NY",
"country": "US",
"postcode": "10013"
}
},
"stakeholders": [
{
"stakeholderDetails": {
"kycMode": "E_KYC",
"firstName": "MARTHA",
"lastName": "ENGLISH REBORN",
"nationality": "US",
"dateOfBirth": "1961-08-11",
"professionalDetails": [
{
"position": "CONTROL_PRONG"
}
],
"address": {
"addressLine1": "Park Street",
"city": "Newark",
"state": "New Jersey",
"country": "US",
"postcode": "07071"
},
"documentDetails": [
{
"documentType": "NATIONAL_ID",
"documentNumber": "555456789",
"documentIssuanceCountry": "US"
}
]
}
},
{
"businessPartner": {
"businessName": "CUZEK PRIVATE VENTURES",
"businessRegistrationNumber": "987609384",
"businessEntityType": "UBO",
"sharePercentage": "15",
"legalDetails": {
"registeredCountry": "US"
}
}
}
],
"applicantDetails": {
"kycMode": "E_DOC_VERIFY",
"firstName": "MARTHA",
"lastName": "ENGLISH REBORN",
"nationality": "US",
"dateOfBirth": "1961-08-11",
"professionalDetails": [
{
"position": "SIGNATORY"
}
],
"contactDetails": {
"countryCode": "US",
"contactNo": "91974922222",
"email": "[email protected]"
},
"address": {
"addressLine1": "Apt X 99, Green Avenue",
"city": "West Hartford",
"state": "Connecticut",
"postcode": "06110",
"country": "US"
},
"additionalInfo": {
"applicantDeclaration": "Yes"
}
},
"additionalInfo": {
"isSameBusinessAddress": "Yes"
}
},
"riskAssessmentInfo": {
"totalEmployees": "EM005",
"annualTurnover": "US007",
"industrySector": "IS033",
"intendedUseOfAccount": "IU009",
"countryOfOperation": [
"US",
"SG",
"HK",
"AU"
],
"transactionCountries": [
"SG",
"AU",
"EU"
]
},
"tags": [
{
"key": "tag1",
"value": "tag1value"
},
{
"key": "tag2",
"value": "tag2value"
}
]
}
Updated 6 months ago