# Add record

Submits one filled record under `code_id` + `tpl_id`.

This page focuses on the request body. To discover fields, `field_id` / `option_id` / column / checklist IDs, call [Get form template](https://cli.im/open-api/en/openapi/v2/api/record/forms-get-template.md) first.

## Request example



```python [Python + requests]
import requests

url = 'https://open.cli.im/api/v2/rpc/record/addRecord'
data = {
    'code_id': 6762875,
    'tpl_id': 122507,
    'fields': [
        { 'field_id': 71399639089153, 'field_type': 'name', 'field_value': '张三' },
        { 'field_id': 71399639089154, 'field_type': 'tel', 'field_value': '13800138000' },
        { 'field_id': 71399639089158, 'field_type': 'sex', 'field_value': { 'option_id': 71399639089192 } },
        { 'field_id': 71399639089161, 'field_type': 'number', 'field_value': { 'value': 30.6 } },
        { 'field_id': 71399639089170, 'field_type': 'checkbox', 'field_value': {
            'values': [
                { 'option_id': 71399639089361 },
                { 'option_id': 71399639089369, 'custom_text': '电线杆子' }
            ]
        } }
    ]
}
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/record/addRecord' \
  -H 'Authorization: Bearer <your API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"code_id":6762875,"tpl_id":122507,"fields":[{"field_id":71399639089153,"field_type":"name","field_value":"张三"},{"field_id":71399639089158,"field_type":"sex","field_value":{"option_id":71399639089192}}]}'
```



## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `code_id` | integer | Yes | QR code ID |
| `tpl_id` | integer | Yes | Form template ID |
| `fields` | array | Yes | Field values; one entry per component—see `fields[]` below |

### `fields[]` item

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `field_id` | integer | Yes | Component ID from the form template |
| `field_type` | string | Yes | Component type, e.g. `name`, `radio`, `checkbox`, `matrix` |
| `field_value` | string \| object \| array | Yes | Value; shape depends on `field_type` |

Notes:

- Structured IDs (`field_id`, `option_id`, `item_id`, `column_id`, …) must come from [Get form template](https://cli.im/open-api/en/openapi/v2/api/record/forms-get-template.md).
- The public API only needs `code_id`, `tpl_id`, and `fields`.

## `field_value` input shapes

### Quick reference

| Family | `field_type` | `field_value` shape |
| --- | --- | --- |
| Text / time | `name`, `tel`, `recorder`, `identity`, `job_number`, `text`, `textarea`, `date`, `time`, `customer_name`, `customer_mobile`, `customer_number`, `carnumber` | `string` |
| Single choice | `sex`, `radio` | `object` |
| Number | `number` | `object` |
| Multi choice | `checkbox` | `object` |
| Composite | `checklist` | `array` |
| Composite | `matrix`, `dynamic_matrix`, `chained_selects` | `object` |
| Address | `address`, `owner_address` | `object` |
| OCR | `ocr_*` | `object` |

### Text / time

`field_type`:

- `name`, `tel`, `recorder`, `identity`, `job_number`, `text`, `textarea`, `date`, `time`, `customer_name`, `customer_mobile`, `customer_number`, `carnumber`

`field_value` is a plain string:

```json
{
  "field_id": 71399639089153,
  "field_type": "name",
  "field_value": "张三"
}
```

Suggested formats:

- `date`: `2026-03-09` or `2026-03-09 17:24`
- `time`: `2026-03-09 17:24`

### Single choice

`field_type`: `sex`, `radio`

Normal option:

```json
{
  "field_id": 71399639089158,
  "field_type": "sex",
  "field_value": {
    "option_id": 71399639089192
  }
}
```

“Other” option may include `custom_text`:

```json
{
  "field_id": 71399639089168,
  "field_type": "radio",
  "field_value": {
    "option_id": 71399639089337,
    "custom_text": "一点小问题"
  }
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `option_id` | integer | Yes | Option ID |
| `custom_text` | string | No | Extra text for “other” |

### Number

`field_type`: `number`

```json
{
  "field_id": 71399639089161,
  "field_type": "number",
  "field_value": {
    "value": 30.6
  }
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | number | Yes | Numeric value |

### Multi choice

`field_type`: `checkbox`

```json
{
  "field_id": 71399639089170,
  "field_type": "checkbox",
  "field_value": {
    "values": [
      { "option_id": 71399639089361 },
      { "option_id": 71399639089369, "custom_text": "电线杆子" }
    ]
  }
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `values` | array | Yes | Selected options |
| `values[].option_id` | integer | Yes | Option ID |
| `values[].custom_text` | string | No | “Other” text |

### Checklist

`field_type`: `checklist`

```json
{
  "field_id": 71399639089163,
  "field_type": "checklist",
  "field_value": [
    {
      "item_id": 71399639089266,
      "value": { "option_value": "1" }
    },
    {
      "item_id": 71399639089267,
      "value": {
        "option_value": "2",
        "description": "生锈了，需要注意"
      }
    }
  ]
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `item_id` | integer | Yes | Checklist item ID |
| `value.option_value` | string | Yes | Result value |
| `value.description` | string | No | Note |

Meaning of `option_value` comes from form config. V2 does not support submitting images or other static assets inside `checklist`.

### Matrix (fixed rows)

`field_type`: `matrix`

```json
{
  "field_id": 71399639089164,
  "field_type": "matrix",
  "field_value": {
    "columns": [
      {
        "column_id": 71399639089283,
        "column_type": "text",
        "value": { "text": "黄金龙" }
      },
      {
        "column_id": 71399639089285,
        "column_type": "sex",
        "value": {
          "text": "男",
          "option_uuid": "25587b8b-485d-4038-a5ab-9bcd7c4af880"
        }
      }
    ]
  }
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `columns` | array | Yes | Column values |
| `columns[].column_id` | integer | Yes | Column ID |
| `columns[].column_type` | string | Yes | Column type |
| `columns[].value` | object | Yes | Value object; shape depends on column type |

Address columns may include `address_detail`, etc.; definitions come from [Get form template](https://cli.im/open-api/en/openapi/v2/api/record/forms-get-template.md).

### Dynamic matrix

`field_type`: `dynamic_matrix`

```json
{
  "field_id": 71399639089165,
  "field_type": "dynamic_matrix",
  "field_value": {
    "rows": [
      {
        "columns": [
          {
            "column_id": 71399639089294,
            "column_type": "text",
            "value": { "text": "螺丝" }
          }
        ]
      }
    ]
  }
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rows` | array | Yes | Rows |
| `rows[].columns` | array | Yes | Same shape as `matrix.columns[]` |

### Address

`field_type`: `address`, `owner_address`

Located:

```json
{
  "field_id": 71399639089173,
  "field_type": "address",
  "field_value": {
    "address": "浙江省宁波市海曙区启文路157弄",
    "lat": 29.856985405815973,
    "lng": 121.53253689236111
  }
}
```

Manual:

```json
{
  "field_id": 71399639089174,
  "field_type": "owner_address",
  "field_value": {
    "province": "浙江省",
    "city": "宁波市",
    "district": "海曙区",
    "street": "南门街道",
    "detail": "海曙区甬水桥科创中心(启文路157弄北150米)"
  }
}
```

`address`:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | string | Yes | Address text |
| `lat` | number | Yes | Latitude |
| `lng` | number | Yes | Longitude |

`owner_address`:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `province` | string | Yes | Province |
| `city` | string | Yes | City |
| `district` | string | Yes | District / county |
| `street` | string | No | Street / township |
| `detail` | string | No | Detail |

### Cascaded selects

`field_type`: `chained_selects`

```json
{
  "field_id": 71399639089177,
  "field_type": "chained_selects",
  "field_value": {
    "values": [
      { "option_id": 71399639089433 },
      { "option_id": 71399639089443 },
      { "option_id": 71399639089447 }
    ]
  }
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `values` | array | Yes | Options per level in order |
| `values[].option_id` | integer | Yes | Option ID |

### OCR

`field_type`: `ocr_id_card`, `ocr_business_license`, `ocr_electric_meter`, other `ocr_*`

```json
{
  "field_id": 71399639089185,
  "field_type": "ocr_electric_meter",
  "field_value": {
    "items": [
      {
        "item_id": 71399639089571,
        "key": "度数",
        "value": "10890.1"
      }
    ]
  }
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array | Yes | Recognized items |
| `items[].item_id` | integer | Yes | Item ID |
| `items[].key` | string | No | Key label |
| `items[].value` | string | Yes | Recognized text |

OCR should carry recognized text only; V2 does not accept source images or other static uploads with the request.

## Not supported in submissions

### Static media components

V2 cannot submit content for:

- `image`
- `signature`
- `audio`
- `video`
- `file`

Even if the form marks these required, **API-sourced** submissions are **not** blocked by those required rules; whether empty values are acceptable is a business decision on your side.

### Non-value components

Not used for business values:

- `description`

## Relationship to form “required” settings

OpenAPI `addRecord` writes are **API-sourced**; they **do not** enforce per-component “required” from the form designer.

Notes:

- `is_required` from [Get form template](https://cli.im/open-api/en/openapi/v2/api/record/forms-get-template.md) mainly applies to browser/mobile form UX.
- You may use `is_required` locally, but do **not** assume the API rejects missing fields the way the form UI would.

## Visibility rules

Show/hide rules from the form config **do not apply** to API submissions.

Notes:

- Visibility is for front-end display only, not server-side field pruning for OpenAPI writes.
- Whether to send a field is entirely up to the caller.
- Product help (Chinese): [visibility rules](https://cli.im/help/94923).

## Excel bulk import

The API does not provide an official Excel upload or batch-import endpoint.

Suggested flow:

1. Call [Get form template](https://cli.im/open-api/en/openapi/v2/api/record/forms-get-template.md) for IDs.
2. Parse Excel; map each row to `fields[]`.
3. Call this API once per row.
4. Aggregate success/failure and retry recoverable errors.

Notes:

- Multiple single writes are not atomic; partial success is normal.
- Check for unsupported media fields before bulk import.
- Handle `error_code` per row—do not blindly retry parameter or validation errors.

## Success response example

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "version": "v1",
    "record_id": 2644408,
    "record_number": "L136",
    "record_code": "r06mEwjF7vqSvXpfTbrF781",
    "record_url": "https://qr46.cn/oEuE2E/r06mEwjF7vqSvXpfTbrF781",
    "submit_at": 1773056540,
    "submit_at_iso": "2026-03-09 19:42:20(UTC+08:00)"
  }
}
```

## Response overview

| Path | Type | Description |
| --- | --- | --- |
| `code` | integer | `0` success |
| `message` | string | Message |
| `data` | object | Result |
| `data.version` | string | `v1` |
| `data.record_id` | integer | Record ID |
| `data.record_number` | string | Record number |
| `data.record_code` | string | Record code |
| `data.record_url` | string | Record URL |
| `data.submit_at` | integer | Submitted at (Unix seconds) |
| `data.submit_at_iso` | string | Formatted time with timezone |

## Error response

Failures often look like:

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

API `addRecord` does not enforce form `is_required`; interpret errors from parameters, value shape, and business state.

Full error codes: [Error codes and rate limits](https://cli.im/open-api/en/openapi/v2/error-codes.md).

## Integration checklist

1. Call [Get form template](https://cli.im/open-api/en/openapi/v2/api/record/forms-get-template.md) for IDs and types.
2. Build `fields[]` using the `field_type` → `field_value` rules on this page.
3. Skip unsupported static media; confirm your process allows them empty if the form needs them.
4. For bulk import, parse locally and call row-by-row—there is no official batch API.
5. After success, read content via [Get a single record](https://cli.im/open-api/en/openapi/v2/api/record/record-get-record.md) or [Get records](https://cli.im/open-api/en/openapi/v2/api/record/record-get-records.md).

## Related pages

- [Get form template](https://cli.im/open-api/en/openapi/v2/api/record/forms-get-template.md): field defs, option IDs, checklist/matrix IDs
- [Form component types overview](https://cli.im/open-api/en/openapi/v2/api/record/components-field-types.md): `field_type` names and families
- [Get a single record](https://cli.im/open-api/en/openapi/v2/api/record/record-get-record.md): response value shapes after write
- [Get records](https://cli.im/open-api/en/openapi/v2/api/record/record-get-records.md): list query
