Create a form on a patient chart and submit field values

Creates a form instance from a pre-configured form definition (resolved by its label) on the patient's chart and writes all provided field values in a single atomic call — on any error, nothing is written. Use GET /forms/definitions to discover form, section, and field labels.

Every ingested form attaches to an existing encounter (visit) on the patient's chart: create the encounter first, then submit form data with its encounterId. The encounter must belong to the patient.

Values are keyed by field definition label and must match the field's type: strings for text and text_paragraph, YYYY-MM-DD or RFC 3339 strings for date, numbers for number_float, a configured choice string for single-choice fields (scale answers are string integers, e.g. "2"), and arrays of choice strings for multi-choice fields. Grid-matrix values are row-keyed objects whose per-row shape depends on the sub-type: grid_matrix_text and grid_matrix_number map each row index to a column-keyed object of cells ({"0": {"1": "cell"}}), grid_matrix_choice maps each row index to a single integer column index ({"0": 1}), and grid_matrix_multi_choice maps each row index to an array of integer column indices ({"0": [0, 1]}). A JSON null clears a field (including any default). Display-only, calculated, and chart-backed (roobi_custom_field) fields cannot be written. Omit values to create an empty form.

Submitted field labels must be unambiguous within the form definition: if a label matches more than one field on the created form, the request fails with a 400.

The created form behaves exactly like one created on the encounter in-app: it arrives unsigned with the definition's signature requirements and signature actions, signers are notified, due-forms scheduling applies, and the encounter's documentation status is recalculated. Requests are not idempotent: retrying a successful call creates a second form instance.