# Submit a record to a form under a QR code

Use this flow when you know the target QR code and need to submit one new record to one linked form.

## Preconditions

- Completed [Authentication](https://cli.im/open-api/en/openapi/v2/auth.md)
- Have QR `coding` or URL
- Confirm current API key has visibility and write permission for target QR code and form

## Recommended call order

### Step 1: Get `code_id`

Call [QR code content](https://cli.im/open-api/en/openapi/v2/api/qrcodes-get-content.md), then read `data.meta.id` as `code_id`.

### Step 2: Get target `tpl_id`

Call [QR code operation elements](https://cli.im/open-api/en/openapi/v2/api/qrcodes-get-operation.md), locate target form, and get `tpl_id`.

If one QR code links multiple forms, choose the correct form first (by name/business context) before proceeding.

### Step 3: Read form structure

Call [Get form template](https://cli.im/open-api/en/openapi/v2/api/record/forms-get-template.md) and extract structured IDs needed for submission:

- `field_id`
- `option_id`
- `item_id`
- `column_id`

This step ensures `fields[]` uses structured identifiers instead of UI display names.

### Step 4: Submit record

Call [Add record](https://cli.im/open-api/en/openapi/v2/api/record/record-add-record.md) and submit with `code_id + tpl_id + fields[]`.

## Key ID mapping

| Name | Source | Usage |
| --- | --- | --- |
| `code_id` | `qrcodes/getContent -> data.meta.id` | Target QR code |
| `tpl_id` | form element from `qrcodes/getOperation` | Target form template |
| `field_id` / `option_id` / `item_id` / `column_id` | `forms/getTemplate` | Build `fields[]` |

## Common notes

- Do not hardcode mapping by field display text; always use structured IDs from `forms/getTemplate`.
- One QR code may have multiple forms; confirm target `tpl_id` before submit.
- `is_required` in `forms/getTemplate` is mainly for frontend interactions; API `addRecord` does not enforce component required flags the same way.
- Handle field-validation and business-state errors case by case; avoid unconditional retries.

## Related APIs

- [QR code content](https://cli.im/open-api/en/openapi/v2/api/qrcodes-get-content.md)
- [QR code operation elements](https://cli.im/open-api/en/openapi/v2/api/qrcodes-get-operation.md)
- [Get form template](https://cli.im/open-api/en/openapi/v2/api/record/forms-get-template.md)
- [Add record](https://cli.im/open-api/en/openapi/v2/api/record/record-add-record.md)
