Sales PDF OCR API
This document highlights the Sales PDF OCR API details.
API Description
Objective
The Sales PDF OCR API extracts business critical fields from Sales PDF document and returns it in a JSON format.
| Input | Output |
|---|---|
| A file containing a Sales PDF document | The textual information extracted from the document |
API URL
The URL for the Sales PDF OCR API is:
https://usa-engine.thomas.hyperverge.co/v1/readMCASalesApplication
API Endpoint
The endpoint for the Sales PDF OCR API is:
readMCASalesApplication
Overview
The Sales PDF OCR API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.
Authentication
You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.
API Request Details
Method - POST
Headers
| Parameter | Mandatory or Optional | Type | Description | Valid Values |
|---|---|---|---|---|
content-type | Mandatory | string | This parameter defines the media type for the request payload. | multipart/form-data |
appId | Mandatory | string | The application ID shared by HyperVerge | Not Applicable - this is a unique value. |
appKey | Mandatory | string | The application key shared by HyperVerge | Not Applicable - this is a unique value. |
transactionId | Mandatory | string | The unique ID for the customer journey. | Not Applicable - this is a unique value related to a transaction in your application. |
Input
The following table lists the parameter required for the Sales PDF OCR API's request body:
| Parameter | Mandatory or Optional | Description | Allowed Values | Default Values |
|---|---|---|---|---|
pdfFile | Mandatory | The file containing the Sales PDF document | The file must be in Portable Document Format (PDF) | Not Applicable |
Request
The following code snippet demonstrates a standard curl request for the Sales PDF OCR API:
curl --location --request POST 'https://usa-engine.thomas.hyperverge.co/v1/readMCASalesApplication' \
--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 'pdfFile=@"<path_to_pdf_file>"'
Document Sample
The following is a sample of a Sales PDF Document:
Success Response
The following code snippet demonstrates a success response from the API:
{
"status": "success",
"statusCode": 200,
"result": {
"details": [
{
"fieldsExtracted": {
"businessLegalName": {
"value": "<Business_Legal_Name>",
"confidence": "High",
"score": 1
},
"businessDBA": {
"value": "<Business_DBA_Name>",
"confidence": "High",
"score": 0.99
},
"federalTaxID": {
"value": "<Federal_Tax_ID>",
"confidence": "High",
"score": 1
},
"companyType": {
"value": "<Company_Type>",
"confidence": "High",
"score": 0.8
},
"businessPhone": {
"value": "<Business_Phone_Number>",
"confidence": "High",
"score": 0.78
},
"businessEmail": {
"value": "<Business_Email_Address>",
"confidence": "High",
"score": 0.75
},
"incorporationDate": {
"value": "<Incorporation_Date_in_DD/MM/YYYY_Format>",
"confidence": "High",
"score": 0.87
},
"businessAddress": {
"value": "<Business_Address>",
"confidence": "High",
"score": 0.8
},
"businessLocationCity": {
"value": "<Business_City>",
"confidence": "High",
"score": 0.99
},
"businessLocationState": {
"value": "<Business_State>",
"confidence": "High",
"score": 1
},
"businessLocationZipCode": {
"value": "<Business_Zip_Code>",
"confidence": "High",
"score": 0.99
},
"businessDomainName": {
"value": "<Business_Domain_URL>",
"confidence": "High",
"score": 0.99
},
"monthlyRevenue": {
"value": "<Monthly_Revenue>",
"confidence": "High",
"score": 0.75
},
"annualRevenue": {
"value": "<Annual_Revenue>",
"confidence": "High",
"score": 0.98
},
"amountRequested": {
"value": "<Amount_Requested>",
"confidence": "High",
"score": 0.99
},
"ownerName": {
"value": "<Owner's_Name>",
"confidence": "High",
"score": 1
},
"ownerPhone": {
"value": "<Owner's_Phone_Number>",
"confidence": "High",
"score": 0.75
},
"ownerEmail": {
"value": "<Owner's_Email>",
"confidence": "High",
"score": 0.75
},
"ownerSocialSecurityNumber": {
"value": "<Owner's_Social_Security_Number>",
"confidence": "High",
"score": 1
},
"ownerDateOfBirth": {
"value": "<Owner's_Date_Of_Birth_in_DD/MM/YYYY_Format>",
"confidence": "High",
"score": 0.99
},
"ownershipPercentage": {
"value": "<Owner's_Percentage_Ownership>",
"confidence": "High",
"score": 1
},
"ownerAddress": {
"value": "<Owner's_Address>",
"confidence": "High",
"score": 0.9
},
"ownerResidenceCity": {
"value": "<Owner's_City>",
"confidence": "High",
"score": 1
},
"ownerResidenceState": {
"value": "<Owner's_State>",
"confidence": "High",
"score": 1
},
"ownerResidenceZipCode": {
"value": "<Owner's_Zip_Code>",
"confidence": "High",
"score": 1
},
"owner2Name": {
"value": "<Second_Owner's_Name>",
"confidence": "High",
"score": 1
},
"owner2Phone": {
"value": "<Second_Owner's_Phone_Number>",
"confidence": "High",
"score": 0.75
},
"owner2Email": {
"value": "<Second_Owner's_Email_Address>",
"confidence": "High",
"score": 0.75
},
"owner2SocialSecurityNumber": {
"value": "<Second_Owner's_Social_Security_Number>",
"confidence": "High",
"score": 1
},
"owner2DateOfBirth": {
"value": "<Second_Owner_Date_Of_Birth_in_DD/MM/YYYY_Format>",
"confidence": "High",
"score": 1
},
"owner2OwnershipPercentage": {
"value": "<Second_Owner's_Partnership_Percentage>",
"confidence": "High",
"score": 0.75
},
"owner2Address": {
"value": "<Second_Owner's_Address>",
"confidence": "High",
"score": 0.93
},
"owner2ResidenceCity": {
"value": "<Second_Owner's_City>",
"confidence": "High",
"score": 1
},
"owner2ResidenceState": {
"value": "<Second_Owner's_State>",
"confidence": "High",
"score": 1
},
"owner2ResidenceZipCode": {
"value": "<Second_Owner's_Zip_Code>",
"confidence": "High",
"score": 1
}
},
"signatureValidation": {
"validSignature": "<Valid_Signature_Status>",
"signatureType": "<Signature_Type>"
},
"type": "<Form_Type>"
}
],
"summary": {
"action": "<Summary_Action>",
"details": []
}
},
"metadata": {
"requestId": "<Request_ID>",
"transactionId": "<Transaction_ID>"
}
}
Success Response Details
The following table outlines the details of the success response from the Sales PDF OCR API:
| Parameter | Type | Description |
|---|---|---|
| status | string | The status of the request |
| statusCode | integer | The HTTP status code of the request |
| requestId | string | A unique identifier for the request |
| transactionId | string | A unique transaction identifier |
| type | string | The type of the form submitted |
| validSignature | string | Indicates if the submitted signature is valid |
| signatureType | string | The type of signature used. info It can be one of the following: docusign, digital with ip address, physical, or empty |
| businessLegalName | string | The registered legal name of the business |
| businessDBA | string | The 'Doing Business As' name of the business |
| federalTaxID | string | The Federal Tax Identification Number of the business |
| companyType | string | The type of business entity |
| businessPhone | string | The contact phone number of the business |
| businessEmail | string | The contact email address of the business |
| incorporationDate | string | The date the business was incorporated |
| businessAddress | string | The registered address of the business |
| businessLocationCity | string | The city where the business is located |
| businessLocationState | string | The state where the business is located |
| businessLocationZipCode | string | The ZIP code of the business location |
| businessDomainName | string | The website URL of the business |
| monthlyRevenue | string | The estimated monthly revenue of the business |
| annualRevenue | string | The estimated annual revenue of the business |
| amountRequested | string | The loan amount requested |
| ownerName | string | The name of the primary business owner |
| ownerPhone | string | The phone number of the primary business owner |
| ownerEmail | string | The email address of the primary business owner |
| ownerSocialSecurityNumber | string | The Social Security Number of the primary business owner |
| ownerDateOfBirth | string | The date of birth of the primary business owner |
| ownershipPercentage | string | The percentage of business ownership held by the primary owner |
| ownerAddress | string | The residential address of the primary business owner |
| ownerResidenceCity | string | The city of residence of the primary business owner |
| ownerResidenceState | string | The state of residence of the primary business owner |
| ownerResidenceZipCode | string | The ZIP code of the primary business owner's residence |
| owner2Name | string | The full name of the second business owner |
| owner2Phone | string | The contact phone number of the second business owner |
| owner2Email | string | The contact email address of the second business owner |
| owner2SocialSecurityNumber | string | The social security number of the second business owner |
| owner2DateOfBirth | string | The date of birth of the second business owner |
| owner2OwnershipPercentage | string | The percentage of business ownership held by the second owner |
| owner2Address | string | The residential address of the second business owner |
| owner2ResidenceCity | string | The city of the second business owner's residence |
| owner2ResidenceState | string | The state of the second business owner's residence |
| owner2ResidenceZipCode | string | The ZIP code of the second business owner's residence |
| summary | object | The summary object suggests the final action for the user's application info If the sample meets all verification criteria and can be processed without manual intervention, the summary.action field is set to "Pass". If the sample requires further review or manual verification, the summary.action field is set to "Manual_review". |
| action | string | The final decision or action taken based on the assessment |
Failure Response
When the image is not of a Sales PDF document, the JSON output might contain null or random values.
Error Responses
The following are some error responses from the Sales PDF OCR API:
- Missing Input File
- Invalid File Type
- Incorrect Document Type
{
"status": "failure",
"statusCode": 400,
"error": "Invalid input passed for field 'pdfFile'",
}
{
"status": "failure",
"statusCode": 400,
"error": "Invalid file type for: 'pdfFile'",
}
{
"status": "failure",
"statusCode": 422,
"error": "Document Not Detected",
"metaData": {
"requestId": "<Request_ID>",
"transactionId": "<Transaction_ID>"
}
}
Failure and Error Response Details
A failure or error response from the module 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 |
|---|---|---|
| 400 | Invalid input passed for field 'pdfFile' | The input value is not a valid entry |
| 400 | Invalid file type for: 'pdfFile' | The input file type is invalid |
| 422 | Document Not Detected | The input file in the request is not a valid Sales PDF document |
| 5xx | Internal Server Error | There was an error with HyperVerge's server. Please contact the HyperVerge team |