Health History Forms - Checkin


Health history forms allow the patient to fill out some of their medical history information before an appointment. They will be able to do this via the athenaCommunicator patient portal or via this API, and changes made to either source will be visible to the other. You can submit updated forms until the appointment is checked in. At that point, a reconciliation document is generated for the practice and the health history form can no longer be modified. Because of this reconciliation process, this is the recommended way to get patient-entered data into the chart. Only athenaNet practice users can update the chart. Patients cannot update their chart information. 

The health history forms (HHF for short) are a subset of the possible clinical questions configured by the practice. (They are not intended to provide chart information about the patient. For that, use the CCDA API or chart-specific APIs.) For partners with access to athenaNet's UI, the possible clinical questions are configured in Gear Icon => Clinicals Admin. The HHFs are configured in Gear => Clinicals Admin => [Forms and Letters] Patient Portal Health Forms. This means that the health history forms cannot ask questions that aren't on the patient's chart.

A practice can configure multiple forms, each of which can be gated by appointment type, provider, or department, as well as the gender or age of the patient. Forms are not visible to the API unless marked as "Live on Portal" in athenaNet.

Each form contains one or more sections, each of which can also be gated by the age and gender of the patient. So, for example, you can have a general form that only asks OB/GYN questions of female patients.

API Overview

There are two sets of APIs: one iw to get the generic forms for a practice and the other is to get patient-specific forms for an appointment.

1. The below healthhistoryforms API endpoints are the generic ones. These calls show all of the forms configured at a practice (that are marked Live on Portal). The former gets the list of forms, and the latter gets the contents of each form.  In the contents of each form, each section will have populatedfrom = "Preview".


2. GET /healthhistoryforms, GET /healthhistoryforms/{formid}, and PUT /healthhistoryforms/{formid} are the appointment (and thus patient) specific calls.

That means only the forms for the particular age and gender of the patient, and the particular appointment type, department, provider, specialty, etc. will be accessed. The populatedfrom can have two values: "Chart" and "Previous Answers". The former means the answers were retrieved from the patient's chart, and happens before any submissions. Once a section has been submitted, subsequent GETs will have populatedfrom = "Previous Answers".  This is also true if the patient already started filling out the form on the athenaCommunicator patient portal prior to arriving for their appointment.

In general, the appointment-specific API will be the one API users will use on a regular basis.

