# 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 [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)
```

```bash [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 |

## Response overview

**response.schema.json (full API response schema)**
<<< ./forms-get-template/schema/response.schema.json


| Path | Type | Description |
| --- | --- | --- |
| `code` | integer | Platform code; `0` success |
| `message` | string | Message |
| `data` | object | Wrapper |
| `data.data` | object | Form structure body |

Wrapper example:

```json
{
  "data": { "...": "..." }
}
```

## `data.data` structure

`data.data` is the form object. Full payload schema and examples are in the collapsible sections below.

**content-json.schema.json (payload schema)**
<<< ./forms-get-template/schema/content-json.schema.json


**Full example**
<<< ./forms-get-template/examples/json/success-normal.response.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](https://cli.im/open-api/en/openapi/v2/api/record/components-field-types.md).

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](https://cli.im/open-api/en/openapi/v2/api/record/record-get-record.md) (`field_type` → `field_value`).

## 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

```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 and rate limits](https://cli.im/open-api/en/openapi/v2/error-codes.md).
