Clear Report Analysis API
This document outlines the details of the Clear Report Analysis API.
API Description
Objective
The Clear Report Analysis API analyzes Clear investigation reports to produce risk assessments for loan applications from business entities. It returns structured decisions, and flags decline reasons so lenders can evaluate applications consistently.
| Input | Output |
|---|---|
| Signed URLs for CLEAR Business & Person reports (XML) | Risk-based decisions (approve/reject/review), decline reasons (e.g. criminal, cash advance, bankruptcy, sanctions), consolidated analysis (UCC, lawsuits, liens, etc.), recommendations. |
API URL
https://usa-engine.thomas.hyperverge.co/v1/clear_report_analysis
API Endpoint
clear_report_analysis
Overview
The Clear Report Analysis API is RESTful and uses standard HTTP verbs and status codes. The requests are in form-data format and responses are in JSON format.
Authentication
You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the Clear Report Analysis API.
API Request Details
Method - POST
Headers
| Header | Mandatory / Optional | Description | Input Format |
|---|---|---|---|
content-type | Mandatory | This parameter defines the media type for the request payload. | multipart/form-data |
appId | Mandatory | The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab. | Not Applicable - this is a unique value |
appKey | Mandatory | The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab. | Not Applicable - this is a unique value |
transactionId | Mandatory | A unique identifier for tracking a user journey | Not Applicable - this should be both unique and easily associated with the user's journey in your application(s) |
Input
The following table provides the details of the parameters required for the Clear Report Analysis API's request body:
| Parameter | Mandatory / Optional | Type | Description | Input Format | Default Value |
|---|---|---|---|---|---|
businessReport | Mandatory | string | Pre-signed URL for the CLEAR Business Report | URL | Not Applicable |
personReports | Mandatory | array | Array of pre-signed URLs for CLEAR Person Reports | Array of URLs | Not Applicable |
businessName | Mandatory | string | The legal name of the business entity applying for the loan | String | Not Applicable |
businessAddress | Optional | string | The complete address of the business entity | String | Not Applicable |
ownerNames | Mandatory | array | An array of names of the business owners | Array of strings | Not Applicable |
Request
The following code snippet demonstrates a standard curl request for the Clear Report Analysis API:
curl --location --request POST 'https://usa-engine.thomas.hyperverge.co/v1/clear_report_analysis' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--form 'businessReport="<Enter_the_BR_URL>"' \
--form 'personReports="["<Enter_the_PR_1_URL>", "<Enter_the_PR_2_URL>"]"' \
--form 'businessName="<Enter_the_Business_Name>"' \
--form 'businessAddress="<Enter_the_Business_Address>"' \
--form 'ownerNames="["<Enter_Owner_1_Name>", "<Enter_Owner_2_Name>"]"'
Success Response
The following code snippet demonstrates a success response from the Clear Report Analysis API:
{
"status": "success",
"statusCode": 200,
"result": {
"details": {
"uccFilings": {
"filings": [
{
"securedPartyName": "C***E",
"filingDate": "03/01/2022",
"filingType": "ORIGINAL",
"originalFilingDate": "03/01/2022",
"yearsSinceFiling": 3,
"monthsSinceFiling": 38,
"isAlternateLender": true,
"isOtherLender": false,
"collaterals": [
"ASSETS AND PROCEEDS",
"ACCOUNT(S) AND PROCEEDS",
"CHATTEL PAPER AND PROCEEDS",
"EQUIPMENT AND PROCEEDS",
"GENERAL INTANGIBLE(S) AND PROCEEDS",
"INVENTORY AND PROCEEDS",
"ACCOUNTS RECEIVABLE AND PROCEEDS"
],
"sourceFile": "BR",
"sourceSection": "UCCSection",
"entityName": "Name as per clear",
"concernedPartyName": "Name as per Input",
"concernedPartyType": "Owner 1/Business"
}
],
"secondaryEntities": [
{
"entityName": "P***S",
"filings": [
{
"securedPartyName": "C***E",
"filingDate": "03/01/2022",
"filingType": "ORIGINAL",
"originalFilingDate": "03/01/2022",
"yearsSinceFiling": 3,
"monthsSinceFiling": 38,
"isAlternateLender": true,
"isOtherLender": false,
"collaterals": [
"ASSETS AND PROCEEDS",
"ACCOUNT(S) AND PROCEEDS",
"CHATTEL PAPER AND PROCEEDS",
"EQUIPMENT AND PROCEEDS",
"GENERAL INTANGIBLE(S) AND PROCEEDS",
"INVENTORY AND PROCEEDS",
"ACCOUNTS RECEIVABLE AND PROCEEDS"
],
"sourceFile": "BR",
"sourceSection": "UCCSection"
}
]
}
]
},
"criminalAndArrestRecords": [
{
"filingDate": "06/05/1990",
"crimeDate": "04/23/2009",
"publicationDate": "04/23/2009",
"dispositionDate": "04/23/2009",
"yearsSinceFiling": 34,
"monthsSinceFiling": 419,
"category": "UncategorizedCriminalRecords",
"offense": "CHECKS, FRAUDULENT CHECK-LESS 500-1ST",
"disposition": "GUILTY",
"status": "CLOSED",
"statuteViolated": "0670",
"severity": "Misdemeanor",
"isTrustCrime": true,
"isTrafficViolation": false,
"isSexOffense": false,
"isMurder": false,
"bailAmount": "N/A",
"caseNumber": "C***4",
"info": {
"sentenceInfo": "5 years",
"communityServiceInfo": "N/A",
"paroleInfo": "N/A",
"probationInfo": "N/A"
},
"sourceFile": "BR",
"sourceSection": "CriminalSection",
"entityName": "J***R",
"concernedPartyName": "J***R",
"concernedPartyType": "Owner 1"
}
],
"docketsLawsuitsAndJudgements": {
"withAlternateLenders": [
{
"date": "06/11/2012",
"yearsSinceFiling": 11,
"monthsSinceFiling": 132,
"natureOfSuit": "Contracts",
"status": "OPEN",
"sourceSection": "DocketSection",
"demandAmount": "$6,512.00",
"plaintiff": "P***C",
"sourceFile": "PR",
"title": "P***P v. M***N",
"entityName": "M***N",
"concernedPartyName": "M***N",
"concernedPartyType": "Business"
}
],
"withLandlord": [],
"withOtherLenders": [
{
"date": "01/24/2013",
"yearsSinceFiling": 10,
"monthsSinceFiling": 125,
"natureOfSuit": "Civil",
"status": "OPEN",
"sourceSection": "DocketSection",
"demandAmount": "$6,512.00",
"plaintiff": "D***K",
"sourceFile": "PR",
"title": "D***K v. M***N",
"entityName": "M***N",
"concernedPartyName": "M***N",
"concernedPartyType": "Business"
},
{
"date": "07/17/2012",
"yearsSinceFiling": 10,
"monthsSinceFiling": 131,
"natureOfSuit": "Civil",
"status": "OPEN",
"sourceSection": "DocketSection",
"demandAmount": "$6,512.00",
"plaintiff": "C***A",
"sourceFile": "PR",
"title": "C***A v. M***N",
"entityName": "M***N",
"concernedPartyName": "M***N",
"concernedPartyType": "Business"
}
],
"withFactoringCompanies": [
{
"date": "06/27/2013",
"yearsSinceFiling": 10,
"monthsSinceFiling": 120,
"natureOfSuit": "Banking/Finance",
"status": "OPEN",
"sourceSection": "DocketSection",
"demandAmount": "$6,512.00",
"plaintiff": "S***k,",
"sourceFile": "PR",
"title": "S***k v. M***N",
"entityName": "M***N",
"concernedPartyName": "M***N",
"concernedPartyType": "Business"
}
],
"others": [
{
"date": "12/20/2016",
"yearsSinceFiling": 6,
"monthsSinceFiling": 78,
"natureOfSuit": "Contracts",
"status": "OPEN",
"sourceSection": "DocketSection",
"demandAmount": "$6,512.00",
"plaintiff": "D***t",
"sourceFile": "PR",
"title": "D***t v. M***l",
"entityName": "M***l",
"concernedPartyName": "M***N",
"concernedPartyType": "Business"
},
{
"date": "05/13/2016",
"yearsSinceFiling": 7,
"monthsSinceFiling": 85,
"natureOfSuit": "Torts/Negligence",
"status": "OPEN",
"sourceSection": "DocketSection",
"demandAmount": "$6,512.00",
"plaintiff": "R***N, I***H",
"sourceFile": "PR",
"title": "R***N,I***H v. M***N",
"entityName": "M***N",
"concernedPartyName": "M***N",
"concernedPartyType": "Business"
}
]
},
"globalSanctions": {
"sanctionExists": "yes",
"details": [
{
"issuer": "SECURITIES AND EXCHANGE COMMISSION (SEC)",
"category": "SECURITIES AND EXCHANGE COMMISSION ADMINISTRATIVE PROCEEDING",
"country": "USA",
"description": "N/A",
"date": "05/21/2010",
"sourceFile": "PR",
"sourceSection": "GlobalSanctionSection",
"entityName": "S***N",
"concernedPartyName": "M***N",
"concernedPartyType": "Business"
}
]
},
"liens": [
{
"date": "03/04/2019",
"status": "OPEN",
"type": "Federal Tax Lien",
"amount": "$6,512.00",
"yearsSinceFiling": 4,
"monthsSinceFiling": 53,
"sourceFile": "BR",
"sourceSection": "LienJudgmentSection",
"entityName": "M***N",
"concernedPartyName": "M***N",
"concernedPartyType": "Owner 1"
},
{
"date": "03/04/2019",
"type": "FICA",
"status": "OPEN",
"amount": "$6,512.00",
"yearsSinceFiling": 4,
"monthsSinceFiling": 53,
"sourceFile": "BR",
"sourceSection": "LienJudgmentSection",
"entityName": "M***N",
"concernedPartyName": "M***N",
"concernedPartyType": "Owner 1"
}
],
"bankruptcyFilings": {
"recordExists": "yes",
"latestStatus": {
"filingDate": "01/31/2020",
"statusDate": "N/A",
"status": "Unknown",
"finalDecreeDate": "04/10/2020",
"chapter": "Chapter 13",
"341Scheduled": true,
"341Date": "03/17/2020",
"sourceFile": "PR",
"sourceSection": "BankruptcySection",
"entityName": "H***E, H***L",
"concernedPartyName": "H***L",
"concernedPartyType": "Owner 1"
}
},
"corporateFilings": {
"entityName": "C***C",
"filing": {
"filingDate": "09/07/2016",
"status": "ACTIVE",
"state": "G***A",
"phoneNumber": "N/A",
"taxId": "N/A",
"address": "5***2)",
"website": "N/A",
"sourceFile": "BR",
"sourceSection": "CorporateSection",
"monthsSinceFiling": 81,
"yearsSinceFiling": 6,
"entityName": "C***C"
},
"secondaryEntities": [
{
"entityName": "C***C.",
"filing": {
"filingDate": "07/18/2005",
"status": "ACTIVE",
"state": "G***A",
"phoneNumber": "N/A",
"taxId": "N/A",
"address": "5***2)",
"website": "N/A",
"sourceFile": "PR",
"sourceSection": "CorporateSection",
"monthsSinceFiling": 215,
"yearsSinceFiling": 17
}
},
{
"entityName": "W***C",
"filing": {
"filingDate": "08/21/2020",
"status": "ACTIVE",
"state": "G***A",
"phoneNumber": "N/A",
"taxId": "N/A",
"address": "9***1)",
"website": "N/A",
"sourceFile": "PR",
"sourceSection": "CorporateSection",
"monthsSinceFiling": 34,
"yearsSinceFiling": 2
}
}
]
},
"licenses": [
{
"licenseType": "SALESPERSON",
"category": "N/A",
"status": "ACTIVE",
"licenseNumber": "2***1",
"isProfessional": false,
"industryMatch": false,
"sourceFile": "PR",
"sourceSection": "LicenseSection",
"entityName": "M***N",
"concernedPartyName": "M***N",
"concernedPartyType": "Owner 1"
},
{
"licenseType": "RESIDENTIAL BASIC INDIVIDUAL",
"category": "RESIDENTIAL/GENERAL CONTRACTOR",
"status": "ACTIVE",
"licenseNumber": "R***7",
"isProfessional": false,
"industryMatch": false,
"sourceFile": "PR",
"sourceSection": "LicenseSection",
"entityName": "M***N",
"concernedPartyName": "M***N",
"concernedPartyType": "Owner 1"
},
{
"licenseType": "RESIDENTIAL BASIC QUALIFYING AGENT",
"category": "RESIDENTIAL/GENERAL CONTRACTOR",
"status": "ACTIVE",
"licenseNumber": "R***7",
"isProfessional": false,
"industryMatch": false,
"sourceFile": "PR",
"sourceSection": "LicenseSection",
"entityName": "M***N",
"concernedPartyName": "M***N",
"concernedPartyType": "Owner 1"
}
],
"workAffiliations": {
"entityName": "C***C",
"phoneNumber": "(6***2",
"address": {
"Street": "5***E",
"City": "A***A",
"State": "G***A",
"ZipCode": "3***2",
"County": "F***N"
},
"website": "N/A",
"ownerAffiliation": [
{
"ownerName": "M***N",
"listedPosition": "PRINCIPAL",
"changeDate": "N/A",
"sourceFile": "BR",
"sourceSection": "DunBradstreetSection"
},
{
"ownerName": "S***L",
"listedPosition": "PRINCIPAL",
"changeDate": "N/A",
"sourceFile": "BR",
"sourceSection": "DunBradstreetSection"
}
],
"secondaryEntities": [
{
"entityName": "S***C",
"phoneNumber": "N/A",
"address": {
"Street": "1***D",
"City": "R***L",
"State": "G***A",
"ZipCode": "3***5"
},
"website": "",
"ownerAffiliation": [
{
"ownerName": "B***D",
"listedPosition": "N/A",
"changeDate": "N/A",
"sourceFile": "PR",
"sourceSection": "WorkAffiliationSection"
}
]
}
]
},
"basicBusinessOwnerChecks": {
"ownerChecks": [
{
"ownerName": "M***N",
"ssnCheck": "neutral",
"nameCheck": "pass",
"dobCheck": "neutral",
"phoneCheck": "neutral",
"ownerAliveCheck": "pass",
"listedPosition": "PRINCIPAL",
"ownershipLinkCheck": "pass",
"quickAnalysisFlags": []
}
],
"businessChecks": {
"nameCheck": "pass",
"addressCheck": "pass",
"phoneCheck": "neutral",
"quickAnalysisFlags": [],
"businessName": "C***C",
"isTransportation": false
}
}
},
"summary": {
"action": "manual-review",
"details": [
"Negative Cash Advance History",
"Adverse Judgments",
"Criminal History",
"Unresolved Liens",
"Bankruptcy",
"Global Sanctions"
]
}
}
}
Success Response Details
The following table outlines the details of the success response from the Clear Report Analysis API:
| Parameter | Type | Description |
|---|---|---|
| status | string | Status of the API response |
| statusCode | integer | The HTTP status code of the response |
| result | object | The main result object containing all response data |
| details | object | The main response object containing all extracted data |
| uccFilings | object | Details of all UCC (Uniform Commercial Code) filings against the Business or any of the primary owners |
| filings | array | List all UCC filings against the Business or any of the primary owners |
| securedPartyName | string | Name of the secured party in the UCC filing |
| filingDate | string | Date when the UCC filing was made |
| filingType | string | Type of UCC filing |
| originalFilingDate | string | Original filing date for the UCC record |
| yearsSinceFiling | integer | Number of years since the filing was made |
| monthsSinceFiling | integer | Number of months since the filing was made |
| isAlternateLender | boolean | Indicates if the secured party is an alternate lender |
| isOtherLender | boolean | Indicates if the secured party is another type of lender |
| collaterals | array | List of collateral types covered in the UCC filing |
| sourceFile | string | Source file identifier for the UCC data |
| sourceSection | string | Source section identifier for the UCC data |
| entityName | string | Name as per the record in clear report |
| concernedPartyName | string | Name as per the request body input |
| concernedPartyType | string | Owner x/Business |
| secondaryEntities | array | UCC filings against other business entities associated with the primary owners |
| criminalAndArrestRecords | array | Details of all Criminal Records where the any of the primary owners were convicted |
| person | string | Name of the person associated with the criminal record |
| filingDate | string | Date when the criminal case was filed |
| crimeDate | string | Date when the crime was committed |
| publicationDate | string | Date when the record was published |
| dispositionDate | string | Date when the case was disposed |
| yearsSinceFiling | integer | Number of years since the criminal case was filed |
| monthsSinceFiling | integer | Number of months since the criminal case was filed |
| category | string | Category of the criminal record |
| offense | string | Description of the criminal offense |
| disposition | string | Disposition of the criminal case |
| status | string | Current status of the criminal case |
| statuteViolated | string | Statute that was violated |
| severity | string | Severity level of the criminal offense |
| isTrustCrime | boolean | Indicates if the crime is a trust crime |
| isTrafficViolation | boolean | Indicates if the offense is a traffic violation |
| isSexOffense | boolean | Indicates if the offense is a sexual offense |
| isMurder | boolean | Indicates if the offense amounts to a murder |
| bailAmount | string | Bail amount set for the case |
| caseNumber | string | Case number for the criminal proceeding |
| info | object | Additional information about the criminal case |
| sentenceInfo | string | Information about the sentence imposed |
| communityServiceInfo | string | Information about community service requirements |
| paroleInfo | string | Information about parole conditions |
| probationInfo | string | Information about probation conditions |
| entityName | string | Name as per the record in clear report |
| concernedPartyName | string | Name as per the request body input |
| concernedPartyType | string | Owner x/Business |
| docketsLawsuitsAndJudgements | object | Details of all Dockets, Lawsuits and Judgements against the Business or any of the primary owners |
| withAlternateLenders | array | Lawsuits involving alternate lenders |
| withLandlord | array | Lawsuits involving landlords |
| withOtherLenders | array | Lawsuits involving other lenders |
| withFactoringCompanies | array | Lawsuits involving factoring companies |
| others | array | Other types of lawsuits and judgments |
| entityName | string | Name as per the record in clear report |
| concernedPartyName | string | Name as per the request body input |
| concernedPartyType | string | Owner x/Business |
| globalSanctions | object | Details of any Global Sanctions Issued against any of the primary owners |
| sanctionExists | string | Indicates if sanctions exist against the entity |
| details | array | Detailed information about the sanctions |
| entityName | string | Name as per the record in clear report |
| concernedPartyName | string | Name as per the request body input |
| concernedPartyType | string | Owner x/Business |
| liens | array | Details of open liens filed against the business or any of the primary owners |
| entityName | string | Name as per the record in clear report |
| concernedPartyName | string | Name as per the request body input |
| concernedPartyType | string | Owner x/Business |
| bankruptcyFilings | object | Details of any relevant bankruptcy filings by the business or any of the primary owners |
| recordExists | string | Indicates if bankruptcy records exist |
| latestStatus | object | Latest status information about the bankruptcy |
| entityName | string | Name as per the record in clear report |
| concernedPartyName | string | Name as per the request body input |
| concernedPartyType | string | Owner x/Business |
| corporateFilings | object | Details of the corporate filings of the business and any secondary businesses of the owners |
| entityName | string | Name of the corporate entity |
| filing | object | Filing information for the corporate entity |
| secondaryEntities | array | List corporate filings for any secondary businesses of the owners |
| licenses | array | Details of all professional licenses held by the business or any of the owners |
| entityName | string | Name as per the record in clear report |
| concernedPartyName | string | Name as per the request body input |
| concernedPartyType | string | Owner x/Business |
| workAffiliations | object | Details of all work affiliations associated with the business or any of the primary owners |
| entityName | string | Name of the primary business entity |
| phoneNumber | string | Phone Number of the primary business entity |
| address | object | Address of the primary business entity |
| website | string | Website of the primary business entity |
| ownerAffiliation | array | List of owner affiliations |
| secondaryEntities | array | List of work affiliations of primary owners with secondary business entities |
| basicBusinessOwnerChecks | object | Basic checks on the business and primary owners based on the input details and CLEAR reports |
| ownerChecks | array | Owner verification checks |
| businessChecks | object | Business verification checks |
| summary | object | Summary Response from the Clear Report Analysis API highlighting decline reasons, if any |
| action | string | Decision from clear-analysis (manual-review/auto-approve) |
| details | array | An array of decline reasons, if any |
Error Responses
- Missing Mandatory Parameter
- No Business Name Present
- No Owner Name Present
- No Business Report Present
- No Personal Report Present
{
"status": "failure",
"statusCode": 400,
"message": "Missing mandatory parameter"
}
{
"status": "failure",
"statusCode": 400,
"message": "No Business Name present"
}
{
"status": "failure",
"statusCode": 400,
"message": "No Owner Name present"
}
{
"status": "failure",
"statusCode": 400,
"message": "No BR present"
}
{
"status": "failure",
"statusCode": 400,
"message": "No PR present"
}
- Business Report XML Not Downloadable
- Personal Report XML Not Downloadable
- Unprocessable Business Report XML
- Unprocessable Personal Report XML
- Missing/Invalid Credentials
- Internal Server Error
{
"status": "failure",
"statusCode": 400,
"message": "BR XML not downloadable"
}
{
"status": "failure",
"statusCode": 400,
"message": "PR XML not downloadable"
}
{
"status": "failure",
"statusCode": 400,
"message": "Unprocessable BR XML"
}
{
"status": "failure",
"statusCode": 400,
"message": "Unprocessable PR XML"
}
{
"status": "failure",
"statusCode": 401,
"message": "Missing/Invalid credentials"
}
{
"status": "failure",
"statusCode": 500,
"message": "internal server error"
}
Error Response Details
A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:
| Status Code | Error Message | Error Description | Error Resolution |
|---|---|---|---|
| 400 | Missing mandatory parameter | Required parameter is missing from the request | Include all mandatory parameters in the request body |
| 400 | No Business Name present | The value for Business name parameter is missing from the request | Include the businessName field in the request body with a valid business name |
| 400 | No Owner Name present | One or more owner name values missing from request | Include the ownerNames field in the request body with at least one owner name |
| 400 | No BR present | Business Report (BR) data is missing from the request | Include the businessReport field in the request body with a valid Business Report URL |
| 400 | No PR present | Personal Report (PR) data is missing from the request | Include the personReports field in the request body with at least one Person Report URL |
| 400 | BR XML not downloadable | Business Report XML file could not be downloaded | Ensure the Business Report URL is downloadable and points to a valid XML file |
| 400 | PR XML not downloadable | Personal Report XML file could not be downloaded | Ensure the Person Report URL(s) are downloadable and point to valid XML files |
| 400 | Unprocessable BR XML | Business Report XML file could not be processed | Verify the Business Report XML is well-formed and follows the expected CLEAR report format. Check for XML syntax errors |
| 400 | Unprocessable PR XML | Personal Report XML file could not be processed | Verify the Person Report XML is well-formed and follows the expected CLEAR report format. Check for XML syntax errors |
| 401 | Missing/Invalid credentials | The request is either missing the mandatory appId and appKey combination or has invalid values | Verify and provide valid appId and appKey credentials in the request headers |
| 500 | Internal server error | An internal server error occurred during processing | Check the request headers and body format, or contact the HyperVerge team for resolution |