# Add Records from Excel (One API Call per Row)

Use this flow when you have Excel (or similar tabular data) and want to import records in batch into a form linked to a QR code.

## Conclusion

The API currently **does not provide an official Excel upload/import or atomic batch-add endpoint**.

Recommended approach: parse Excel locally, then call [Add record](https://cli.im/open-api/en/openapi/v2/api/record/record-add-record.md) row by row.

## Recommended implementation flow

### Step 1: Determine target QR code and form

Follow [Submit a record to a form under a QR code](https://cli.im/open-api/en/openapi/v2/scenarios/add-record-by-qrcode.md) first to get:

- `code_id`
- `tpl_id`
- structured IDs required by form fields

### Step 2: Parse Excel locally

Read Excel on the client side, map each row to an internal object, then map to API `fields[]` structure.

### Step 3: Call `addRecord` per row

Call [Add record](https://cli.im/open-api/en/openapi/v2/api/record/record-add-record.md) for each row.

This is fundamentally:

- multiple single submissions
- non-atomic batch processing
- per-row independent success/failure

## Capabilities you should implement on your side

Because platform-side transactional batch semantics are not provided, implement these client-side:

- row-level validation
- error aggregation
- idempotency control
- retry strategy
- import progress and result reporting

## Common notes

- Do not interpret this as “upload one Excel and let platform import all at once.”
- Failure of one row does not roll back previously successful rows.
- Before bulk import, call [Get form template](https://cli.im/open-api/en/openapi/v2/api/record/forms-get-template.md) to lock field mapping and avoid hardcoding by display text.

## Related APIs

- [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)
- [Submit a record to a form under a QR code](https://cli.im/open-api/en/openapi/v2/scenarios/add-record-by-qrcode.md)