For the PUT call, you’ll be sending the exact same data structure back from the original GET, with possible changes to the answers. Each section should have complete set to true once it is completed by a patient. The various IDs that are not specified in the fielddata hash should be parroted back to the API unchanged; this is how we keep track of the questions. Those IDs are not shared between practices. They are set whenever the portal health history form questions are added or changed. While it's easiest just to return the entire structure back, the minimum to be sent back are the "portalformsectionid", "type", "complete", "empty", and "questions" elements. In the "questions" elements, you just need the "fields" (and subelements) and "portalformquestionid" elements. The exceptions are the MEDICATION and ALLERGY sections, in which almost all elements under "questions" are required.


  1. A GET must precede any PUTs. This does some necessary initialization, as well as retrieving any existing answers the patient might have filled out on the portal.
  2. When submitting a section, you must set complete = "true". Otherwise it will ignore that section. 
  3. If you haven't changed anything in a given section and are still submitting it, mark both complete = "true" and empty = "true".
  4. You do NOT have to complete/submit all forms nor sections within a form.
  5. You can submit a section multiple times. Each time is not cumulative -- each section submission will clear the previous answers, so submit all answers for a given section.
  6. You can continue submitting sections until check-in is complete (either via the API or the athenaNet UI's "Done with Check in" button).

JSON Structure and Inputs

Each form section has a similar layout. They include the following fields:

  • portalformsectionid: Identifies the section, required, different for each section even if they are the same type, different across practices.
  • type: The section type (see "Sections" below).
  • name: The practice-defined name of the section.
  • complete (true/false): Whether the section has been submitted, required for submission.
  • empty (true/false): Whether the section contains no changes.
  • minage, maxage, ageunit (Y/N), sex: The limitations of this section, for your reference.
  • populatedfrom / populated: (Preview) today's date, (Chart) date first GET was used on form, (Previous Apartment) date of last submission for this section.
  • fielddata: Lists the user-facing inputs for this section type, describing the fields, input types, and options for select fields.
  • questions: This section lists the actual questions to be asked. The "fields" subsection contains the current answer (either from a previous submission or the patient's chart). The remaining elements are additional identifying information.

The field "DEFAULT" is poorly named. It's actually the ANSWER to the question (normally Y/N) signifying whether the patient has checked off the question.

If the "fielddata" DEFAULT INPUTTYPE is CUSTOM (for the SOCIAL and OBGYN section types), the inputs are defined on a per-question basis in the "questions" section.

Input Types

These are an exhaustive list of input types.

If the field is marked as "REQUIRED" then it should always have a value, however, we don't actually check to see if you have. Not all athenaNet data will contain data for required fields. This means you should check to see if there is an existing value, and require the field if there is an existing value or if the question was never answered. 

If the field is marked as "LIST" then it should contain an array of values (normally APPROXDATEs).

  • CHECKBOX: A true/false field. A null/blank is equivalent to false.
  • YESNO: A Y/N/null field. N and null will show up as different in reconciliation.
  • DROPDOWN: A selection from a list of valid values (given as a value/name pair). 
  • NUMERIC: A real number. NOTE: There are some values in athenaNet where non-numeric data was entered. This will eventually be eventually be fixed, but, unfortunately, not anytime soon.
  • DATE: A date in MM/DD/YYYY format.
  • APPROXDATE: A date in either YYYY, MM/YYYY, or MM/DD/YYYY format.
  • FREETEXT: A free text field (the length is not well defined). Not currently used. (Used for RxNormName, but that shouldn't be an input field and will be deprecated from the fielddata list.)
  • HIDDEN: A read-only free text field. Currently only used for externalnote for medications with a particular practice setting.
  • AUTOCOMPLETE: A free text field. While athena uses a drop down for it, users can enter any value in the UI.


Currently, there are 8 possible section types.   


Note that a section type can occur more than once, though the sections will generally have different names.

In general, the list of questions configured for the health history form is a subset of the questions configured by the practice for the patients' charts.

Every section except for MEDICATION and ALLERGY will have a "portalformquestionid", identifying the particular question. If the same question is asked twice (on two different forms, or two different sections of the same type on the same form), they will have different portalformquestionids. Each time you add a new question (or delete an existing one and re-add it), it will get a new portalformquestionid.


The past medical history section is the simplest section type. It consists of a list of checkbox questions.

  • 'DEFAULT' is the Y/N checkbox that says whether they've had this condition before.
  • 'pastmedicalhistoryquestionid' ties it to the practice-specific medical history question, and can be used to tie the same question across multiple forms.
  • 'text' is the patient-friendly name of the medical history question.


The surgical history section again contains a list of checkbox questions, with an optional list of surgery dates.

  • 'DEFAULT' is the Y/N checkbox which says whether they've had this surgery before.
  • If 'DEFAULT' is 'Y', then the SURGERYDATE is a optional list of surgery dates. Even one surgery date should be submitted as a (singleton) list.
  • 'surgicalhistoryprocedureid'  ties it to the practice-specific surgical history question, and can be used to tie the same question across multiple forms.
  • 'procedurecode' is the CPT code of the procedure, if configured as such by the practice.
  • 'text' is the patient-friendly name of the surgical history question.


The vaccination section contains a list of checkbox questions, with a required list of administered dates.

  • 'DEFAULT' is the Y/N checkbox which says whether they've had this vaccine.
  • If DEFAULT is 'Y' then 'ADMINISTERED' is a required list of administered dates. Even one administration should be submitted as a list.
  • 'cvx' is the HL7 Table 0292, Vaccine Administered code as maintained by the CDC:
  • 'text' is the patient-friendly name of the vaccine.


Both the social history and Ob/Gyn history sections contain custom questions, where each question follows its own format. Both sections can contain global or local questions defined by the practice.

  • 'inputtype' is the input type of the question.
  • 'text' is the patient-facing name of the question.
  • 'fields' contains the answer to the question being asked. It always contains 'DEFAULT', which is the answer to the question.
  • 'dropdownvalues' (which only exists if inputtype = 'DROPDOWN') lists the possible answers to this question.
  • clinicalelementid is the unique global social history question identifier. localclinicalelementid is the unique practice-specific social history question identifier. Only one or the other will exist for each question, identifying whether it's a global or practice-defined question. You can use this field to tie the same question across multiple forms, and to perform global optimizations.


NOTE: You must have the beta practice setting "Family History Reconcilliation Update" turned on. We are looking for user feedback of some UI changes related to this practice setting before releasing it to all practices. If you are submitting the family history section, please contact us.

Make sure you support multiple relations of the same type having the same issue (two brothers both having high blood pressure), and a single person having an issue more than once (the mother having two instances of cancer).

The family history section is structured differently than other sections. Other sections have question fields that contain a list of single question/answer pairs with some metadata. For the family history section, each of those question/answer entries is itself an array of data, one sub-entry per relation or per occurence. The relations do not specify biological vs logical (step/adoptive/etc.) relations. Biological relations are assumed. In general, practices only track relations that have problems, although they can be configured to have an "Alive and Well" problem.

  • 'snomedfamilyhistoryproblemid' ties it to the practice-specific family history element, and can be used to tie the same question across multiple forms.
  • 'snomedcode' is the SNOMED code value for this particular problem.
  • 'text' is the patient-friendly name of the problem.
  • 'origtext' is the SNOMED term for this problem, which almost always matches text. We recommend you use text and not origtext.
  • 'fields' contains a list of problem instances, each of which contains:
    • 'default' is the Y/N checkbox that says whether this person has this problem.
    • 'relation' is the relation this person has with the patient (Mother, Sister, etc.).
    • 'relationkeyid' is the ID of the particular relation. Each relation type has its own keyspace. This means you can have a Brother 1, Brother 2, Sister 1, etc.
    • 'onsetage' is the age when the problem started.
    • 'diedofage' is the age when the relation died from this particular problem.


  • 'relationkeyid' is a REQUIRED field. If you adding a new relation, please specify the next available numerical value for relationkeyid.
  • It's possible to receive a missing/null relationkeyid. This is always from the portal. Until that is fixed, please assign the next available relationkeyid to that empty value.
  • We do no cross checking between entries. That means a particular relative could be specified to have died at two different ages from two different problems.
  • We match on problem/relation/relationkeyid/onsetage. This means that a given person (e.g. Brother 2) can have two instances of the same problem (e.g. two instances of cancer).


The allergy section, unlike previous sections, contains all of the patient's allergies.

  • 'allergyid' is the global athenaNet ID for this allergy. This is the same ID across all practices. You can get a list of allergies to add using our allergy API.
  • 'name' is the patient-friendly name for this allergy.
  • 'onsetdate' is the date the allergy was first noticed or reported.
  • 'allergyreactionid' is a list of reactions this patient has to this allergen.
  • 'severityid' is a list of reaction severities. If you specify reactions, you must also specify their severities. If the severity is not known, then the value "none" must be used, which is a special value not currently in the fielddata specification. The allergyreactionid and severityid lists must have the same number of elements, as they are mapped to each other in order.


A patient might have multiple instances of a given medication (e.g,. they were prescribed a branded medication, which was changed to the generic, and the patient had 3 refills). We will only send however, the most recent medication in each group (where group combines similar medications). See the medication API overview for more details about how we group medications.

  • 'medicationid' is the global athenaNet ID for this medication. This is the same ID across all practices. You can get a list of medications to add using our medication API.
  • 'rxnormid' is the RxNorm ID for this medication. Not all medications will have this.
  • 'rxnormtype' is the RxNorm codepage the ID is from.
  • 'rxnormname' is the RxNorm name for this medication.
  • 'name' is the athenaNet name for this medication.
  • 'startdate' is the date the medication was first prescribed, entered, downloaded, etc.
  • 'stopdate' is the date the medication was terminated. This field must be used to "stop" a medication.
  • 'meddeactivatedreasonid' is the reason why the medication was stopped. It's optional, but should only be filled if stopdate is filled.
  • 'frequency', 'displaydosageunits', 'dosagequantity', and 'sig' are the signature of this medication. These fields are currently not well supported and should not be modified.
  • 'externalnote'. This HIDDEN field is only shown if the practice setting "Show External Notes on Medications in Portal" is turned on. This is a read-only field, and should submitted unchanged. You can choose to show this to the patient or not. Our patient portal currently does.

NOTE: There are two uncommon types of medications without medicationids. These you will not be able to add nor update, and will always show up in reconciliation as a conflict. This behavior is similarly broken through our patient portal. The first type is practice-defined medications called compounded medications (defined in settings => [admin] Clinicals => [Order Configuration] Compounded Medications. The other type is downloaded medications from certain small (i.e., not surescripts) sources.


A reconciliation document is generated when an appointment is checked in and there is at least one health history form submitted. As part of the debugging process, after you have submitted some forms and started check-in via the "Start Check in" athenaNet UI or via the API, the Check In stage has a printable version of the form you submitted near the bottom of the page. It shows the percentage of each form submitted (just the number of completed sections divided by the total number of sections that are appropriate for this patient/appointment).

The reconciliation document will appear as a separate tab during the encounter, or if you visit the patient's chart.

IMPORTANT: If there are prior reconciliation documents that have not been completed, the oldest one will be the one shown by default. The provider should reconcile each document in order. The fact that you have pending documents to reconcile will show up on the patient's health history tab as well as any open encounter. They are above the relevant section (e.g. social history) with a "N Documents to Reconcile" link.

The reconciliation is divided up by section. Each section has a list of items, with the patient's chart on the left and the incoming document on the right. Each row will either be a match, a no matching item (for adds or deletes), or a conflict (when a value is changed). The provider then selects either the chart version or the incoming version for each item. The provider can also enter a note (for some sections). He or she then must update the chart. This is immediately reflected on the patient's chart and any currently open encounters. 

Known Issues and Limitations

In addition to the section-specific issues above, these are additional issues:

  1. Notes (both per-question and per-section) are not supported. There is currently no timeline to expose these notes.
  2. Some data we send you will not match the input type requirements -- either non-numerical values in NUMERIC fields or missing vaccine administered dates. We are working to clean these up over time.
  3. Social and OB/GYN entries that are configured for the patient's chart but not in health history forms will still show up in reconciliation, acting as if you sent in a blank value for that non-existent question.
  4. Surgeries that are deactivated in athenaNet are not sent in the surgical history section of the health history form. They do however, show up as conflicts during reconciliation.
  5. Similarly, allergies and medications that are deactivated and stopped respectively in athenaNet are not sent to you but do show up as conflicts during reconciliation.
  6. When submitting allergies, sometimes reconciliation will complain that the last modified date has changed (to Unknown in the chart).
  7. Medication sig fields are not well supported.
  8. Deactivating a medication or allergy will show up as a "No Matching Item" during reconciliation instead of showing the stopped medication/allergy.
  9. Sections that have nothing to change will sometimes show up during reconciliation.
Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others