Get form template

Returns the full form definition for a template ID (tpl_id): render forms, validate input, build submission flows, or sync structure on your side.

This page focuses on response structure and integration notes; full schemas and demos are in the companion folder. Examples are sanitized or synthetic.

Request example

Python + requests

import requests

url = 'https://open.cli.im/api/v2/rpc/forms/getTemplate'
data = {
    'tpl_id': 122507
}
headers = {
    'Authorization': 'Bearer <your API Key>',
    'Content-Type': 'application/json'
}
response = requests.post(url, json=data, headers=headers)
print(response.text)

curl

curl -X POST 'https://open.cli.im/api/v2/rpc/forms/getTemplate' \
  -H 'Authorization: Bearer <your API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"tpl_id": 122507}'

Request parameters

Parameter	Type	Required	Description
tpl_id	integer	Yes	Form template ID

Full response skeleton

The block below is a success skeleton only; full payload and response files are linked under “Schema and examples.”

{
  "code": 0,
  "message": "ok",
  "data": {
    "version": "v1",
    "data": {
      "form": {
        "id": 122507,
        "name": "设备巡检",
        "type": 0,
        "type_text": "普通表单",
        "number": "D32",
        "description": "请仔细填写表单中的内容",
        "submit_button_title": "提交",
        "created_at_iso": "2026-02-27 10:26:42(UTC+08:00)",
        "updated_at_iso": "2026-03-09 17:13:04(UTC+08:00)"
      },
      "org": { "id": 94910252 },
      "project": { "id": 1104 },
      "groups": [
        {
          "group_id": 71399639089153,
          "group_title": "",
          "show_group_title": false,
          "is_page_break_group": false,
          "fields": [
            {
              "field_id": 71399639089153,
              "field_title": "巡检人姓名",
              "field_desc": "",
              "field_type": "name",
              "field_short_name": "",
              "group_id": 71399639089153,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": true,
                "is_unique": false,
                "is_highlight": false
              }
            }
          ]
        }
      ],
      "audit_config": {
        "enabled": true,
        "stages": [
          { "id": 20241, "title": "组长审批", "level": 1 },
          { "id": 20242, "title": "厂长审批", "level": 2 }
        ]
      },
      "process_status_config": {
        "enabled": true,
        "options": [
          { "text": "待处理", "color": "#E64340" },
          { "text": "处理中", "color": "#155EB7" },
          { "text": "已完成", "color": "#06AE56" }
        ]
      },
      "rules": {
        "time_limit_record": [
          {
            "start_time": 1773030000,
            "end_time": 1773036000,
            "time_limit_type": 0
          }
        ],
        "tpl_limit_record": null,
        "owner_tpl_limit_record": null
      }
    }
  }
}

Full examples:

• json full response
• json payload

Response overview

Path	Type	Description
code	integer	Platform code; 0 success
message	string	Message
data	object	Wrapper
data.version	string	Version, fixed v1
data.data	object	Form structure body

Wrapper example:

{
  "version": "v1",
  "data": { "...": "..." }
}

data.data structure

data.data is the form object. Schema: content-json-v1.schema.json; sample: payload-normal.json.

Top-level fields

Field	Type	Description
form	object	Basic form info
org	object	Owning org
project	object	Owning project (partition)
groups	array	Groups and field definitions
audit_config	object	Approval configuration
process_status_config	object	Process status configuration
rules	object	Submission rules

form object

Field	Type	Description
id	integer	Form ID
name	string	Form name
type	integer	Form type code
type_text	string	Form type label
number	string	Form number
description	string	Description
submit_button_title	string	Submit button label
created_at_iso	string	Created at with timezone
updated_at_iso	string	Updated at with timezone

form.type values

Value	Meaning
0	Normal form
1	Normal form
2	Normal form
3	Confidential commitment system form
7	Manual QR state change system form
12	Identity group join application form
13	Subcode edit system form
21	QR message system form
22	QR collaboration system form

org / project

Object	Field	Type	Description
org	id	integer	Org ID
project	id	integer	Project ID

groups[]

Each item is a field group. Supports page-break groups: a break group carries no fields and only separates pages.

Group fields

Field	Type	Description
group_id	integer	Group ID
group_title	string	Title; may be ""
show_group_title	boolean	Show title or not
is_page_break_group	boolean	Page break; fields usually []
fields	array	Fields in the group

Pagination notes:

• is_page_break_group=true marks a page boundary.
• The following normal group usually holds fields for that page.
• Do not assume titled groups always contain fields—check is_page_break_group.

groups[].fields[]

Field	Type	Description
field_id	integer	Field ID
field_title	string	Title
field_desc	string	Hint text
field_type	string	Type
field_short_name	string	Short name / alias
group_id	integer	Group ID
settings	object	Generic and type-specific settings

Filtering:

