API Change (21.7): New Social History Experience

Summary: With the release of the new feature Social History, we make changes to our global Social History questions, including the removal of some questions. API endpoints that call Social History questions and templates configured by a practice are affected by the changes to the global questions.

Products: athenaClinicals

Available: 21.7 GA


  • This has a breaking change
  • API endpoints affected include these categories
    • Social History questions and templates 
    • Patient selected templates 
    • Patient Social History 
    • Health History forms 


All endpoints affected  

  • GET /v1/{practiceid}/chart/configuration/socialhistory 
  • GET /v1/{practiceid}/chart/{patientid}/socialhistory 
  • PUT /v1/{practiceid}/chart/{patientid}/socialhistory 
  • GET /v1/{practiceid}/appointments/{appointmentid}/healthhistoryforms/{formid}
  • PUT /v1/{practiceid}/appointments/{appointmentid}/healthhistoryforms/{formid}
  • PUT /v1/{practiceid}/chart/{patientid}/socialhistory/templates 
  • GET /v1/{practiceid}/chart/{patientid}/socialhistory/templates 

Why we’re making the changes 

We are committed to update athenaNet’s global Social History content on a regular basis to adhere to quality program and regulatory requirements as well as respond to industry trends.  

The new social history experience: 

  • Uses a new admin page to configure global social history questions 
  • Organizes related questions into categories based on new social history templates 
  • Omits questions that are irrelevant for your patient based on age, sex, specialty, and the patient's answers to related social history questions 
  • Includes a navigation bar so you can quickly go to the questions of interest 
  • Supports use of custom questions in local social history templates 
  • Is reflected in the Full Encounter Summary, which uses the same organization 

To ensure your APIs connected to Social History in athenaNet align with the new experience, you must update certain endpoints. 

Is this a breaking change: Yes 


Social History questions and templates configured 

  • Endpoint: GET /v1/{practiceid}/chart/configuration/socialhistory 
  • Change: Templateids will change 
  • Update to code: No

Patient selected templates 

  • Endpoints:
    • PUT /v1/{practiceid}/chart/{patientid}/socialhistory/templates 
    • GET /v1/{practiceid}/chart/{patientid}/socialhistory/templates 
  • Change: No change in structure. Global social history templates can no longer be assigned to a patient’s chart using this API. Global social history questions can be configured using the New Social History admin page.
  • Update to code: No

Patient Social History 

  • Endpoints:
    • GET /v1/{practiceid}/chart/{patientid}/socialhistory 
    • PUT /v1/{practiceid}/chart/{patientid}/socialhistory 
  • Change: The main goal of the New Social History Experience is to allow Athenahealth to update Social History Content (Templates / Questions). 
    • Structure of output remains the same 
    • questiontext, questionkeys, templates, templateid, ordering, questionid fields' values may change more frequently in the new system as new content is rolled out 
    • questionid is being deprecated 
    • templateid may not be unique 
  • Breaking Change:
    •  socialhistorystatus was deprecated, it is now being removed as an output parameter from GET /chart/{patientid}/socialhistory
  • Validation of input: 
    • We will accept invalid answers to input types (dropdown, numeric, yes/no and date). These invalid answers will be flagged in the chart with the recommendation that the user select a valid answer option. For example:
    • We will reject free text answers exceeding 4000 characters. 
    • We will reject invalid question keys that are not defined in our system. Note: As in the previous experience, no error response will be sent when an invalid question key is submitted. 
  • Updates to code 
    • questiontext, questionkeys, templates can be added at any time. Code defensively, expecting that a question could be added or removed at any point 
    • Questionid is being deprecated. Partners should rely on the value of questionkey instead of questionid to uniquely identify a question. The questionid field will still be returned, but the value can change over time.  In a future release, the questionid field can be removed (as with any deprecated field) 
    • Partners can no longer rely on socialhistorystatus 
    • If partners rely on the value of templateid and encounter issues with the ID not being unique, they need to update the code because this value may not be unique and may change in the new release 
    • Users will need to remove the invalid data causing the PUT request to rejected. In the error response, they can see which field is causing the error and whether it is an invalid type or an invalid value or an invalid question key 
  • What will happen if you do not update code  
    • The value of questionid for the same question can change at any time 
    • any code that expects socialhistorystatus will throw an error 
    • PUT Requests with invalid questions or answers will be rejected with an error and until the invalid data is removed, socialhistory answers can’t be saved 

Health History Forms

  • Endpoints:
    • GET /appointments/{appointmentid}/healthhistoryforms/{formid} 
    • PUT /appointments/{appointmentid}/healthhistoryforms 
  • Change: The structure of the endpoints remains the same, but questions are changing.
  • Update to code: No action needed unless questions are hard-coded and need to be updated.
  • Validation of Input:
    • We will reject requests with invalid question keys/clinical element id’s that are not defined in our system.  
    • We will reject requests with invalid dropdown answer options, invalid Yes /No answer options and free text answers exceeding 4000 characters. 
    • We will accept invalid numeric and date answers. These invalid numeric and date answers will be flagged in the chart with the recommendation that the user enter a valid answer. For example:

Recommendations for users that save the health history forms output in their own system

Before the New Social History Experience is Enabled

  1. Continue using your old workflows to GET and PUT the healthhistoryforms API. 
  2. Store the output of the GET to the healthhistoryforms somewhere in case you need to reference it as the numeric identifiers will change once the new experience is enabled. 

After the New Social History Experience is enabled for a particular client / context

  1. OPTION: in case you can't get the new GET output soon after the client joins the beta / enables the new experience, you can still PUT the JSON you used in the old experience temporarily while you switch over to the new content. 
  2. Run a GET the on the "healthhistoryforms" endpoint to get the new JSON that represents the questions configured on the Health History Forms. When the new experience is enabled, the clinicalelementid will map from questions that exist in both the old social history experience and the new social history experience for any global questions, for example SOCIALHISTORY.SMOKINGSTATUS.
    Note: numeric id's such as portalformquestionid and portalformsectionid may change and should not be relied up for mapping questions to answers, or mapping questions from the old experience to the new experience. 
  3. Using the output of the GET, do a PUT with the answers filled in. 
Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others

On this Page