RealDoc - Schema Management API

2026-06-30 08:30

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.

The Schema Management API is used to manage document processing templates (Schemas), supporting the creation, update, and query of custom document extraction rules. Currently, only the document information extraction product type (REALDOC_DOCUMENT_EXTRACTION) is supported.

Common Request Parameters

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

Field Name	Data Type	Description
bizId	String	Merchant's business ID, maximum length 64, used to distinguish different requests or tasks. Do not reuse the same `bizId` to avoid confusion in task status or result queries.

Create Schema

API Path

POST /api/v1/zoloz/realdoc/schema/create

API Description

Used to create a Schema.

Request Parameters

Field Name	Data Type	Required	Default Value	Description	Example
bizId	String	Yes	-	Merchant's business ID, used to distinguish different requests or tasks.	20230601001
schemaId	String	Yes	-	Schema identifier. Supports only letters, digits, underscores, and hyphens, maximum length 128. Note: `schemaId` must be unique under the same merchant and cannot be duplicated.	my_custom_schema
productType	String	Yes	-	Product type. Currently only `REALDOC_DOCUMENT_EXTRACTION` (document information extraction) is supported.	REALDOC_DOCUMENT_EXTRACTION
schemaData	Object	Yes	-	Schema definition data. Must conform to JSON Schema Draft 7. See SchemaData Validation for details.	See request example

SchemaData Validation

The schemaData field must conform to JSON Schema Draft 7 and is subject to the following restrictions:

Category	Description
Supported Fields (24 in total)	`type`, `format`, `title`, `description`, `nullable`, `default`, `items`, `minItems`, `maxItems`, `prefixItems`, `enum`, `properties`, `propertyOrdering`, `required`, `minProperties`, `maxProperties`, `additionalProperties`, `minimum`, `maximum`, `minLength`, `maxLength`, `pattern`, `example`, `anyOf`
Unsupported Fields (rejected)	`$ref`, `$defs`, `allOf`, `oneOf`, `not`, `if/then/else`, `const`, `patternProperties`, etc. If these fields are used, the system will return a validation failure.
Supported `type` Values	`string`, `number`, `integer`, `boolean`, `object`, `array`, `null`

Response Parameters

Field Name

Data Type

Description

Example

result

Result

API request result, containing result status, result code, and result message.

{

"resultStatus": "S",

"resultCode": "SUCCESS",

"resultMessage": "Success"

}

schemaId

String

The identifier of the successfully created Schema.

my_custom_schema

Request Example

copy
{
    "bizId": "20230601001", 
    "schemaId": "my_custom_schema", 
    "productType": "REALDOC_DOCUMENT_EXTRACTION", 
    "schemaData": {
        "type": "object", 
        "properties": {
            "company_name": {
                "type": "string", 
                "description": "Company name"
            }, 
            "registration_number": {
                "type": "string", 
                "description": "Company registration number"
            }, 
            "registered_address": {
                "type": "string", 
                "description": "Registered address"
            }
        }, 
        "required": [
            "company_name"
        ]
    }
}

Response Example

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "schemaId": "my_custom_schema"
}

Update Schema

API Path

POST /api/v1/zoloz/realdoc/schema/update

API Description

Used to update a Schema.

Request Parameters

Field Name	Data Type	Required	Default Value	Description	Example
bizId	String	Yes	-	Merchant's business ID, used to distinguish different requests or tasks.	20230601002
schemaId	String	Yes	-	Schema identifier to be updated. Supports only letters, digits, underscores, and hyphens, maximum length 128.	my_custom_schema
schemaData	Object	Yes	-	New Schema definition data. See SchemaData Validation for details.	See request example

Response Parameters

Field Name

Data Type

Description

Example

result

Result

API request result, containing result status, result code, and result message.

{

"resultStatus": "S",

"resultCode": "SUCCESS",

"resultMessage": "Success"

}

Request Example

copy
{
    "bizId": "20230601002", 
    "schemaId": "my_custom_schema", 
    "schemaData": {
        "type": "object", 
        "properties": {
            "company_name": {
                "type": "string", 
                "description": "Company name"
            }, 
            "registration_number": {
                "type": "string", 
                "description": "Company registration number"
            }, 
            "registered_address": {
                "type": "string", 
                "description": "Registered address"
            }, 
            "incorporation_date": {
                "type": "string", 
                "description": "Date of incorporation"
            }
        }, 
        "required": [
            "company_name", 
            "registration_number"
        ]
    }
}

Response Example

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

Query Schema

API Path

POST /api/v1/zoloz/realdoc/schema/query

API Description

Used to query Schemas. It supports querying a single Schema or querying the active versions of all Schemas under the current merchant.

Request Parameters

Field Name	Data Type	Required	Default Value	Description	Example
bizId	String	Yes	-	Merchant's business ID, used to distinguish different requests or tasks.	20230601003
schemaId	String	Yes	-	Schema identifier to query. Supported values: Pass a specified `schemaId` to query a single Schema. Pass `All` to query the active versions of all Schemas under the current merchant.	my_custom_schema
productType	String	No	null	Product type, used to filter query results. Currently only `REALDOC_DOCUMENT_EXTRACTION` (document information extraction) is supported.	REALDOC_DOCUMENT_EXTRACTION

Response Parameters

Field Name

Data Type

Description

Example

result

Result

API request result, containing result status, result code, and result message.

{

"resultStatus": "S",

"resultCode": "SUCCESS",

"resultMessage": "Success"

}

schemas

List<SchemaItem>

Schema list, containing only the active version data.

See response example

SchemaItem Field Description

Field Name	Data Type	Description	Example
schemaId	String	Schema identifier.	my_custom_schema
productType	String	Product type.	REALDOC_DOCUMENT_EXTRACTION
schemaData	Object	Schema definition data, i.e., the specific content of the active version.	See response example

Request Example

Example 1: Query a single Schema

copy
{
    "bizId": "20230601003", 
    "schemaId": "my_custom_schema"
}

Example 2: Query all Schemas

copy
{
    "bizId": "20230601003", 
    "schemaId": "All"
}

Example 3: Query all Schemas under a specific product type

copy
{
    "bizId": "20230601003", 
    "schemaId": "All", 
    "productType": "REALDOC_DOCUMENT_EXTRACTION"
}

Response Example

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "schemas": [
        {
            "schemaId": "my_custom_schema", 
            "productType": "REALDOC_DOCUMENT_EXTRACTION", 
            "schemaData": {
                "type": "object", 
                "properties": {
                    "company_name": {
                        "type": "string", 
                        "description": "Company name"
                    }, 
                    "registration_number": {
                        "type": "string", 
                        "description": "Company registration number"
                    }, 
                    "registered_address": {
                        "type": "string", 
                        "description": "Registered address"
                    }
                }, 
                "required": [
                    "company_name"
                ]
            }
        }
    ]
}

API Result Codes

The result codes for the Schema Management API are listed in the table below.

resultCode	resultStatus	Description
SUCCESS	S	Operation successful.
PARAMETER_ERROR	F	Request parameter error. Possible causes include: schemaId is empty schemaId format is invalid productType is not supported schemaData validation failed
CLIENT_BUSINESS_ERROR	F	Client business error. Possible causes include: Schema already exists Schema does not exist Product type mismatch Version conflict or update conflict Product unavailable (merchant has no available quota)
INTERNAL_BUSINESS_ERROR	F	Internal business error. Possible causes include: Schema creation failed Schema update failed
SYSTEM_ERROR	F	System error. Service temporarily unavailable.