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 first.

Request example

Python + requestscurl

python

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

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

Excel bulk import

OpenAPI V2 does not provide an official Excel upload or batch-import endpoint.

Suggested flow:

Call Get form template for IDs.
Parse Excel; map each row to fields[].
Call this API once per row.
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.

Integration checklist

Call Get form template for IDs and types.
Build fields[] using the field_type → field_value rules on this page.
Skip unsupported static media; confirm your process allows them empty if the form needs them.
For bulk import, parse locally and call row-by-row—there is no official batch API.
After success, read content via Get a single record or Get records.

Get form template: field defs, option IDs, checklist/matrix IDs
Form component types overview: field_type names and families
Get a single record: response value shapes after write
Get records: list query

QR Code

Dynamic QR Code

Forms

QR codes

Forms & records

Installation Guide

WeCom Version Purchase

FAQ

Add record

Request example

Request parameters

`fields[]` item

`field_value` input shapes

Quick reference

Text / time

Single choice

Number

Multi choice

Checklist

Matrix (fixed rows)

Dynamic matrix

Address

Cascaded selects

OCR

Not supported in submissions

Static media components

Non-value components

Relationship to form “required” settings

Visibility rules

Excel bulk import

Success response example

Response overview

Error response

Integration checklist

Add record ​

Request example ​

Request parameters ​

fields[] item ​

field_value input shapes ​

Quick reference ​

Text / time ​

Single choice ​

Number ​

Multi choice ​

Checklist ​

Matrix (fixed rows) ​

Dynamic matrix ​

Address ​

Cascaded selects ​

OCR ​

Not supported in submissions ​

Static media components ​

Non-value components ​

Relationship to form “required” settings ​

Visibility rules ​

Excel bulk import ​

Success response example ​

Response overview ​

Error response ​

Integration checklist ​

Related pages ​

Add record

Request example

Request parameters

`fields[]` item

`field_value` input shapes

Quick reference

Text / time

Single choice

Number

Multi choice

Checklist

Matrix (fixed rows)

Dynamic matrix

Address

Cascaded selects

OCR

Not supported in submissions

Static media components

Non-value components

Relationship to form “required” settings

Visibility rules

Excel bulk import

Success response example

Response overview

Error response

Integration checklist

Related pages