RealDoc - Async API Documentation

2026-06-02 09:45

Important Notice:

All request and response parameters are strictly subject to the official API documentation.
The API response may contain fields not defined in the documentation. These fields are for internal debugging purposes only and are not guaranteed to be stable or compatible. Do not rely on these fields in production environments. ZOLOZ reserves the right to modify or remove these fields at any time without prior notice.

Overview

RealDoc provides asynchronous document processing capabilities and currently supports the following features:

Document Information Extraction
Document Forgery Detection
Document Insight
Document Cross-Matching
Document Parsing (Markdown)

Common Parameters

Request Common Parameters

All interface requests use HTTP POST method with Content-Type: application/json.

Field Name	Type	Description
bizId	String	business id max is 64

Response Common Parameters

All interface responses contain the following common fields:

Field Name	Type	Description
result	Result Object	Response result
transactionId	String	Transaction ID

Result Object Structure

Field Name	Type	Description
resultCode	String	Result code
resultMessage	String	Result message
resultStatus	String	Result status, "`S`" for success, "`F`" for failure

API List

Asynchronous Document Upload Interface

API Path

POST /api/v1/zoloz/realdoc/async/upload

Description

Used to submit an asynchronous document processing task. Upon successful submission, the returned transactionId can be used to query the task status and the corresponding processing result.

Request Parameters

Parameter Name	Type	Required	Description	Example Value
bizId	String	Yes	Business ID	20230601001
productType	String	Yes	Product type. Valid values: `REALDOC_FORGERY_DETECTION`: Document Forgery Detection `REALDOC_DOCUMENT_EXTRACTION`: Document Information Extraction `REALDOC_DOCUMENT_INSIGHT`: Document Insight `REALDOC_CROSS_MATCHING`: Document Cross-Matching `REALDOC_DOCUMENT_PARSING`: Document Parsing (Markdown)	REALDOC_DOCUMENT_EXTRACTION
fileType	String	No	File type (pdf, jpg/jpeg, png, webp, bmp, and tiff)	pdf
schemaId	String	No	Schema ID for document validation rules. This parameter is required only when `productType` is set to `REALDOC_DOCUMENT_EXTRACTION`. Valid values: `companies_registry_v1`: Company registration certificate `business_registration_certificate_v1`: Business registration certificate `invoice_v1`: Invoice `receipt_v1`: Receipt `bank_statement_v1`: Bank statement `mys_birth_certificate_v1`: Malaysia birth certificate	bank_statement_v1
fileContent	String	No	The document file to be processed. It must be Base64-encoded before being passed. The maximum file size is 10MB. Note: Except for cross-matching scenarios, either `fileContent` or `fileUrl` must be provided. If both are provided, `fileUrl` will be used.	/9j/4AAQSkZJRgABAQAAlgCWAAD/4QCARXhpZgAA
fileUrl	String	No	File URL address. Note: Except for cross-matching scenarios, either `fileContent` or `fileUrl` must be provided. If both are provided, `fileUrl` will be used.	https://example.com/file.pdf
documents	List	No	The list of documents used in cross-matching scenarios. This parameter is required when `productType` is set to `REALDOC_CROSS_MATCHING`, and exactly two documents must be provided.	[ { "fileType": "pdf", "fileUrl": "https://example.com/file-a.pdf" }, { "fileType": "pdf", "fileUrl": "https://example.com/file-b.pdf" } ]

Document Object Structure

Field Name	Type	Required	Description	Example
fileType	String	No	Specifies the file type. Supported file types include: pdf, jpg, jpeg, png, webp, bmp, tiff.	pdf
fileContent	String	No	The document file to be compared. It must be Base64-encoded before being passed. The maximum file size is 10MB. Note: Either `fileContent` or `fileUrl` must be provided.	/9j/4AAQSkZJRgABAQAAlgCWAAD/4QCARXhpZgAA
fileUrl	String	No	The URL address of the document to be compared. Note: Either `fileContent` or `fileUrl` must be provided.	https://example.com/file-a.pdf

Response Parameters

Field Name	Type	Description
transactionId	String	Transaction ID it can be used to query the status and results of a task
result	Result Object	Response result

Request Example

Document Information Extraction:

copy
{
    "bizId": "20230601001", 
    "productType": "REALDOC_DOCUMENT_EXTRACTION", 
    "fileType": "pdf", 
    "fileContent": "/9j/4AAQSkZJRgABAQAAlgCWAAD/4QCARXhpZgAA", 
    "schemaId": "bank_statement_v1"
}

