--- title: "Update a patientForm" method: PUT path: "/patientForms/{patientFormId}" tags: ["patientForms"] --- # Update a patientForm `PUT /patientForms/{patientFormId}` ## Path parameters - `patientFormId` string, required ## Request body - PatientFormRequest - `status` 'pending' | 'unstarted' | 'started' | 'completed', required - `processingStatus` 'open' | 'in-progress' | 'closed', required — processingStatus ## Response `200` PatientForm - PatientFormResponse — A patient form is a specific instance of a form template that has been sent to or filled out by a patient, such as an intake form, consent form, or feedback survey. It tracks the patient's answers, completion status, and processing state, and can be linked to an appointment, a file upload, or a resulting scheduling offer. It also supports advanced workflows like jump logic between form sections, EHR writeback of answers or PDFs, and staff review of submitted answers. - `patient` string — the ID of the patient who filled out the answers for this form. - `status` 'pending' | 'unstarted' | 'started' | 'completed' — The completion status of the patient form under the patient's perspective, knowingly: - `pending`: the initial status, not seen by the patient, created when a message is sent out with the form link; - `unstarted`: set when the patient clicked on the link to open the form but only saw the welcome screen, without actually answering any questions; - `started`: when the patient started answering at least one question, but hasn't finished the form yet; - `completed`: the patient has finished answering all the questions and cannot edit the form anymore. - `completedAt` string, date-time — the date/time when the patient finished all the responses of this form. - `processingStatus` 'open' | 'in-progress' | 'closed' — The internal staff's management status for a completed form, serving the purpose of organizing which answers were analysed by a staff member or not. - `open`: the form was completed by a patient but not seen by any staff member yet; - `in-progress`: a staff user is analysing the answers; - `closed`: the form has been completely analysed by a member of the staff team. - `processingStatusUpdatedBy` string — the ID of a staff `user` who analysed the responses of this completed patient form and changed its `processingStatus`. - `processingStatusUpdatedAt` string, date-time — the date/time when a staff `user` analysed the responses of this completed patient form and changed its `processingStatus`. - `lumabot` boolean — flag to signal whether a form was filled out in the shape of a patient chat with a bot. - `appointment` string — the ID of an appointment related to this form. - `fileUpload` string — the ID of a fileUpload related to this form. - `duration` number — the time it took (in minutes) for the patient to complete this form. - `url` string — deprecated: custom patient form url, basically to identify any patient in survey monkey, an external forms service that's not being used anymore by Luma. - `currentItemId` string — The code of the current question the patient was last shown, before answering it. Such a code must be the content of any `responses.pages[0].questions[x].id`, or `success`. Usually this will contain each id, in sequence, but patients can go back and forth. Also, forms can have jump logic, and some questions might not be displayed to the patient. When the form is completed, this is updated to `success`. - `patientFormTemplate` string — the ID of the template of questions that was displayed for the patient. - `patientFormTemplateName` string — the name of the template of questions used as a basis for these form answers. See `patientFormTemplates`. - `patientFormTemplateType` 'intake' | 'pre-qualification' | 'feedback' | 'ccda' — A flag to help filter forms by their originally desired purpose. The form structure and behavior is identical, but depending on the settings screen, some forms may be displayed as a selectable option or not. Also, CCDA forms enable some more form components/questions that are compatible with EHR systems nation wide. - `intake`: a regular form, intended to be sent to patients manually, or in reminders, or even custom actions. - `pre-qualification`: a form to be displayed before the scheduler is shown to patients. In the scheduler settings page, you can only select a `pre-qualification` form to be displayed before the patient actually schedules an appointment. - `feedback`: a form to be sent to patients after their visits, to rate the service they've received. On the feedback settings page, you can only select a form with this flag. - `ccda`: a form containing special questions that conform to the standard format which can be read by EHR Systems. - `ref` 'reminder' | 'referral-reminder' | 'feedback-reminder' | 'followup' | 'outbound-referral-reminder' | 'form-reminder' | 'reschedule' | 'waitlist' | 'appointment-offer' | 'chat-notification' | 'pin-verification' | 'chat' | 'chat-audit' | 'chat-audit-tz' | 'feedback' | 'waitlist-offer' | 'referral-followup' | 'outbound-referral-outreach' | 'referral-redirect' | 'broadcast' | 'generic' | 'stop' | 'bot:followup' | 'telehealth' | 'waiting-room-patient' — Indicates what this is about. Depending on this value, you also know what the parameter `refId` refers to.
- reminder (`refId` will be the ID of a `Reminder`)
- referral-reminder (`refId` will be the ID of a `Reminder`)
- feedback-reminder (`refId` will be the ID of a `Reminder`)
- followup (`refId` will be the ID of a `Reminder`)
- outbound-referral-reminder (`refId` will be the ID of a `Reminder`)
- form-reminder (`refId` will be the ID of a `Reminder`)
- reschedule (`refId` will be the ID of a `Reminder`)
- waitlist (`refId` will be the ID of a `Waitlist`)
- appointment-offer (`refId` will be the ID of a `Offer`)
- chat-notification (`refId` will be the ID of a `Message`)
- pin-verification (`refId` will be the ID of a `Message`)
- chat (`refId` will be the ID of a `ChatActivity`)
- chat-audit (`refId` will be the ID of a `ChatActivity`)
- chat-audit-tz (`refId` will be the ID of a `ChatActivity`)
- feedback (`refId` will be the ID of a `Feedback` request)
- waitlist-offer (`refId` will be the ID of an `Appointment`)
- referral-followup (`refId` will be the ID of a `Referral`)
- outbound-referral-outreach (`refId` will be the ID of a `Referral`)
- referral-redirect (`refId` will be the ID of a `Referral`)
- broadcast (`refId` will be the ID of a `Broadcast`)
- generic (`refId` will refer to the same object of the previous message to this same patient)
- stop (`refId` will refer to the same object of the previous message to this same patient)
- bot:followup (`refId` will be the ID of a `Patient`)
- telehealth (`refId` will be the ID of a `Telehealth` object)
- waiting-room-patient (`refId` will be the ID of a `WaitingRoomPatient` object)
- `refId` string — The ID of the Object refereced by the `ref` field. - `offer` string — The ID of an appointment `Offer` related to these form answers. - `language` 'en' | 'es' | 'pt' — The language in which the form was answered by the patient. - `accessedFrom` string — IP address of the patient who filled out the form. - `previousPatientForm` string — PreviousPatientForm and nextPatientForm will be used to make it possible for forms to be able to jump to another form with another template so we can reduce the number of unecessary questions in a single form, which should help with organization and performance. One form must call the jump template, at which time we create a new patientForm and set the previous form ID on its `previousPatientForm` property. - `nextPatientForm` string — PreviousPatientForm and nextPatientForm will be used to make it possible for forms to be able to jump to another form with another template so we can reduce the number of unecessary questions in a single form, which should help with organization and performance. One form must call the jump template, at which time we create a new patientForm and set the new form ID on the first form's `nextPatientForm` property. - `responses` object — Contains information about the responses given by the patient. - `currentItemId` string — The code of the current question the patient was last shown, before answering it. Such a code must be the content of any `responses.pages[0].questions[x].id`, or `success`. Usually this will contain each id, in sequence, but patients can go back and forth. Also, forms can have jump logic, and some questions might not be displayed to the patient. When the form is completed, this is updated to `success`. - `path` string[] — The sequence in each questions were seen by the patient. - `finalDisposition` object — The last question or template answered/seen by the patient on form completion. Same structure as a question in `responses.pages[0].questions[i]`. - `pages` object[] — The pages of the form. Luma forms always only have one page, whose index is zero. - `questions` object[] — An array of metadata about the questions and their answers. The information about the questions is kept here because the template might be updated at any time, so the version of these question might be out-of-date when compared to the actual patientFormTemplate. - `id` string — the reference code for this question, also used in `currentItemId` and `path`. - `type` '2FA' | 'address' | 'date' | 'dropdown' | 'e_signature' | 'email' | 'group' | 'information_capture' | 'insurance_card' | 'jump' | 'long_text' | 'medication_search' | 'multiple_choice' | 'patient_information' | 'pharmacy_search' | 'phone_number' | 'scheduler' | 'short_text' | 'ssn' | 'template_welcome' | 'template' | 'yes_no' | 'zipcode' | 'copay' | 'docusign_templates' | 'insurance_verification' | 'insurance_capture' | 'medication_list' | 'immunization_history' | 'allergy' | 'surgical_history' | 'family_history' | 'problems' | 'social_history' | 'scheduler_component' | 'book_status_component' | 'demographics' — The `PatientFormTemplateItemTypeKeys`, representing the type of question. - `group`: at this root level, a special `type: group` may be used, and in that case, `responses.pages[0].questions[x].properties.items[]` will contain objects with a structure similar to one of `responses.pages[0].questions[i]` (recursively), with the exception that the inner question cannot be of type `group`. - `jump`: a special type of question, containing a property called `script`in `responses.pages[0].questions[x].properties.script` which resolves to one of the values in `responses.pages[0].question[x].properties.answers[k].label`. Each `responses.pages[0].question[x].properties.answers[k].properties` will determine if the jump is to the next question (nothing inside properties), or another specific question (properties object containing a `goTo` with another question squiggly), or redirect (properties object containing a final `url` for redirection). - `title` string - `description` string — the description of the question - `locales` object — A map-object whose keys may be any of these language codes `es` or `pt` - `es` object - `description` string — the translation of the description of the question into spanish - `title` string — the translation of the title of the question into spanish - `properties` object — same structure as `responses.pages[0].questions[i].properties`. - `pt` object - `description` string — the translation of the description of the question into portuguese - `title` string — the translation of the title of the question into portuguese - `properties` object — same structure as `responses.pages[0].properties`. - `text` string — the text of the question - `squiggly` string — The code to be used in message templates, in the format `custom-form-xyz`, which becomes `{{custom-form-xyz}}` in message templates, and turns into the URL for the patient to click and answer the form. - `redirectType` 'externalUrl' | 'goTo' | 'goToForm' | 'goToPrevious' | 'isFinal' | 'none' | 'reschedule' | 'scheduler' - `validations` object - `required` boolean - `answers` object[] — This is the `responses.pages[0].questions[i].answers` array. Contains the answer (or possible answers) for the question in `responses.pages[0].questions[i]`. When a drop down menu is displayed, then all the possible answers are listed here. But only the one selected is marked as `selected: true`. - `id` string — id of a question - `redirectType` 'externalUrl' | 'goTo' | 'goToForm' | 'goToPrevious' | 'isFinal' | 'none' | 'reschedule' | 'scheduler' — PatientFormTemplateItemRedirectType - `text` string - `label` string - `score` string - `code` string - `disabled` boolean - `locales` object — A map-object whose keys may be any of these language codes `es` or `pt` - `es` object - … - `pt` object - … - `properties` object — This is `responses.pages[0].questions[i].answers[j].properties`. Has the same structure as `responses.pages[0].questions[i].properties`. - `insurances` object[] - `payerName` string - `_id` string - `planName` string - `memberName` string - `firstname` string - `lastname` string - `memberNumber` string - `insuranceGroupName` string - `url` string — URL of the front picture of the insurance card - `urlBack` string — URL of the back picture of the insurance card - `fileUpload` string — the ID of a fileUpload for the picture of the insurance card (front) - `fileUploadBack` string — the ID of a fileUpload for the picture of the insurance card (back) - `active` boolean - `status` 'archived' | 'active' - `externalId` object - `source` string - `value` string - `payerId` string - `verification` object - `status` 'unknown' | 'active' | 'inactive' | 'failed' - `updatedAt` number — timestamp - `requestedBy` object — User details - … - `lookupResults` object — ReplaceAny - `patient` object — Patient - `safeId` string — safeId - `name` string — Full name - `firstname` string — First name - `lastname` string — Last name - `middlename` string — Middle name - `alternativeName` string — Alternative name - `displayPhone` string — Phone number displayed in staff profile. Not used for communication purposes. - `displayStatus` 'active' | 'pending' | 'suspended' — Account status. Informative field only, not used for access control. - `email` string — User's e-mail address in lowercase. - `roles` string[] — User's roles, used for access control. - `rolesByUser` RolesByUser — Object containing 2 keys, referringProvider and renderingProvider. The value for each key is an array. The content of the array should be the root account ids under the same organization, where this user has the role with the same name of the key. - … - `organization` string — The ID of the organization controling this root user account. - `contact` object[] — List of contact infos of this user. - … - `doNotContact` boolean — Indicates if the user has requested not to be contacted anymore. - `doNotContactMessage` string — The ID of the message where the user requested not to be contacted anymore. - `groups` string[] — List of group IDs to which this user belongs. - `stripeCustomerId` string — Customer ID from stripe for this account - `stripeSubscriptionId` string — Stripe subscription ID - `salesforceId` string — Salesforce Account ID for this account - `salesforceData` SalesforceData — Salesforce internal meta data for this account. - … - `active` number — Indicates if a user is active and able to log into the system or not. - `language` string — User's preferred language. - `externalId` ExternalId - … - `secondaryExternalId` ExternalId - … - `dateOfBirth` object — Date of birth - … - `address` string — User's address. - `city` string — User's city. - `state` string — User's state. - `country` string — User's country - `postcode` string — User's postal code. - `gender` 'male' | 'female' | 'unknown' | 'nonbinary' — User's gender. - `avatar` string — The ID of a FileUpload containing the profile picture of the user. - `directMessagingEmail` string — E-mail for direct communication with the user. - `website` string — User's website. - `demoConfiguration` object - … - `type` 'staff' | 'doctor' | 'guest' — type - `allowedIps` string[] — allowedIps - `dependent` object — Dependent - `firstname` string - `lastname` string - `dateOfBirth` object - … - `relationshipToSubscriber` 'spouse' | 'grandfather-or-grandmother' | 'grandson-or-grandaughter' | 'nephew-or-niece' | 'foster-child' | 'ward-of-the-court' | 'stepson-or-stepdaughter' | 'self' | 'child' | 'employee' | 'unknown' | 'handicapped-dependent' | 'sponsored-dependent' | 'dependent-of-minor-dependent' | 'significant-other' | 'mother' | 'emancipated-minor' | 'organ-donor' | 'cadaver-donor' | 'injured-plaintiff' | 'child-where-insured-has-no-financial-responsibility' | 'life-partner' | 'other-relationship' — PatientRelationship - `address` string - `primary` boolean - `properties` object — This is `responses.pages[0].questions[i].properties`. These are the properties of the current question. If type is `group`, then `responses.pages[0].questions[i].properties.items` will contain sub-questions inside the group. - `answers` object[] - `showDescription` boolean - `visibility` string - `showCustomAction` boolean - `scoringEnabled` boolean - `allowMultipleSelection` boolean - `allowOtherChoice` boolean - `includeNoneOfAboveChoice` boolean - `includeInsuranceCard` 'DEFAULT' | 'REQUIRED' | 'OPTIONAL' - `addToAppointment` boolean - `persistAnswer` boolean - `mustExist` boolean - `params` object[] - `goTo` string — The id of a question where the patient will be taken after this question - `url` string — URL to redirect the patient. - `template` string - `actionLabel` string - `actionHref` string - `script` string - `items` object[] — This is `responses.pages[0].questions[i].properties.items`. Same structure as `responses.pages[0].questions`. Used if `responses.pages[0].questions[i].type` is `group`. These items will be sub-questions inside the group, but they themselves cannot be of type `group` again (no groups inside groups). - `copay` string - `immunizationHistory` object[] — Immunization History. Additional info on `reponses.pages[0].questions[i].answers`, such as `reponses.pages[0].questions[i].answers[j].answer: 2022`. with the same ids as the items in the history here. Only used when form is CCDA. - `id` string — UUID of the immunization history entry - `code` string - `codeSystem` string — Luma's internal ID referring a `CCDACodeSystem` on the database. - `description` string — Description of the immunization item according to the chosen code system. - `friendlyName` string — Friendly description of the immunization item. - `surgicalHistory` object[] — Surgical History.Additional info on `reponses.pages[0].questions[i].answers`, such as `reponses.pages[0].questions[i].answers[j].answer: 2022`. with the same ids as the items in the history here. Only used when form is CCDA. - `id` string — UUID of the surgical history entry - `code` string - `codeSystem` string — Luma's internal ID referring a `CCDACodeSystem` on the database. - `description` string — Description of the surgical procedure item according to the chosen code system. - `friendlyName` string — Friendly description of the surgical procedure item. - `familyHistory` object[] — Family History. Additional info on `reponses.pages[0].questions[i].answers`, such as `reponses.pages[0].questions[i].answers[j].familyMembers: [ 'Mother' ]`. with the same ids as the items in the history here. Only used when form is CCDA. - `id` string — UUID of the family history entry - `code` string - `codeSystem` string — Luma's internal ID referring a `CCDACodeSystem` on the database. - `description` string — Description of the family history item according to the chosen code system. - `friendlyName` string — Friendly description of the family history item. - `locales` object — A map-object whose keys may be any of these language codes `es` or `pt` - `es` object - … - `pt` object - … - `canSkip` boolean - `notifyStaff` boolean - `mappingField` string — The name of any Patient model fields. When this property is set, then the question will have its answer pre-populated using the value from the Patient model. As an example, if the mappingField for the question is `firstname`, when creating the form, the system will try to get this information from the patient data, and if there's a value on this field, it will be set as the default answer for the question. - `answers` object[] — A simplified representation of the answers contained in `responses.pages[0].questions[i]`. - `id` string — The id of the question to which this answer refers. The content of any `responses.pages[0].questions[x].id`. - `answerId` string — The id of the answer chosen or entered by the user for the given question. - `question` string — the label of the question being answered by the patient. - `answer` string — the answer given by the patient, either by typing of by picking an option. - `questionType` '2FA' | 'address' | 'date' | 'dropdown' | 'e_signature' | 'email' | 'group' | 'information_capture' | 'insurance_card' | 'jump' | 'long_text' | 'medication_search' | 'multiple_choice' | 'patient_information' | 'pharmacy_search' | 'phone_number' | 'scheduler' | 'short_text' | 'ssn' | 'template_welcome' | 'template' | 'yes_no' | 'zipcode' | 'copay' | 'docusign_templates' | 'insurance_verification' | 'insurance_capture' | 'medication_list' | 'immunization_history' | 'allergy' | 'surgical_history' | 'family_history' | 'problems' | 'social_history' | 'scheduler_component' | 'book_status_component' | 'demographics' — the type of question. - `path` string[] — path - `finalDisposition` string — Not used, and always filled with an empty string. Rather, see `reponses.finalDisposition` - `integratorUpdateResults` object — integratorUpdateResults - `status` 'success' | 'failure' | 'pending' — PatientFormIntegratorUpdateResultsStatus - `error` string - `directMessageCcdaUpdateResults` object — directMessageCcdaUpdateResults - `status` 'success' | 'failure' | 'pending' - `error` string - `requestAt` string, date-time - `responseAt` string, date-time - `calculationResult` object — If the `patientFormTemplate` has a `calculation` field, which is a javascript code, then the result will be stored here. - `availabilities` string[] — availabilities - `facilities` string[] — facilities - `querystring` object — querystring ReplaceAny ## Other responses - `401` — Not authenticated - `403` — Access token does not have the required scope --- [API](https://skmtc.net/lumahealth/apis/rest-service.md) · [All operations](https://skmtc.net/lumahealth/apis/rest-service/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lumahealth/rest-service/revisions/d3c75c2a2f1d/schema)