Get records

Returns a page of records using filters, keyword, time range, and pagination. Supports json, json-ld, and markdown.

This page covers list-specific query and paging semantics. Each element of data.list[] has the same shape as data.data from Get a single record for the same format.

Request example

Python + requestscurl

python

import requests

url = 'https://open.cli.im/api/v2/rpc/record/getRecords'
data = {
    'filters': {
        'record_template': {'id': 122507},
        'qrcode': {'id': 6762875}
    },
    'format': 'json',
    'search_key': '张三',
    'record_type': 0,
    'page_size': 10,
    'get_total_count': 1
}
headers = {
    'Authorization': 'Bearer <your API Key>',
    'Content-Type': 'application/json'
}
response = requests.post(url, json=data, headers=headers)
print(response.text)

bash

curl -X POST 'https://open.cli.im/api/v2/rpc/record/getRecords' \
  -H 'Authorization: Bearer <your API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"filters": {"record_template": {"id": 122507}, "qrcode": {"id": 6762875}}, "format": "json", "page_size": 10}'

Request parameters

Parameter	Type	Required	Description
`format`	string	No	Output format, default `json`. Values: `json`, `json-ld`, `markdown`
`search_key`	string	No	Fuzzy full-text search across field contents
`filters`	object	No	Filter object; see “`filters` fields” below
`record_type`	integer	No	Record type: `0` all, `3` state change, `7` subcode edit. Default `0`
`start_time`	string \| integer	No	Start time: Unix timestamp or ISO 8601 string
`end_time`	string \| integer	No	End time: Unix timestamp or ISO 8601 string
`page_size`	integer	No	Page size, max 50, default 10
`page_token`	string	No	Cursor from the previous response
`last_record_id`	integer	No	Offset: fetch records after this ID
`order_by`	string	No	`{field},{direction}`. Supports `submit_at,desc` and `submit_at,asc`; default `submit_at,desc`
`get_total_count`	integer	No	`1` return total count, `0` skip total for speed. Default `1`

`filters` fields

filters is optional; sub-fields can be combined.

Default scope:

Omitting filters queries within what the API key can see, usually the current org.
Without filters.qrcode.id, results are not restricted by QR code; with only filters.record_template.id, you get records for that form.
Without filters.record_template.id, results are not restricted by form; with only filters.qrcode.id, you get records for that QR code.
With both filters.qrcode.id and filters.record_template.id, you get records for that QR code and that form.
Other filters.* combine with AND semantics.

`filters.record_template`

Field	Type	Description
`id`	integer	Form template ID

`filters.qrcode`

Field	Type	Description
`id`	integer	QR code ID (single)
`template_id`	integer	Template ID (batch template codes)
`category_id`	integer	QR code category ID (single)

`filters.project`

Field	Type	Description
`id`	integer	Project (partition) ID

`filters.audit`

Field	Type	Description
`stage_id`	integer	Audit stage ID
`status`	integer	Audit status: `0` pending / `1` approved / `2` rejected; omit for all

`filters.process_status`

Field	Type	Description
`text`	string	Process status text, exact match; see form `process_status_config`

`filters.state_changes`

Field	Type	Description
`state_id`	integer	State group ID—records that triggered this state change

`filters.recorder`

Field	Type	Description
`auth_id`	integer	Submitter `auth_id` (Caoliao user auth ID)

Output format overview

Request `format`	`data.list[]` type	Item content	Typical use
`json`	object	Same as `data.data` for `format=json` in Get a single record	Parsing, sync, field-level work
`json-ld`	object	Same as `format=json-ld` `data.data` there	Semantic exchange, graphs
`markdown`	string	Same as `format=markdown` `data.data` there	Reading, export, LLM ingestion

Full response skeleton

The blocks below show success skeletons for three formats.

format=jsonformat=json-ldformat=markdown

json

{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [
      {
        "record_id": 1039879,
        "record_number": "L10610",
        "record_code": "ru6gdTee",
        "record_url": "https://qr46.cn/o4dilp/q0og7BW",
        "submit_at": 1763102668,
        "submit_at_iso": "2025-11-14 14:44:28(UTC+08:00)",
        "submit_method": "微信其他入口填写",
        "recorder": { "auth_id": 16559, "user_id": 831988, "name": "黄**" },
        "project": { "id": 329, "name": "演示会内容", "number": "F2" },
        "qrcode": { "id": 4698286, "name": "灭火器巡检", "type": 0, "type_text": "普通二维码" },
        "org": { "id": 94884306, "name": "南京噗噗网络科技有限公司765", "code": "o4dilp" },
        "record_template": { "id": 25732, "name": "灭火器巡检", "type": 0, "type_text": "普通表单", "number": "D510" },
        "audit": { "enabled": false, "current_stage_id": null, "status": null, "status_text": null },
        "process_status": { "enabled": false, "text": null, "color": null },
        "state_changes": [],
        "tpl_groups": [
          {
            "group_id": 27178,
            "group_title": "",
            "show_group_title": false,
            "is_page_break_group": false,
            "fields": [
              { "field_id": 153984, "field_title": "AI智能填表图片", "field_type": "image", "field_value": [{ "url": "https://ncstatic.clewm.net/rsrc/example.jpg" }] }
            ]
          }
        ]
      }
    ],
    "next_page_token": "CAESKAoVChMKD3JlY29yZF9hZGRfdGltZRAB...",
    "total": 36
  }
}

