Patient Forms

Patient Forms lets you discover the forms configured for a location, read their full field definitions, and submit completed responses on behalf of a patient.

Typical Flow

GET /form_schemas — list all forms available at the location
GET /form_schemas/:id — fetch the full field definitions for a form; note newest_version_id
Build a patient_submitted_data object from the field definitions (see Submitting a Response)
POST /form_responses — submit the completed form on behalf of a patient

Form Schemas

Each schema represents a form template. The list endpoint returns id, title, and form_slug — a stable slug derived from the filename that stays consistent across versions.

The detail endpoint adds two fields:

formio_schema.components — the ordered array of field definitions. Each component has:

Field	Description
`key`	The field name used in `patient_submitted_data` when submitting
`type`	Controls what value shape is expected (see Field Types)
`label`	Human-readable question text
`values`	For `radio` and `selectboxes` — the list of valid options, each with a `label` and `value`
`validate.required`	Whether the field must be present in the submission
`conditional`	Show/hide rule — see Conditional Fields
`input`	`false` for display-only elements (`htmlelement`, `button`) — omit these from submissions

newest_version_id — the UUID of the most recently published version of this form. Always use this when submitting a response to ensure the patient is filling the latest revision. It may differ from the schema's own id if the form has been updated.

Submitting a Response

POST /form_responses takes a patient_submitted_data object keyed by component key. Only include components where input: true.

Field Types

`type`	Expected value
`radio`	String matching one of `values[].value` — e.g. `"yes"` or `"no"`
`checkbox`	Boolean
`selectboxes`	Object mapping every option's `value` to a boolean — e.g. `{"Aspirin": true, "Latex": false}`
`textfield` / `textarea`	String
`signature`	Data URI — `"data:image/png;base64,..."`

Conditional Fields

Some fields only apply when a previous answer has a specific value. These carry a conditional block:

{
  "key": "specify-73",
  "conditional": { "show": true, "when": "73", "eq": "yes" }
}

Only include the field in your submission when the trigger field (when) equals the required value (eq). Submitting a conditional field whose condition is not met may cause the submission to be rejected.

Example Schema and Response

The following shows a subset of formio_schema.components alongside the corresponding patient_submitted_data.

Schema (formio_schema.components)

[
  {
    "key": "72",
    "type": "textfield",
    "input": true,
    "label": "Are you under a physician's care now?"
  },
  {
    "key": "73",
    "type": "radio",
    "input": true,
    "label": "Have you ever been hospitalized or had a major operation?",
    "values": [
      { "label": "Yes", "value": "yes" },
      { "label": "No", "value": "no" }
    ],
    "validate": { "required": true }
  },
  {
    "key": "specify-73",
    "type": "textfield",
    "input": true,
    "label": "If Yes, please specify",
    "conditional": { "show": true, "when": "73", "eq": "yes" }
  },
  {
    "key": "82",
    "type": "selectboxes",
    "input": true,
    "label": "Are you allergic to any of the following?",
    "values": [
      { "label": "Acrylic", "value": "Acrylic" },
      { "label": "Aspirin", "value": "Aspirin" },
      { "label": "Codeine", "value": "Codeine" },
      { "label": "Latex", "value": "Latex" },
      { "label": "Local Anesthetics", "value": "Local Anesthetics" },
      { "label": "Metal", "value": "Metal" },
      { "label": "Penicillin", "value": "Penicillin" },
      { "label": "Sulfa Drugs", "value": "Sulfa Drugs" }
    ]
  },
  {
    "key": "83",
    "type": "checkbox",
    "input": true,
    "label": "Other allergy?"
  },
  {
    "key": "specify-83",
    "type": "textfield",
    "input": true,
    "label": "If Yes, please specify",
    "conditional": { "show": true, "when": "83", "eq": "true" }
  },
  {
    "key": "81",
    "type": "selectboxes",
    "input": true,
    "label": "Women: Are you...",
    "values": [
      { "label": "Nursing?", "value": "Nursing?" },
      { "label": "Pregnant/Trying to get pregnant?", "value": "Pregnant/Trying to get pregnant?" },
      { "label": "Taking oral contraceptives?", "value": "Taking oral contraceptives?" }
    ]
  },
  {
    "key": "86",
    "type": "textarea",
    "input": true,
    "label": "Additional comments"
  },
  {
    "key": "88",
    "type": "signature",
    "input": true,
    "label": "Patient signature",
    "validate": { "required": true }
  }
]

Submission (patient_submitted_data)

{
  "72": "Dr. Sarah Chen",
  "73": "yes",
    "input": true,
    "label": "Patient signature",
    "validate": { "required": true }
  }
]

Submission (patient_submitted_data)

{
  "72": "Dr. Sarah Chen",
  "73": "yes",
  "specify-73": "Appendectomy 2018",
  "82": {
    "Acrylic": false,
    "Aspirin": false,
    "Codeine": false,
    "Latex": true,
    "Local Anesthetics": false,
    "Metal": false,
    "Penicillin": true,
    "Sulfa Drugs": false
  },
  "83": true,
  "specify-83": "Sulfonamides",
  "81": {
    "Nursing?": false,
    "Pregnant/Trying to get pregnant?": false,
    "Taking oral contraceptives?": true
  },
  "86": "Patient notes they have a mild latex sensitivity discovered during a prior procedure.",
  "88": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

Key	Type	Note
`72`	`textfield`	Free-text answer
`73`	`radio`	One value from `values[].value`
`specify-73`	`textfield`	Conditional on `73 == "yes"`
`82`	`selectboxes`	Every option mapped to a boolean
`83`	`checkbox`	Boolean
`specify-83`	`textfield`	Conditional on `83 == true`
`81`	`selectboxes`	Multi-select; unchecked options must still be present as `false`
`86`	`textarea`	Longer free text
`88`	`signature`	PNG data URI

Form Responses

The list endpoint requires a patient_id and returns submissions for that patient at the location.

The detail endpoint returns form_schema_id — the UUID of the exact schema version that was submitted against. This lets you reconstruct the field definitions as they were at the time of submission by fetching GET /form_schemas/:form_schema_id, which may differ from the current newest_version_id if the form
has since been updated.

Note: Only form responses submitted via the NexHealth API are returned. Submissions recorded directly in Eaglesoft are not currently available through this endpoint.