• Sub-fields are not returned.
• Disabled fields are omitted.
• ocr_* describes OCR main fields without internal implementation detail.

Common settings booleans

All field types include:

Field	Type	Description
is_required	boolean	Required
is_hidden	boolean	Hidden
is_result	boolean	Result field
is_masked	boolean	Privacy masking enabled
is_unique	boolean	Uniqueness check
is_highlight	boolean	Highlight

Extended settings by type

Types not listed only have the six booleans above.

Date/time: date / time

Field	Type	Description
format	string	Date/time format
default_to_current	boolean	Default to now

Number: number

Field	Type	Description
unit	string	Unit label; "" if none
unit_enabled	boolean	Show unit
range	object	Numeric range
range.minimum	number | null	Min
range.maximum	number | null	Max
allow_negative	boolean	Allow negatives

Options: sex / radio / checkbox

Field	Type	Description
options	array	Options
options[].option_id	integer	Option ID
options[].option_text	string	Label
options[].is_custom	boolean	Allow custom text

Checklist: checklist

Field	Type	Description
is_allow_entry_desc	boolean	Allow note text
checklist_items	array	Items
checklist_items[].item_id	integer	Item ID
checklist_items[].item_title	string	Item title
checklist_result_options	array	Result options
checklist_result_options[].option_id	integer	Option ID
checklist_result_options[].option_value	string	Value
checklist_result_options[].option_text	string	Label

Table: matrix / dynamic_matrix

Field	Type	Description
columns	array	Column defs
columns[].column_id	integer	Column ID
columns[].column_title	string	Title
columns[].column_type	string	Column type
columns[].format	string	Date/time format for some types
columns[].options	array	For sex / radio etc.
columns[].options[].option_uuid	string	Option UUID
columns[].options[].option_text	string	Label
columns[].options[].is_custom	boolean	Custom input allowed

Cascaded: chained_selects

Field	Type	Description
chained_options	array	Tree
chained_options[].option_id	integer	Option ID
chained_options[].option_text	string	Label
chained_options[].level	integer	Depth from 1
chained_options[].children	array	Children; [] at leaves

OCR: ocr_*

Field	Type	Description
ocr_items	array	Recognition items
ocr_items[].item_id	integer	Item ID
ocr_items[].item_title	string	Title
ocr_items[].unit	string	Unit
ocr_items[].unit_enabled	boolean	Show unit

Description: description

Field	Type	Description
description_html	string	Rich HTML

audit_config

Field	Type	Description
enabled	boolean	Approval enabled
stages	array	Stages; empty when disabled
stages[].id	integer	Stage ID
stages[].title	string	Stage title
stages[].level	integer	Level from 1

process_status_config

Field	Type	Description
enabled	boolean	Processing status enabled
options	array	Status options
options[].text	string	Label
options[].color	string	Hex color

rules

Time limits, per-user submission limits, and total submission limits.

Field	Type	Description
time_limit_record	array	Time windows
tpl_limit_record	object | null	Per-user limit
owner_tpl_limit_record	object | null	Total form limit

time_limit_record[]

Field	Type	Description
start_time	integer | string	Start; may be Unix timestamp—do not rely on a single format
end_time	integer | string	End
time_limit_type	integer	0 none, 1 datetime range, 2 daily window

tpl_limit_record / owner_tpl_limit_record

Field	Type	Description
limit_type	integer	0 none, 1 once, 2 custom period
custom_type	integer	Period: 0 day, 1 week, 2 month, 3 year
custom_limit	integer	Allowed submissions per period
custom_type_limit	integer	Period span value

field_type reference

Overview: Form component types overview.

In forms/getTemplate, field_type mainly determines which settings keys appear:

Category	Common field_type	Config focus
Text / identity	name, tel, recorder, identity, job_number, text, textarea, customer_name, customer_mobile, customer_number, carnumber	Usually only the six booleans
Choice	sex, radio, checkbox	options[]
Number / time	number, date, time	unit, range, format, default_to_current
Composite	checklist, matrix, dynamic_matrix, chained_selects	Nested: checklist_items, columns, chained_options
Media / display / OCR	image, audio, video, file, signature, description, ocr_*	Media flags, description_html, ocr_items

For record values, see Get a single record (field_type → field_value).

Schema and examples

Schema

• response.schema.json: full response
• content-json-v1.schema.json: data.data payload

Full examples

• JSON: normal response, normal payload

Other conventions

Empty values

Case	Rule
Optional rule not set	tpl_limit_record, owner_tpl_limit_record may be null
Empty string	Often ""
Empty array	Often []
Open range	range.minimum / maximum may be null

Masking

Case	Description
Live API	Masking depends on org permission and field config
Examples	Sanitized or synthetic
settings.is_masked	Masking enabled; does not imply the sample matches live data

Error response

{
  "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.