json

{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [
      {
        "@context": "https://schema.org",
        "@type": "CreativeWork",
        "identifier": "ru6gdTee",
        "name": "灭火器巡检-L10610",
        "url": "https://qr46.cn/o4dilp/q0og7BW",
        "mainEntity": { "@type": "ItemList", "name": "组件数据" }
      }
    ],
    "next_page_token": "CAESKAoVChMKD3JlY29yZF9hZGRfdGltZRAB...",
    "total": 36
  }
}

json

{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [
      "---\\ntitle: 灭火器巡检-L10610\\nrecord_id: 1039879\\n...\\n---\\n\\n# 灭火器巡检-L10610\\n\\n## 基本信息\\n\\n**记录编号：** L10610"
    ],
    "next_page_token": "CAESKAoVChMKD3JlY29yZF9hZGRfdGltZRAB...",
    "total": 36
  }
}

Response overview

Path	Type	Description
`code`	integer	Platform code; `0` success
`message`	string	Message
`data`	object	Wrapper
`data.list`	array	Records; element type depends on `format`
`data.next_page_token`	string	Next page cursor; often `""` when none
`data.total`	integer	Total matches; accurate when `get_total_count=1`

List items and `getRecord`

getRecords does not define a separate record schema. For a given format, each data.list[] element is identical to data.data from Get a single record.

For field definitions, tpl_groups structure, and field_type/field_value mapping, see Get a single record and Field types overview. Per-format schemas (reused from getRecord):