Document Insight:

copy
{
    "bizId": "20230601002", 
    "productType": "REALDOC_DOCUMENT_INSIGHT", 
    "fileType": "pdf", 
    "fileUrl": "https://example.com/document.pdf", 
    "schemaId": "general_insight_v1"
}

Document Cross-Matching:

copy
{
    "bizId": "20230601003", 
    "productType": "REALDOC_CROSS_MATCHING", 
    "schemaId": "general_cross_matching_v1", 
    "documents": [
        {
            "fileType": "pdf", 
            "fileUrl": "https://example.com/file-a.pdf"
        }, 
        {
            "fileType": "pdf", 
            "fileUrl": "https://example.com/file-b.pdf"
        }
    ]
}

Document Parsing (Markdown):

copy
{
    "bizId": "20230601004", 
    "productType": "REALDOC_DOCUMENT_PARSING", 
    "fileType": "pdf", 
    "fileUrl": "https://example.com/document.pdf", 
    "schemaId": "general_text_parsing_v1"
}

Response Example

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "transactionId": "R00000020250926155511ff792165"
}

Task Status Query Interface

API Path

POST /api/v1/zoloz/realdoc/async/status

Description

Used to query the execution status of asynchronous tasks.

Request Parameters

Parameter Name	Type	Required	Description	Example Value
bizId	String	Yes	Business ID	20230601001
transactionId	String	Yes	Transaction ID returned from upload interface	R00000020250926155511ff792165

Response Parameters

Field Name	Type	Description
result	Result Object	Response result
transactionId	String	Transaction ID
status	String	Task status (Processing, Success, Failure)

Request Example

copy
{
  "bizId": "20230601001",
  "transactionId": "R-1234567890abcdef"
}

Response Example

copy
{
  "result": {
    "resultStatus": "S",
    "resultCode": "SUCCESS",
    "resultMessage": "Success"
  },
  "transactionId": "R000000202509261556320d7d1c44",
  "status": "Processing"
}

Document Extraction Async Result Query Interface

API Path

POST /api/v1/zoloz/realdoc/async/documentparse/result

Description

Used to query the results of asynchronous document extraction, returning the same response format as the synchronous interface.

Request Parameters

Parameter Name	Type	Required	Description	Example Value
bizId	String	Yes	Business ID	20230601001
transactionId	String	Yes	Transaction ID returned from upload interface	R000000202510111032563d0e515f

Response Parameters

Field Name	Type	Description
result	Result Object	Response result
transactionId	String	Transaction ID
data	Map<String, Object>	Extracted information in string format

Request Example

copy
{
  "bizId": "20230601001",
  "transactionId": "R000000202510111032563d0e515f"
}

Response Example

copy
{
        "account_holders_name": "MS. IxxG",
        "account_number": "91802xxxxx04",
        "bank_name": "AXIS BANK",
        "starting_balance": "47315.01",
        "ending_balance": "115368.01",
        "deposits_and_credits": "372700.00",
        "withdrawals_and_debits": "304647.00",
        "scheme_code": "CA- LARGE RETAILERS AND DISTRIBUTORS",
        "customer_id": "88xxx0",
        "currency": "INR",
        "lien_amount": "0.00",
        "nomination_details": "NOMINATION REGISTERED",
        "PIN": "11xxx1",
        "details": [
            {
                "date": "10/04/2019",
                "description": "MOB/SELFFT/SURJEET SINGH/9130100",
                "balance": "315.01"
            },
            {
                "date": "13/04/2019",
                "description": "GST @18% on Charge",
                "balance": "2028.81"
            }
        ]
    }

Document Insight Async Result Query Interface

API Path

POST /api/v1/zoloz/realdoc/async/documentinsight/result

Description

Used to retrieve asynchronous document insight results. Document insight performs a comprehensive analysis of a document and returns a risk score, an executive summary, detailed insights, and, where applicable, the locations of detected risks.

Request Parameters

Field Name	Data type	Required	Description	Example
bizId	String	Yes	Merchant's business ID, used to distinguish different requests or tasks.	20230601002
transactionId	String	Yes	Transaction ID returned from upload interface.	R00000020251011105012a1b2c3d4

Response Parameters

Field Name	Data type	Description	Example
result	Result	The API request result, which contains information about the result of the API request, such as status and error codes.	{ "resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success" }
transactionId	String	Transaction ID returned by ZOLOZ.	R00000020251011105012a1b2c3d4
summary	Summary	Summary of the document insight result.	See response example
tamperInfo	List	Details of risk or tampering locations. Returned only when such risks are detected.	See response example

