# Query forms and records linked to a QR code

Use this flow when you only have QR `coding` or a QR URL and want to find:

- which forms are linked to this QR code
- the field structure of a target form
- records already submitted under this QR code

## Preconditions

- Completed [Authentication](https://cli.im/open-api/en/openapi/v2/auth.md)
- Have QR `coding` or QR URL

## 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). Read `data.meta.id` as `code_id` for subsequent calls.

### Step 2: Get linked `tpl_id`

Call [QR code operation elements](https://cli.im/open-api/en/openapi/v2/api/qrcodes-get-operation.md), filter elements with `element_type=2`, and get one or more `tpl_id` values.

### Step 3: Read form structure as needed

If you need form title, fields, options, or component types, call [Get form template](https://cli.im/open-api/en/openapi/v2/api/record/forms-get-template.md).

Typical purposes:

- dynamic form rendering
- backend field mapping validation
- preparing structured IDs (`field_id`, `option_id`, ...)

### Step 4: Query record list

Call [Get records](https://cli.im/open-api/en/openapi/v2/api/record/record-get-records.md). Recommended filters:

| Goal | Suggested parameters |
| --- | --- |
| All records under this QR code | `filters.qrcode.id=code_id` |
| Records for one form under this QR code | `filters.qrcode.id=code_id` + `filters.record_template.id=tpl_id` |
| Records for one form in current API-key scope | `filters.record_template.id=tpl_id` |
| Global search in current API-key scope | Omit both filters; add keyword/time filters as needed |

### Step 5: Whether to call single-record API

When `format=json`, each item in `getRecords.data.list[]` is already a full record object.

Call [Get a single record](https://cli.im/open-api/en/openapi/v2/api/record/record-get-record.md) only when you need precise retrieval by one `record_id` / `record_url`.

## Key ID mapping

| Name | Source | Usage |
| --- | --- | --- |
| `code_id` | `qrcodes/getContent -> data.meta.id` | Target QR code |
| `tpl_id` | `qrcodes/getOperation` where `element_type=2` | Target form template |
| `record_id` | `getRecords.data.list[]` or business context | Retrieve one exact record |

## Common notes

- One QR code can link to multiple forms; do not assume a single `tpl_id`.
- `getRecords` already returns full detail in `json` mode; avoid per-item `getRecord` calls for batch reads.
- If `filters.qrcode.id` is omitted, results usually expand to the API-key visible scope.

## 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)
- [Get records](https://cli.im/open-api/en/openapi/v2/api/record/record-get-records.md)
- [Get a single record](https://cli.im/open-api/en/openapi/v2/api/record/record-get-record.md)