content-json.schema.json (json payload schema)

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "content-json.schema.json",
  "title": "record/getRecord content schema (format=json)",
  "description": "`record/getRecord` 在 `format=json` 时 `data.data` 的结构定义。用于说明记录详情对象本体，不含最外层 code/message/data 包装。",
  "type": "object",
  "required": [
    "record_id",
    "record_number",
    "record_code",
    "record_url",
    "submit_at",
    "submit_at_iso",
    "submit_method",
    "tpl_groups",
    "recorder",
    "qrcode",
    "org",
    "record_template"
  ],
  "properties": {
    "record_id": {
      "type": "integer",
      "description": "记录ID（企业下唯一）"
    },
    "record_number": {
      "type": "string",
      "description": "记录编号（企业内唯一）"
    },
    "record_code": {
      "type": "string",
      "description": "记录code（平台唯一）"
    },
    "record_url": {
      "type": "string",
      "format": "uri",
      "description": "记录码访问地址（平台唯一）"
    },
    "submit_at": {
      "type": "integer",
      "description": "记录提交时间（Unix 时间戳，秒）"
    },
    "submit_at_iso": {
      "type": "string",
      "description": "记录提交时间（格式：Y-m-d H:i:s(UTC+08:00)）"
    },
    "submit_method": {
      "type": "string",
      "description": "记录填写方式，如\"扫一扫填写\"、\"手动添加\"等"
    },
    "recorder": {
      "$ref": "#/$defs/Recorder"
    },
    "tpl_groups": {
      "type": "array",
      "description": "模板分组列表，每个分组包含若干字段",
      "items": {
        "$ref": "#/$defs/TplGroup"
      }
    },
    "project": {
      "$ref": "#/$defs/Project"
    },
    "qrcode": {
      "$ref": "#/$defs/Qrcode"
    },
    "org": {
      "$ref": "#/$defs/Org"
    },
    "record_template": {
      "$ref": "#/$defs/RecordTemplate"
    },
    "audit": {
      "$ref": "#/$defs/Audit"
    },
    "process_status": {
      "$ref": "#/$defs/ProcessStatus"
    },
    "state_changes": {
      "type": "array",
      "description": "状态变更记录列表",
      "items": {
        "$ref": "#/$defs/StateChange"
      }
    }
  },
  "additionalProperties": false,
  "$defs": {
    "Recorder": {
      "type": "object",
      "description": "记录提交人信息",
      "required": [
        "auth_id",
        "user_id",
        "name"
      ],
      "properties": {
        "auth_id": {
          "type": "integer",
          "description": "提交人权限ID"
        },
        "user_id": {
          "type": "integer",
          "description": "提交人用户ID"
        },
        "name": {
          "type": "string",
          "description": "提交人姓名"
        }
      },
      "additionalProperties": false
    },
    "Project": {
      "type": "object",
      "description": "所属项目信息",
      "required": [
        "id",
        "name",
        "number"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "description": "项目ID"
        },
        "name": {
          "type": "string",
          "description": "项目名称"
        },
        "number": {
          "type": "string",
          "description": "项目编号"
        }
      },
      "additionalProperties": false
    },
    "Qrcode": {
      "type": "object",
      "description": "关联二维码信息",
      "required": [
        "id",
        "name",
        "type",
        "type_text",
        "template_id",
        "qrcode_url",
        "number"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "description": "二维码ID"
        },
        "name": {
          "type": "string",
          "description": "二维码名称"
        },
        "type": {
          "type": "integer",
          "description": "二维码类型（0=普通二维码）"
        },
        "type_text": {
          "type": "string",
          "description": "二维码类型文本"
        },
        "template_id": {
          "type": "integer",
          "description": "二维码模板ID"
        },
        "qrcode_url": {
          "type": "string",
          "format": "uri",
          "description": "二维码短链接地址"
        },
        "number": {
          "type": "string",
          "description": "二维码编号"
        },
        "category_id": {
          "type": [
            "integer",
            "null"
          ],
          "description": "目录ID"
        }
      },
      "additionalProperties": false
    },
    "Org": {
      "type": "object",
      "description": "所属组织/企业信息",
      "required": [
        "id",
        "name",
        "code",
        "logo_url"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "description": "企业ID（平台唯一）"
        },
        "name": {
          "type": "string",
          "description": "企业名称"
        },
        "code": {
          "type": "string",
          "description": "企业唯一编码"
        },
        "logo_url": {
          "type": "string",
          "format": "uri",
          "description": "企业Logo URL"
        }
      },
      "additionalProperties": false
    },
    "RecordTemplate": {
      "type": "object",
      "description": "记录模板（表单）信息",
      "required": [
        "id",
        "name",
        "type",
        "type_text",
        "number"
      ],
      "properties": {
        "id": {
          "type": [
            "integer",
            "null"
          ],
          "description": "表单ID"
        },
        "name": {
          "type": [
            "string",
            "null"
          ],
          "description": "表单名称"
        },
        "type": {
          "type": [
            "integer",
            "null"
          ],
          "description": "表单类型：0/1/2=普通表单, 3=保密承诺系统表单, 7=码状态手动变更记录系统表单, 12=身份组成员申请加入记录表单, 13=子码编辑记录系统表单, 21=码留言记录系统表单, 22=码协作记录系统表单",
          "enum": [
            null,
            0,
            1,
            2,
            3,
            7,
            12,
            13,
            21,
            22
          ]
        },
        "type_text": {
          "type": [
            "string",
            "null"
          ],
          "description": "表单类型说明"
        },
        "number": {
          "type": [
            "string",
            "null"
          ],
          "description": "表单编号"
        }
      },
      "additionalProperties": false
    },
    "Audit": {
      "type": "object",
      "description": "当前审核阶段信息（仅在启用审核时出现）",
      "required": [
        "enabled"
      ],
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "是否启用审核"
        },
        "current_stage_id": {
          "type": [
            "integer",
            "null"
          ],
          "description": "当前审核阶段ID"
        },
        "current_stage_title": {
          "type": [
            "string",
            "null"
          ],
          "description": "当前审核阶段名称"
        },
        "status": {
          "type": [
            "integer",
            "null"
          ],
          "description": "审核状态码（0=待审核, 1=审核通过, 2=审核拒绝）"
        },
        "status_text": {
          "type": [
            "string",
            "null"
          ],
          "description": "审核状态文本"
        },
        "auditor_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "审核人姓名"
        }
      },
      "additionalProperties": false
    },
    "ProcessStatus": {
      "type": "object",
      "description": "处理状态信息（仅在启用处理状态时出现）",
      "required": [
        "enabled"
      ],
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "是否启用处理状态"
        },
        "text": {
          "type": [
            "string",
            "null"
          ],
          "description": "当前处理状态文本"
        },
        "color": {
          "type": [
            "string",
            "null"
          ],
          "description": "状态颜色（Hex 格式，如 #155EB7）"
        }
      },
      "additionalProperties": false
    },
    "StateChange": {
      "type": "object",
      "description": "单条状态变更记录",
      "required": [
        "state",
        "from_state_option",
        "to_state_option"
      ],
      "properties": {
        "state": {
          "type": "object",
          "description": "状态定义",
          "required": [
            "id",
            "name",
            "number"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "description": "状态ID"
            },
            "name": {
              "type": "string",
              "description": "状态名称"
            },
            "number": {
              "type": "string",
              "description": "状态编号"
            }
          },
          "additionalProperties": false
        },
        "from_state_option": {
          "$ref": "#/$defs/StateOption"
        },
        "to_state_option": {
          "$ref": "#/$defs/StateOption"
        }
      },
      "additionalProperties": false
    },
    "StateOption": {
      "type": "object",
      "description": "状态选项值",
      "required": [
        "name",
        "color"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "状态选项名称"
        },
        "color": {
          "type": "string",
          "description": "状态选项颜色（Hex 格式）"
        }
      },
      "additionalProperties": false
    },
    "TplGroup": {
      "type": "object",
      "description": "模板分组",
      "required": [
        "group_id",
        "group_title",
        "show_group_title",
        "is_page_break_group",
        "fields"
      ],
      "properties": {
        "group_id": {
          "type": "integer",
          "description": "分组ID"
        },
        "group_title": {
          "type": "string",
          "description": "分组标题（空字符串表示无标题）"
        },
        "show_group_title": {
          "type": "boolean",
          "description": "是否显示分组标题"
        },
        "is_page_break_group": {
          "type": "boolean",
          "description": "是否为分页标记组（分页组的 fields 通常为空数组）"
        },
        "fields": {
          "type": "array",
          "description": "分组内的字段列表",
          "items": {
            "$ref": "#/$defs/Field"
          }
        }
      },
      "additionalProperties": false
    },
    "Field": {
      "type": "object",
      "description": "单个表单字段",
      "required": [
        "field_id",
        "field_title",
        "field_type",
        "field_value",
        "options"
      ],
      "properties": {
        "field_id": {
          "type": "integer",
          "description": "字段ID"
        },
        "field_title": {
          "type": "string",
          "description": "字段标题"
        },
        "field_desc": {
          "type": "string",
          "description": "字段描述/提示文字"
        },
        "field_type": {
          "type": "string",
          "description": "字段类型标识",
          "enum": [
            "name",
            "tel",
            "recorder",
            "identity",
            "job_number",
            "text",
            "textarea",
            "date",
            "time",
            "customer_name",
            "customer_mobile",
            "customer_number",
            "carnumber",
            "sex",
            "radio",
            "number",
            "checkbox",
            "checklist",
            "matrix",
            "dynamic_matrix",
            "address",
            "owner_address",
            "chained_selects",
            "image",
            "signature",
            "audio",
            "video",
            "file",
            "description",
            "ocr_id_card",
            "ocr_bank_card",
            "ocr_vehicle_license",
            "ocr_driving_license",
            "ocr_car_number",
            "ocr_car_vin",
            "ocr_business_license",
            "ocr_way_bill",
            "ocr_special_operate",
            "ocr_general_cert",
            "ocr_degree_cert",
            "ocr_diploma_cert",
            "ocr_dashboard_mile",
            "ocr_electric_meter",
            "ocr_water_meter",
            "ocr_hygrother_mograp",
            "ocr_gas_meter",
            "ocr_pressure_meter",
            "ocr_general_meter",
            "ocr_digital_meter",
            "ocr_roll_meter",
            "ocr_pointer_meter",
            "ocr_liquid_column_meter",
            "sub_qrcode_edit_diff"
          ]
        },
        "field_short_name": {
          "type": "string",
          "description": "字段短名称"
        },
        "group_id": {
          "type": "integer",
          "description": "所属分组ID"
        },
        "field_value": {
          "description": "字段值，类型随 field_type 不同而变化，详见 $defs/FieldValue*",
          "oneOf": [
            {
              "$ref": "#/$defs/FieldValueString"
            },
            {
              "$ref": "#/$defs/FieldValueSingleOption"
            },
            {
              "$ref": "#/$defs/FieldValueNumber"
            },
            {
              "$ref": "#/$defs/FieldValueCheckbox"
            },
            {
              "$ref": "#/$defs/FieldValueChecklist"
            },
            {
              "$ref": "#/$defs/FieldValueMatrix"
            },
            {
              "$ref": "#/$defs/FieldValueDynamicMatrix"
            },
            {
              "$ref": "#/$defs/FieldValueAddress"
            },
            {
              "$ref": "#/$defs/FieldValueOwnerAddress"
            },
            {
              "$ref": "#/$defs/FieldValueChainedSelects"
            },
            {
              "$ref": "#/$defs/FieldValueImageList"
            },
            {
              "$ref": "#/$defs/FieldValueAudioList"
            },
            {
              "$ref": "#/$defs/FieldValueVideoList"
            },
            {
              "$ref": "#/$defs/FieldValueFileList"
            },
            {
              "$ref": "#/$defs/FieldValueDescription"
            },
            {
              "$ref": "#/$defs/FieldValueOcr"
            },
            {
              "$ref": "#/$defs/FieldValueSubQrcodeEditChangeList"
            }
          ]
        },
        "options": {
          "$ref": "#/$defs/FieldOptions"
        }
      },
      "additionalProperties": false
    },
    "FieldOptions": {
      "type": "object",
      "description": "字段显示选项",
      "required": [
        "is_result",
        "is_highlight",
        "is_hidden",
        "is_masked"
      ],
      "properties": {
        "is_result": {
          "type": "boolean",
          "description": "是否为结果字段"
        },
        "is_highlight": {
          "type": "boolean",
          "description": "是否高亮显示"
        },
        "is_hidden": {
          "type": "boolean",
          "description": "是否隐藏"
        },
        "is_masked": {
          "type": "boolean",
          "description": "是否脱敏显示"
        }
      },
      "additionalProperties": false
    },
    "FieldValueString": {
      "type": "string",
      "description": "纯文本字段值。适用 field_type: name, tel, recorder, identity, job_number, text, textarea, date, time, customer_name, customer_mobile, customer_number, carnumber"
    },
    "FieldValueSingleOption": {
      "type": "object",
      "description": "单选字段值。适用 field_type: sex, radio",
      "required": [
        "option_text",
        "option_id"
      ],
      "properties": {
        "option_text": {
          "type": "string",
          "description": "选项文本。若选择\"其他\"并填写补充，格式为 \"其他[补充内容]\""
        },
        "option_id": {
          "type": "integer",
          "description": "选项ID"
        }
      },
      "additionalProperties": false
    },
    "FieldValueNumber": {
      "type": "object",
      "description": "数字字段值。适用 field_type: number",
      "required": [
        "value",
        "unit",
        "unit_enabled"
      ],
      "properties": {
        "value": {
          "type": "number",
          "description": "数值"
        },
        "unit": {
          "type": "string",
          "description": "单位文本（无单位时为空字符串）"
        },
        "unit_enabled": {
          "type": "boolean",
          "description": "是否启用单位"
        }
      },
      "additionalProperties": false
    },
    "FieldValueCheckbox": {
      "type": "object",
      "description": "多选字段值。适用 field_type: checkbox",
      "required": [
        "values"
      ],
      "properties": {
        "values": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "option_id",
              "option_text"
            ],
            "properties": {
              "option_id": {
                "type": "integer",
                "description": "选项ID"
              },
              "option_text": {
                "type": "string",
                "description": "选项文本。若选择\"其他\"并填写补充，格式为 \"其他[补充内容]\""
              }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    "FieldValueChecklist": {
      "type": "array",
      "description": "检查清单字段值。适用 field_type: checklist",
      "items": {
        "type": "object",
        "required": [
          "item_id",
          "item_title",
          "value"
        ],
        "properties": {
          "item_id": {
            "type": "integer",
            "description": "检查项ID"
          },
          "item_title": {
            "type": "string",
            "description": "检查项标题"
          },
          "value": {
            "type": "object",
            "required": [
              "option_id",
              "option_text",
              "description",
              "images"
            ],
            "properties": {
              "option_id": {
                "type": "integer",
                "description": "选择的选项ID"
              },
              "option_text": {
                "type": "string",
                "description": "选择的选项文本（如 正常、异常、需要关注）"
              },
              "description": {
                "type": "string",
                "description": "补充描述（无描述时为空字符串）"
              },
              "images": {
                "type": "array",
                "description": "补充图片列表",
                "items": {
                  "$ref": "#/$defs/ImageItem"
                }
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      }
    },
    "FieldValueMatrix": {
      "type": "object",
      "description": "矩阵（单行）字段值。适用 field_type: matrix",
      "required": [
        "columns"
      ],
      "properties": {
        "columns": {
          "type": "array",
          "description": "列数据列表",
          "items": {
            "$ref": "#/$defs/MatrixColumn"
          }
        }
      },
      "additionalProperties": false
    },
    "FieldValueDynamicMatrix": {
      "type": "object",
      "description": "动态矩阵（多行）字段值。适用 field_type: dynamic_matrix",
      "required": [
        "rows"
      ],
      "properties": {
        "rows": {
          "type": "array",
          "description": "行数据列表",
          "items": {
            "type": "object",
            "required": [
              "columns"
            ],
            "properties": {
              "columns": {
                "type": "array",
                "items": {
                  "$ref": "#/$defs/MatrixColumn"
                }
              }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    "MatrixColumn": {
      "type": "object",
      "description": "矩阵中的单个列",
      "required": [
        "column_id",
        "column_title",
        "column_type",
        "value"
      ],
      "properties": {
        "column_id": {
          "type": "integer",
          "description": "列ID"
        },
        "column_title": {
          "type": "string",
          "description": "列标题"
        },
        "column_type": {
          "type": "string",
          "description": "列类型（text, sex, identity, date, owner_address 等）"
        },
        "value": {
          "type": "object",
          "required": [
            "text",
            "option_uuid"
          ],
          "properties": {
            "text": {
              "type": [
                "string",
                "null"
              ],
              "description": "文本值"
            },
            "option_uuid": {
              "type": [
                "string",
                "null"
              ],
              "description": "选项 UUID，非选择类列为 null"
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "FieldValueAddress": {
      "type": "object",
      "description": "地址定位字段值。适用 field_type: address",
      "required": [
        "address",
        "lat",
        "lng"
      ],
      "properties": {
        "address": {
          "type": "string",
          "description": "地址文本"
        },
        "lat": {
          "type": "number",
          "description": "纬度"
        },
        "lng": {
          "type": "number",
          "description": "经度"
        }
      },
      "additionalProperties": false
    },
    "FieldValueOwnerAddress": {
      "type": "object",
      "description": "详细地址字段值（省/市/区/街道/详细）。适用 field_type: owner_address",
      "required": [
        "province",
        "city",
        "district",
        "street",
        "detail",
        "full_address"
      ],
      "properties": {
        "province": {
          "type": "string",
          "description": "省份"
        },
        "city": {
          "type": "string",
          "description": "城市"
        },
        "district": {
          "type": "string",
          "description": "区/县"
        },
        "street": {
          "type": "string",
          "description": "街道/乡镇"
        },
        "detail": {
          "type": "string",
          "description": "详细地址"
        },
        "full_address": {
          "type": "string",
          "description": "完整地址拼接"
        }
      },
      "additionalProperties": false
    },
    "FieldValueChainedSelects": {
      "type": "object",
      "description": "级联选择字段值。适用 field_type: chained_selects",
      "required": [
        "values"
      ],
      "properties": {
        "values": {
          "type": "array",
          "description": "各级选择值（按 level 升序排列）",
          "items": {
            "type": "object",
            "required": [
              "option_id",
              "option_text",
              "level"
            ],
            "properties": {
              "option_id": {
                "type": "integer",
                "description": "选项ID"
              },
              "option_text": {
                "type": "string",
                "description": "选项文本"
              },
              "level": {
                "type": "integer",
                "description": "层级（从 1 开始）"
              }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    "FieldValueImageList": {
      "type": "array",
      "description": "图片/签名字段值。适用 field_type: image, signature",
      "items": {
        "$ref": "#/$defs/ImageItem"
      }
    },
    "FieldValueAudioList": {
      "type": "array",
      "description": "音频字段值。适用 field_type: audio",
      "items": {
        "type": "object",
        "required": [
          "url",
          "size",
          "duration"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "音频文件 URL"
          },
          "size": {
            "type": [
              "integer",
              "null"
            ],
            "description": "文件大小（字节），可能为 null"
          },
          "duration": {
            "type": "number",
            "description": "时长（秒）"
          },
          "translated_text": {
            "type": [
              "string",
              "null"
            ],
            "description": "语音转文字内容"
          },
          "abstract_text": {
            "type": [
              "string",
              "null"
            ],
            "description": "语音摘要文本"
          },
          "upload_time_iso": {
            "type": "string",
            "description": "上传时间（格式：Y-m-d H:i:s(UTC+08:00)）"
          }
        },
        "additionalProperties": false
      }
    },
    "FieldValueVideoList": {
      "type": "array",
      "description": "视频字段值。适用 field_type: video",
      "items": {
        "type": "object",
        "required": [
          "url",
          "size",
          "duration"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "视频文件 URL"
          },
          "size": {
            "type": [
              "integer",
              "null"
            ],
            "description": "文件大小（字节）"
          },
          "duration": {
            "type": "number",
            "description": "时长（秒）"
          },
          "upload_time_iso": {
            "type": "string",
            "description": "上传时间（格式：Y-m-d H:i:s(UTC+08:00)）"
          }
        },
        "additionalProperties": false
      }
    },
    "FieldValueFileList": {
      "type": "array",
      "description": "文件字段值。适用 field_type: file",
      "items": {
        "type": "object",
        "required": [
          "url",
          "size",
          "file_name"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "文件下载 URL"
          },
          "size": {
            "type": [
              "integer",
              "null"
            ],
            "description": "文件大小（字节）"
          },
          "file_name": {
            "type": "string",
            "description": "文件名（含扩展名）"
          },
          "upload_time_iso": {
            "type": "string",
            "description": "上传时间（格式：Y-m-d H:i:s(UTC+08:00)）"
          }
        },
        "additionalProperties": false
      }
    },
    "FieldValueDescription": {
      "type": "object",
      "description": "说明/描述字段值。适用 field_type: description",
      "required": [
        "description_html"
      ],
      "properties": {
        "description_html": {
          "type": "string",
          "description": "富文本 HTML 内容"
        }
      },
      "additionalProperties": false
    },
    "FieldValueOcr": {
      "type": "object",
      "description": "OCR 识别字段值。适用 field_type: ocr_id_card, ocr_bank_card, ocr_vehicle_license, ocr_driving_license, ocr_car_number, ocr_car_vin, ocr_business_license, ocr_way_bill, ocr_special_operate, ocr_general_cert, ocr_degree_cert, ocr_diploma_cert, ocr_dashboard_mile, ocr_electric_meter, ocr_water_meter, ocr_hygrother_mograp, ocr_gas_meter, ocr_pressure_meter, ocr_general_meter, ocr_digital_meter, ocr_roll_meter, ocr_pointer_meter, ocr_liquid_column_meter",
      "required": [
        "items",
        "image"
      ],
      "properties": {
        "items": {
          "type": "array",
          "description": "OCR 识别结果项列表",
          "items": {
            "type": "object",
            "required": [
              "item_id",
              "item_title",
              "value",
              "unit",
              "unit_enabled"
            ],
            "properties": {
              "item_id": {
                "type": "integer",
                "description": "识别项ID"
              },
              "item_title": {
                "type": "string",
                "description": "识别项标题"
              },
              "value": {
                "type": "string",
                "description": "识别结果值"
              },
              "unit": {
                "type": "string",
                "description": "单位（无单位时为空字符串）"
              },
              "unit_enabled": {
                "type": "boolean",
                "description": "是否启用单位"
              }
            },
            "additionalProperties": false
          }
        },
        "image": {
          "oneOf": [
            {
              "$ref": "#/$defs/ImageItem"
            },
            {
              "type": "null"
            }
          ],
          "description": "OCR 源图片（部分 OCR 类型无源图片时为 null）"
        }
      },
      "additionalProperties": false
    },
    "AiImageAuditResult": {
      "type": "object",
      "description": "AI 图片审核结果（仅当原始数据含审核信息时输出）",
      "required": [
        "audit_status",
        "audit_status_text",
        "reason"
      ],
      "properties": {
        "audit_status": {
          "type": "integer",
          "description": "0=默认，1=通过，2=不通过，3=失败，4=待审核"
        },
        "audit_status_text": {
          "type": "string",
          "description": "与 audit_status 对应的中文说明（默认、通过、不通过、失败、待审核）"
        },
        "reason": {
          "type": "string",
          "description": "AI 针对当前审核状态返回的原因说明"
        }
      },
      "additionalProperties": false
    },
    "ImageItem": {
      "type": "object",
      "description": "图片资源",
      "required": [
        "url",
        "size",
        "width",
        "height"
      ],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "图片 URL"
        },
        "size": {
          "type": [
            "integer",
            "null"
          ],
          "description": "文件大小（字节）"
        },
        "width": {
          "type": "integer",
          "description": "图片宽度（像素）"
        },
        "height": {
          "type": "integer",
          "description": "图片高度（像素）"
        },
        "upload_time_iso": {
          "type": "string",
          "description": "上传时间（格式：Y-m-d H:i:s(UTC+08:00)）"
        },
        "ai_audit_result": {
          "$ref": "#/$defs/AiImageAuditResult",
          "description": "可选；无 AI 审核数据时不返回"
        }
      },
      "additionalProperties": false
    },
    "FieldValueSubQrcodeEditChangeList": {
      "type": "array",
      "description": "子码编辑变更记录列表。适用 field_type: sub_qrcode_edit_diff。每个元素代表一个被修改的字段及其修改前后的值。",
      "items": {
        "$ref": "#/$defs/SubQrcodeEditChangeItem"
      }
    },
    "SubQrcodeEditChangeItem": {
      "type": "object",
      "description": "子码编辑的单个字段变更记录",
      "required": [
        "field_id",
        "field_title",
        "field_type",
        "before_value",
        "after_value"
      ],
      "properties": {
        "field_id": {
          "type": "integer",
          "description": "被修改的原始字段ID"
        },
        "field_title": {
          "type": "string",
          "description": "被修改的原始字段标题"
        },
        "field_type": {
          "type": "string",
          "description": "被修改的原始字段类型",
          "enum": [
            "text",
            "textarea",
            "number",
            "date",
            "time",
            "radio",
            "checkbox",
            "address",
            "image",
            "signature",
            "audio",
            "video",
            "file"
          ]
        },
        "before_value": {
          "$ref": "#/$defs/SubQrcodeEditChangeContent"
        },
        "after_value": {
          "$ref": "#/$defs/SubQrcodeEditChangeContent"
        }
      },
      "additionalProperties": false
    },
    "SubQrcodeEditChangeContent": {
      "type": "object",
      "description": "变更前/后的内容。非媒体字段使用 text_content；媒体字段使用 media_items。",
      "required": [
        "text_content",
        "media_items"
      ],
      "properties": {
        "text_content": {
          "type": "string",
          "description": "文本内容（非媒体字段的值，媒体字段时为空字符串）"
        },
        "media_items": {
          "type": "array",
          "description": "媒体项列表（媒体字段的值，非媒体字段时为空数组）。元素结构随所属变更项的 field_type 不同而变化。",
          "items": {
            "$ref": "#/$defs/SubQrcodeEditChangeMediaItem"
          }
        }
      },
      "additionalProperties": false
    },
    "SubQrcodeEditChangeMediaItem": {
      "type": "object",
      "description": "变更内容中的媒体资源项。根据所属变更项的 field_type 不同，包含不同属性：image/signature 有 width/height；audio 有 duration/translated_text/abstract_text；video 有 duration；file 有 file_name。",
      "required": [
        "url"
      ],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "资源 URL"
        },
        "size": {
          "type": [
            "integer",
            "null"
          ],
          "description": "文件大小（字节）"
        },
        "width": {
          "type": "integer",
          "description": "图片宽度（px）—— 仅 image/signature"
        },
        "height": {
          "type": "integer",
          "description": "图片高度（px）—— 仅 image/signature"
        },
        "duration": {
          "type": "number",
          "description": "时长（秒）—— 仅 audio/video"
        },
        "file_name": {
          "type": "string",
          "description": "文件名（含扩展名）—— 仅 file"
        },
        "translated_text": {
          "type": [
            "string",
            "null"
          ],
          "description": "语音转文字 —— 仅 audio"
        },
        "abstract_text": {
          "type": [
            "string",
            "null"
          ],
          "description": "语音摘要 —— 仅 audio"
        },
        "ai_audit_result": {
          "$ref": "#/$defs/AiImageAuditResult",
          "description": "可选；image/signature 变更项在含审核数据时返回"
        }
      },
      "additionalProperties": false
    }
  }
}

content-jsonld.schema.json (json-ld payload schema)

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "content-jsonld.schema.json",
  "title": "record/getRecord content schema (format=json-ld)",
  "description": "`record/getRecord` 在 `format=json-ld` 时 `data.data` 的结构定义。该结构基于 Schema.org 风格输出，保留主字段约束并允许扩展属性。",
  "type": "object",
  "required": [
    "@context",
    "@type",
    "identifier",
    "name",
    "url",
    "mainEntity"
  ],
  "properties": {
    "@context": {
      "type": "string"
    },
    "@type": {
      "type": "string"
    },
    "identifier": {
      "type": "string"
    },
    "alternateName": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "url": {
      "type": "string",
      "format": "uri"
    },
    "dateCreated": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "author": {
      "type": "object"
    },
    "sourceOrganization": {
      "type": "object"
    },
    "isBasedOn": {
      "type": "object"
    },
    "isPartOf": {
      "type": "object"
    },
    "additionalProperty": {
      "type": "array"
    },
    "review": {
      "type": "object"
    },
    "potentialAction": {
      "type": "array"
    },
    "mainEntity": {
      "type": "object"
    }
  },
  "additionalProperties": true
}

content-markdown.schema.json (markdown payload schema)

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "content-markdown.schema.json",
  "title": "record/getRecord content schema (format=markdown)",
  "description": "`record/getRecord` 在 `format=markdown` 时 `data.data` 的结构定义。返回值为完整 Markdown 文本。",
  "type": "string"
}

For format=json, each list item is already a full record object—batch reads usually do not need per-row getRecord calls. getRecord is better suited when you already have a single record_id / record_url.

Suggested filters

Goal	Suggested parameters
All records under one QR code	`filters.qrcode.id`
Records for one QR + one form	`filters.qrcode.id` + `filters.record_template.id`
All records for a form in visible scope	`filters.record_template.id`
Global search in visible scope	Omit both QR and form filters; add `search_key`, time, etc. as needed

Empty list example

json

{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [],
    "next_page_token": "",
    "total": 0
  }
}

Other conventions

Pagination

Case	Description
First request	`page_token` may be omitted
Next page	Pass prior `data.next_page_token` as `page_token`
No next page	`next_page_token` is usually `""`
Stop condition	Prefer checking whether `next_page_token` is empty
`get_total_count=0`	Server may skip total; do not rely on `total` to stop paging

Nulls and masking

Same rules as Get a single record. Linked example files are sanitized.

Error response

json

{
  "code": 400,
  "error_code": 100300,
  "message": "System error",
  "message_detail": ""
}

Field	Type	Description
`code`	integer	HTTP or platform status
`error_code`	integer	Business error code
`message`	string	Summary
`message_detail`	string	Detail; may be empty

Full error codes: Error codes.

QR Code

Dynamic QR Code

Forms

QR codes

Forms & records

Installation Guide

WeCom Version Purchase

FAQ

Get records

Request example

Request parameters

`filters` fields

`filters.record_template`

`filters.qrcode`

`filters.project`

`filters.audit`

`filters.process_status`

`filters.state_changes`

`filters.recorder`

Output format overview

Full response skeleton

Response overview

List items and `getRecord`

Suggested filters

Empty list example

Other conventions

Nulls and masking

Error response

Get records ​

Request example ​

Request parameters ​

filters fields ​

filters.record_template ​

filters.qrcode ​

filters.project ​

filters.audit ​

filters.process_status ​

filters.state_changes ​

filters.recorder ​

Output format overview ​

Full response skeleton ​

Response overview ​

List items and getRecord ​

Suggested filters ​

Empty list example ​

Other conventions ​

Pagination ​

Nulls and masking ​

Error response ​

Get records

Request example

Request parameters

`filters` fields

`filters.record_template`

`filters.qrcode`

`filters.project`

`filters.audit`

`filters.process_status`

`filters.state_changes`

`filters.recorder`

Output format overview

Full response skeleton

Response overview

List items and `getRecord`

Suggested filters

Empty list example

Other conventions

Pagination

Nulls and masking

Error response