Summary Object Structure

Field Name	Data type	Description	Example
overallRiskScore	Double	Overall risk score, ranging from 0 to 100. The higher the score, the higher the document risk.	82
executiveSummary	String	Summary of the insight result.	The document shows several risk indicators.
insightInfo	String	Detailed insight information.	The invoice amount and tax section require manual review.

TamperInfo Object Structure

Field Name	Data type	Description	Example
content	String	Content of the risk or tampering area.	Invoice Amount
location	Double[]	Bounding box coordinates of the risk or tampering area, in the format [x1, y1, x2, y2].	[ 0.365, 0.281, 0.582, 0.318 ]
explanation	String	Explanation of the risk or tampering detection.	The amount field is inconsistent with the tax details.
page	Integer	Page number where the risk or tampering is located.	1

Request Example

copy
{
    "bizId": "20230601002", 
    "transactionId": "R00000020251011105012a1b2c3d4"
}

Response Example

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "transactionId": "R00000020251011105012a1b2c3d4", 
    "summary": {
        "overallRiskScore": 82, 
        "executiveSummary": "The document shows several risk indicators and should be reviewed manually.", 
        "insightInfo": "The invoice amount and tax section require manual review."
    }, 
    "tamperInfo": [
        {
            "content": "Invoice Amount", 
            "location": [
                0.365, 
                0.281, 
                0.582, 
                0.318
            ], 
            "explanation": "The amount field is inconsistent with the tax details.", 
            "page": 1
        }
    ]
}

Document Forgery Detection Async Result Query Interface

API Path

POST /api/v1/zoloz/realdoc/async/fraudcheck/result

Description

Used to query the results of asynchronous document forgery detection, returning the same response format as the synchronous interface.

Request Parameters

Parameter Name	Type	Required	Description	Example Value
bizId	String	Yes	Business ID	20230601001
transactionId	String	Yes	Transaction ID returned from upload interface	R-1234567890abcdef

Response Parameters

Field Name	Type	Description
result	Result Object	Response result
transactionId	String	Transaction ID
summary	Summary Object	Forgery detection result summary
tamperInfo	List<TamperInfo>	Possible tampering of information

Summary Object Structure

Field Name	Type	Description
overallRiskScore	Double	Overall risk score (0-100) Score from 0 to 100; the higher the score, the higher the risk of forgery
executiveSummary	String	Executive summary of results This describes the document identification result; for higher scores, it provides specific risk details.

TamperInfo Object Structure

Field Name	Type	Description
content	String	Content of the tampered area
location	Double	Location coordinates [x1, y1, x2, y2], represents the bounding box of the tampered content
explanation	String	Explanation of the tampering detection
page	Integer	The page containing the tampered location.

Request Example

copy
{
  "bizId": "20230601001",
  "transactionId": "R00000020251011103904dd53c8ff"
}

Response Example

Normal case

copy
{
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "Success"
    },
    "summary": {
        "overallRiskScore": 5.0,
        "executiveSummary": "Based on the comprehensive visual and logical analysis, no evidence of digital forgery or malicious alteration was found. All examined regions of the document, including the dates, price, names, and official seal, are consistent with the characteristics of an authentically generated official document. Therefore, no forged locations have been identified."
    },
    "transactionId": "R000000202510111040423dc6af95"
}

Tampering case

copy
{
    "result": {
        "resultCode": "SUCCESS",
        "resultStatus": "S",
        "resultMessage": "Success"
    },
    "transactionId": "R00000020251020115123c7c15c40",
    "summary": {
        "overallRiskScore": 95.0,
        "executiveSummary": "Despite internal consistency and high template quality, the document exhibits deliberate tampering through malicious obscuration of critical identifying information (Customer Name and Correspondence Address) using black blocks, indicating a high likelihood of forgery."
    },
    "tamperInfo": [
  {
    "content": "5",
    "explanation": "The digit '5' in the 'Invoice Date' field exhibits font and rendering inconsistency, appearing marginally bolder with different sharpness and anti-aliasing. A subtle background halo around it suggests a copy-paste operation.",
    "location": [
      0.865,
      0.281,
      0.882,
      0.318
    ],
    "page": 1
  }
]
}

Document Cross-Matching Async Result Query Interface

API Path

POST /api/v1/zoloz/realdoc/async/crossmatch/result

Description

