KYB Comprehensive Report API Documentation
KYB Comprehensive API Documentation
Endpoint
POST `https://api.satschel.com/v2/kyb/entity
GET `https://api.satschel.com/v2/kyb/entity/:id
1. Overall Structure
Request Structure
The request to the KYB Comprehensive API should include the following JSON structure:
{
"company": {
"companyId": "914108804",
"requestId": "66583a18d50e7b49ffba4324"
},
"configurations": {
"enhanced": true,
"comprehensive": true
},
"representatives": [
{
"firstName": "Test",
"lastName": "last",
"dateOfBirth": {
"year": "1942",
"month": "11",
"day": "21"
},
"nationalIdNumber": "123456789",
"telephone": "+141231111"
}
]
}
Sample POST Request
Here is a sample POST request to the KYB Comprehensive API:
{
"company": {
"companyId": "914108804",
"requestId": "66583a18d50e7b49ffba4324"
},
"configurations": {
"enhanced": true,
"comprehensive": true
},
"representatives": [
{
"firstName": "Test",
"lastName": "last",
"dateOfBirth": {
"year": "1942",
"month": "11",
"day": "21"
},
"nationalIdNumber": "123456789",
"telephone": "+141231111"
}
]
}
2. Address Object
The address object within the response data contains the following fields:
- value: The address string.
- status: The verification status of the address.
Example
jsonCopy code
{
"value": "62 STRATFORD RD",
"status": "not-verified"
}
3. Person Object
The person object representing a company representative contains the following fields:
- first_name: First name of the representative.
- last_name: Last name of the representative.
- national_id_number: National ID number (SSN).
- date_of_birth: Date of birth in YYYYMMDD format.
- telephone_number: Telephone number.
Example
{
"first_name": "First Name",
"last_name": "Last Name",
"national_id_number": "SSN",
"date_of_birth": "YYYYMMDD",
"telephone_number": "Phone Number"
}
4. Documentation: Company Verification Output
This section describes the data structure of the output returned by the KYB (Know Your Business) API after processing a company's details.
Overall Structure
The response from the KYB Comprehensive API will contain the following fields:
- message: Status message.
- data: Contains the detailed information about the company and representatives.
API Results
The data object contains multiple nested objects providing detailed information:
Status
- status: Indicates the overall verification status (e.g., "approved, under review and rejected").
Basic Info
- name: Company name and its verification status.
- status: Company status (e.g., "active and inactive").
- tin: Tax Identification Number and its verification status.
- location: Address object containing address, city, state, and zip code.
- contactDetails: Contains phone information.
Example
{
"status": "rejected",
"basicInfo": {
"name": {
"value": "company name",
"status": "not-verified"
},
"status": {
"value": "active"
},
"tin": {
"value": "tin",
"status": "not-verified"
},
"location": {
"value": {
"address": {
"value": "62 STRATFORD RD",
"status": "not-verified"
},
"city": {
"value": "NEW ROCHELLE",
"status": "not-verified"
},
"state": {
"value": "NY",
"status": "not-verified"
},
"zipCode": {
"value": "10804",
"status": "not-verified"
}
}
},
"contactDetails": {
"value": {
"phone": {
"value": [
{
"value": "2125551650",
"status": "not-verified"
}
]
}
}
},
"errorMessages": [
"The company is not verified.",
"The representative is not verified.",
"The representative is not associated with business."
]
}
}
5. AuthorizedRepresentativeResults
Contains information about the authorized representatives:
- name: Name and verification status.
- dateOfBirth: Date of birth and verification status.
- phone: Phone number and verification status.
- nationalIdNumber: National ID number and verification status.
- relatesToBusiness: Boolean indicating if the representative is related to the business.
- id: Unique identifier.
Example
{
"authorizedRepresentative": {
"value": [
{
"name": {
"value": "First Name",
"status": "not-verified"
},
"dateOfBirth": {
"value": "YYYYMMDD",
"status": "not-verified"
},
"phone": {
"value": "2345678987",
"status": "not-verified"
},
"nationalIdNumber": {
"value": "XXXXX6789",
"status": "not-verified"
},
"relatesToBusiness": {
"value": false},
"id": {
"value": "2cb06a02-9882-4560-96df-1ebefb9540ca"
}
}
]
}
}
6. Sample Output
Below is a sample output from the KYB Comprehensive API:
{
"message": "ok",
"data": {
"status": "rejected",
"basicInfo": {
"name": {
"value": "company name",
"status": "not-verified"
},
"status": {
"value": "active"
},
"tin": {
"value": "915555977",
"status": "not-verified"
},
"location": {
"value": {
"address": {
"value": "62 STRATFORD RD",
"status": "not-verified"
},
"city": {
"value": "City",
"status": "not-verified"
},
"state": {
"value": "State",
"status": "not-verified"
},
"zipCode": {
"value": "10804",
"status": "not-verified"
}
}
},
"contactDetails": {
"value": {
"phone": {
"value": [
{
"value": "Phone Number",
"status": "not-verified"
}
]
}
}
},
"errorMessages": [
"The company is not verified.",
"The representative is not verified.",
"The representative is not associated with business."
]
},
"similarCompanies": {
"value": [],
"error": {
"message": "This company does not have the value for the metric."
}
},
"authorizedRepresentative": {
"value": [
{
"name": {
"value": "First Name",
"status": "not-verified"
},
"dateOfBirth": {
"value": "YYYYMMDD",
"status": "not-verified"
},
"phone": {
"value": "Phone Number",
"status": "not-verified"
},
"nationalIdNumber": {
"value": "XXXXX6789",
"status": "not-verified"
},
"relatesToBusiness": {
"value": false},
"id": {
"value": "2cb06a02-9882-4560-96df-1ebefb9540ca"
}
}
]
},
"compliance": {
"value": {},
"error": {
"message": "This company does not have the value for the metric."
}
},
"comprehensive": {
"label": "KYB Comprehensive",
"report": {
"companyInformation": {
"label": "Company Information",
"type": "card",
"value": {
"address": {
"label": "Address",
"type": "basic",
"value": "Address"
},
"tin": {
"label": "Tin",
"type": "basic",
"value": "915555977"
},
"uRL": {
"label": "URL",
"type": "basic",
"value": "DontQuitYourDayJobKaraoke.com"
}
}
}
}
}
}
}
User Flow for KYB Verification
1. User Enters Business Details
The user begins by entering the following business details:
- Business Name
- FEIN (Federal Employer Identification Number)
- Country
- State
2. Business Search API Call
The system then calls the Business Search API using the provided business details.
3. Fetch Business List
The Business Search API retrieves a list of businesses matching the entered details from the database.
4. User Selects Business or Enters Manually
The user selects a business from the fetched list or manually enters the business details if their business is not listed.
5. User Enters Authorized Representative Details
Next, the user provides details of the authorized representative, including:
- First Name
- Last Name
- Date of Birth
- SSN (Social Security Number)
- Phone Number
6. User Clicks on Submit
Once all the required information is provided, the user clicks the submit button to proceed.
7. KYB Sample POST API Call
The system sends a POST request to the KYB Enhanced API with the business and representative details for verification.
8. Receive KYB Comprehensive Response from KYB Comprehensive API
Using the KYB Comprehensive API, the system receives the KYB Comprehensive response, which includes the verification results for the business and its authorized representative.
Sample KYB Comprehensive API Post Request
The following JSON sample illustrates the structure of the POST request sent to the KYB Comprehensive API:
{
"company": {
"companyId": "Company ID from the search request",
"requestId": "Request ID from the search request"
},
"kybConfigurations": {
"kyb_enhanced": true,
"kyb_comprehensive": true},
"representatives": [
{
"first_name": "First Name",
"last_name": "Last Name",
"national_id_number": "SSN",
"date_of_birth": "YYYYMMDD",
"telephone_number": "Phone Number"
}
]
}
Sample KYB Comprehensive API Response
The following JSON sample demonstrates the structure of the response received from the KYB Comprehensive API using the KYB Comprehensive API:
jsonCopy code
{
"message": "ok",
"data": {
"status": "rejected",
"basicInfo": {
"name": {
"value": "Company Name",
"status": "verified"
},
"status": {
"value": "active"
},
"tin": {
"value": "123456789",
"status": "verified"
},
"location": {
"value": {
"address": {
"value": "Address",
"status": "not-verified"
},
"city": {
"value": "city",
"status": "not-verified"
},
"state": {
"value": "CA",
"status": "not-verified"
},
"zipCode": {
"value": "94108",
"status": "not-verified"
}
}
},
"contactDetails": {
"value": {
"phone": {
"value": [
{
"value": "4153412888",
"status": "not-verified"
}
]
}
}
},
"errorMessages": [
"The company is not verified.",
"The representative is not verified.",
"The representative is not associated with business."
]
},
"similarCompanies": {
"value": [
{
"name": {
"value": "Company Name"
},
"address": {
"value": "Address"
}
},
{
"name": {
"value": "Company Name"
},
"address": {
"value": "Address"
}
},
{
"name": {
"value": "Company Name"
},
"address": {
"value": "Address"
}
}
]
},
"authorizedRepresentative": {
"value": [
{
"name": {
"value": "First Name",
"status": "not-verified"
},
"dateOfBirth": {
"value": "YYYYMMDD",
"status": "not-verified"
},
"phone": {
"value": "Phone Number",
"status": "not-verified"
},
"nationalIdNumber": {
"value": "XXXXX6789",
"status": "not-verified"
},
"relatesToBusiness": {
"value": false},
"id": {
"value": "2b5c9d34-0094-43d3-8f90-9ae2dcb4b943"
}
}
]
},
"compliance": {
"TimeOnSOS": {
"value": "0"
},
"SOSStatus": {
"value": "UNKNOWN"
},
"LNStatus": {
"value": "NO RECENT PUBLIC RECORDS"
},
"TimeOnPublicRecord": {
"value": "116"
},
"County": {
"value": "SAN FRANCISCO"
},
"BusinessFirstSeenYYYY": {
"value": "2014"
}
}
}
}
Updated 11 months ago