Used to retrieve asynchronous document cross-matching results. Cross-matching compares the key information between two documents to determine consistency, and returns an overall match result, a match score, and field-level comparison details.

Request Parameters

Field Name	Data type	Required	Description	Example
bizId	String	Yes	Merchant's business ID, used to distinguish different requests or tasks.	20230601003
transactionId	String	Yes	Transaction ID returned from upload interface.	R00000020251011110012e5f6g7h8

Response Parameters

Field Name	Data type	Description	Example
result	Result	The API request result, which contains information about the result of the API request, such as status and error codes.	{ "resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success" }
transactionId	String	Transaction ID returned by ZOLOZ.	R00000020251011110012e5f6g7h8
overallMatchResult	String	Overall match result, e.g., `True`, `False`, `None`.	True
overallMatchScore	Double	Overall match score, ranging from 0 to 100.	92.5
executiveSummary	String	Summary of the matching result.	High similarity detected.
matchingInfo	List	Field-level matching details.	See response example

MatchInfo Object Structure

Field Name	Data type	Description	Example
field	String	Name of the field being compared.	address
value1	String	Field value from the first document.	123 Main St
value2	String	Field value from the second document.	123 Main St
explanation	String	Explanation of the field match result.	Address matches exactly.

Request Example

copy
{
    "bizId": "20230601003", 
    "transactionId": "R00000020251011110012e5f6g7h8"
}

Response Example

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "transactionId": "R00000020251011110012e5f6g7h8", 
    "overallMatchResult": "True", 
    "overallMatchScore": 92.5, 
    "executiveSummary": "High similarity detected between the two documents.", 
    "matchingInfo": [
        {
            "field": "address", 
            "value1": "123 Main St", 
            "value2": "123 Main St", 
            "explanation": "Address matches exactly."
        }, 
        {
            "field": "company_name", 
            "value1": "Example Trading Ltd.", 
            "value2": "Example Trading Limited", 
            "explanation": "Company names are semantically equivalent."
        }
    ]
}

Document Parsing (Markdown) Async Result Query Interface

API Path

POST /api/v1/zoloz/realdoc/async/documentparsemarkdown/result

Description

Used to retrieve asynchronous document parsing (Markdown) results. Document parsing converts document content into structured text or Markdown format. The return format is consistent with the document parsing response model, and the specific content of the data field is determined by the parsing template and the document content.

Request Parameters

Field Name	Data type	Required	Description	Example
bizId	String	Yes	Merchant's business ID, used to distinguish different requests or tasks.	20230601004
transactionId	String	Yes	Transaction ID returned from upload interface.	R00000020251011112012i9j0k1l2

Response Parameters

Field Name	Data type	Description	Example
result	Result	The API request result, which contains information about the result of the API request, such as status and error codes.	{ "resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success" }
transactionId	String	Transaction ID returned by ZOLOZ.	R00000020251011112012i9j0k1l2
data	Map<String, Object>	Document parsing result. Typically contains Markdown text, sections, tables, or summaries. The actual returned fields depend on the parsing template used.	See response example

Request Example

copy
{
    "bizId": "20230601004", 
    "transactionId": "R00000020251011112012i9j0k1l2"
}

Response Example

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "data": {
        "markdown_base64": "base64content"
    }, 
    "transactionId": "R00000020251011112012i9j0k1l2"
}

Product Type Description

Product Type	Description
REALDOC_FORGERY_DETECTION	Document forgery detection
REALDOC_DOCUMENT_EXTRACTION	Document extraction

Task Status Description

Status	Description
Processing	Task is being processed
Success	Task completed successfully
Failure	Task execution failed

Important Notes

Document Upload Method

For the Upload Document API, except in cross-matching scenarios, either fileContent or fileUrl is required. If both are provided, fileUrl has priority.
In cross-matching scenarios, two documents must be included in the documents array. For each document, either fileContent or fileUrl must be provided.

Quota Limit
If the merchant has no available quota, the PRODUCT_NOT_AVAILABLE error will be returned.
Billing
For asynchronous processing, billing will be charged as long as the processing is successful, regardless of whether the results are queried.
Task Processing Flow

After the task is successfully submitted, it is recommended to poll the task status using the Query Task Status API. Only query the result when the task status is Success.
When the task status is Success, the system will return the specific processing results. When the task status is Failure, the system will return the failure reason. Refer to the resultMessage field for details and diagnose the issue based on the provided information.

Rate Limits
Some APIs have rate limits. If you encounter rate limiting issues, please contact ZOLOZ Technical Support.