API Documentation


Introduction


The Synaptec Health API is REST based with resource-oriented URLs. It accepts and returns JSON-encoded responses, and uses standard HTTP response codes. HTTPS / TLS 1.2 is enforced for HIPAA compliance.


Base API URL:

https://api.synaptechealth.com/

Authentication


The Synaptec Health API uses API keys to authenticate requests. Get your API keys from your engineering contact.


Your API key must be provided in the Request Header as x-api-key and all API requests must be made over HTTPS and require authentication.


Your API keys carry many privileges, so be sure to keep them secure! Do not share your API keys in publicly accessible areas such as GitHub, client-side code, and so forth.


Authenticated Request Example:

curl --header "x-api-key: <your_api_key>"
--header "content-type: application/json" "https://api.synaptechealth.com/v1/hello"

Data Formats


The Synaptec Health API uses JSON formatted text with UTF-8 encoding. When making a request, be sure to specify the correct content-type in the Request Header, which is application/json.


Authenticated Request Example with Content Type:

curl --header "x-api-key: <your_api_key>"
--header "content-type: application/json" "https://api.synaptechealth.com/v1/hello"

Response Codes and Errors


Synaptec Health uses conventional HTTP response codes to indicate the success or failure of a request.


Response Code Types:

200 - Success.
400 - Unacceptable request due to missing required parameter.
403 - Permission denied. Verify your API key and endpoint URL.
409 - Unable to process. Verify a valid encounterID was provided.
429 - Rate limit exceeded. Suggest exponential request backoff.
5xx - Synaptec Health server error. Contact support.

Encounter Resources


Encounter resources allow you to create and update encounters.


Base Encounter URL:

https://api.synaptechealth.com/v1/encounter/:encounterID

The Encounter Data Model


Fields should be provided as UTF-8 formatted text. Our NLP engine reads each field exactly as human medical coders do today.


Each customer may use and map fields differently. Synaptec Health can create new fields for customer-specific EHR's and maintains a per-customer mapping between custom fields and our internal models.


Templated data is also supported. You can provide sample data to your engineering contact and they can help find the right fields.


{
   "encounter_id":string,
   "chief_complaint":{
      "chief_complaint":string,
      "reason_for_referral":string
   },
   "history_of_present_illness":{
      "history_of_present_illness":string,
      "reason_for_visit":string,
      "subjective":string
   },
   "past_medical_family_social_history":{
      "allergy":string,
      "immunization":string,
      "problems":string,
      "family":string,
      "social":string,
      "medical_equipment":string,
      "medications":string,
      "other":string
   },
   "review_of_systems":string,
   "physical_exam":{
      "vitals":string,
      "physical_exam":string
   },
   "medical_decision_making":{
      "assessment":string,
      "differential_diagnosis":string,
      "results":string,
      "medications_administered":string,
      "procedures":string,
      "interventions":string,
      "diagnosis_codes":string
   },
   "discharge_instructions":string,
   "physician_signature_token":string
}

Creating and Updating an Encounter


Patient encounters are populated with a POST request to the Encounter Endpoint with at least one encounter model data field provided in the Request Body.


Patient encounters can be populated asynchronously and data fields can be updated multiple times as the documentation is updated by practitioners.


An encounter ID must be provided as a Path Variable for each request. Providing a previously seen encounter ID will add new or update existing fields of a previously stored encounter.


Create New Encounter Example:

curl --header "x-api-key: <your_api_key>" 
--header "content-type: application/json" 
-X POST
--data '{"chief_complaint":{"chief_complaint":"cough with chest pain"}}'
"https://api.synaptechealth.com/v1/encounter/<encounter_id>"

Response Format Example:

HTTP/1.1 200 OK

{}

Documentation Analysis Resources


Documentation Analysis resources provide feedback on available documentation for a patient encounter prior to the coding of a chart. This feedback can be used to update inadequate or provide missing documentation prior to coding and billing.


Base Documentation Analysis URLs:

https://api.synaptechealth.com/v1/documentation/all
https://api.synaptechealth.com/v1/documentation/history
https://api.synaptechealth.com/v1/documentation/pe
https://api.synaptechealth.com/v1/documentation/mdm


The Documentation Analysis Data Models


Currently the history documentation analysis is available in production.


The history model indicates which additional elements from the HPI, PFSH or ROS were identified and how many more elements are required to achieve the desired or highest billing level of 99285 or critical care. This model will also identify if a qualifying alternative statement was found that would allow a chart to support the highest billing level regardless of the number of identified elements.


History Documentation Analysis Data Model:

{
   "hpi":{
      "element_count":integer,
      "elements_found":{
         "location":boolean,
         "quality":boolean,
         "severity":boolean,
         "duration":boolean,
         "timing":boolean,
         "context":boolean,
         "modifying_factors":boolean,
         "associated_signs_symptoms":boolean
      },
      "elements_required_for":{
         "99281":integer,
         "99282":integer,
         "99283":integer,
         "99284":integer,
         "99285":integer
      },
      "supports_critical_care":boolean,
      "unatainable_qualifying_statement_alternative":boolean,
      "discuss_other_conditions_alternative":boolean
   },
   "pfsh":{
      "element_count":integer,
      "elements_found":{
         "past_medical_history":boolean,
         "social_history":boolean,
         "family_history":boolean
      },
      "elements_required_for":{
         "99281":integer,
         "99282":integer,
         "99283":integer,
         "99284":integer,
         "99285":integer
      },
      "supports_critical_care":boolean,
      "unatainable_qualifying_statement_alternative":boolean,
      "reviewed_confirmed_statement_alternative":boolean
   },
   "ros":{
      "element_count":integer,
      "elements_found":{
         "constitutional":boolean,
         "eyes":boolean,
         "enmt":boolean,
         "cardiovascular":boolean,
         "respiratory":boolean,
         "gastrointestinal":boolean,
         "genitourinary":boolean,
         "musculoskeletal":boolean,
         "integumentary_breast":boolean,
         "neurological":boolean,
         "psychiatric":boolean,
         "endocrine":boolean,
         "hematologic_lymphatic":boolean,
         "allergic_immunologic":boolean
      },
      "elements_required_for":{
         "99281":integer,
         "99282":integer,
         "99283":integer,
         "99284":integer,
         "99285":integer
      },
      "supports_critical_care":boolean,
      "unatainable_qualifying_statement_alternative":boolean,
      "reviewed_confirmed_statement_alternative":boolean
   }
}

Example


The following end-to-end example demonstrates what to expect from the API for a sample HPI section of an encounter.


HPI Example from Physician:

Pt is a 62 y/o male arriving via ALS presenting with slurred speech x 1.5 hrs. Pts sister states the pt was in his usual state of health, walking through the kitchen when he started to slur his words, lost his balance and hit his head on the counter top. + LOC of <2 mins. Pt notes mild HA over same duration but denies vision changes. Denies focal numbness or weakness of the extremities. No seizure like activity noted. EMS notes facial droop and decreased coordination which progressed en route. No airway compromise noted. Pt having difficulty following commands and was intermittently confused en route. Of note, per family pt fell 2 weeks ago while hiking hitting his head but w/o LOC. He was not seen by a doctor at that time. Pt has been acting normally since the event. No meds given by ems. Pt has hx of DM, HTN and prior MI with 2 stents. +2 PPD smoking, + IVDU use and +etoh use 1x per week.

API Call to Create Encounter:

curl --header "x-api-key: <your_api_key>" 
--header "content-type: application/json" 
-X POST
--data '{"history_of_present_illness":{"history_of_present_illness":"Pt is a 62 y/o male arriving via ALS presenting with slurred speech x 1.5 hrs. Pts sister states the pt was in his usual state of health, walking through the kitchen when he started to slur his words, lost his balance and hit his head on the counter top. + LOC of <2 mins. Pt notes mild HA over same duration but denies vision changes. Denies focal numbness or weakness of the extremities. No seizure like activity noted. EMS notes facial droop and decreased coordination which progressed en route. No airway compromise noted. Pt having difficulty following commands and was intermittently confused en route. Of note, per family pt fell 2 weeks ago while hiking hitting his head but w/o LOC. He was not seen by a doctor at that time. Pt has been acting normally since the event. No meds given by ems. Pt has hx of DM, HTN and prior MI with 2 stents. +2 PPD smoking, + IVDU use and +etoh use 1x per week."}}' "https://api.synaptechealth.com/v1/encounter/<encounter_id>"

Response:

HTTP/1.1 200 OK

{}

API Call to History Documentation Analysis API:

curl --header "x-api-key: <your_api_key>" 
--header "content-type: application/json"
"https://api.synaptechealth.com/v1/documentation/history/<encounter_id>"

Response:

HTTP/1.1 200 OK

{
   "hpi":{
      "element_count":8,
      "elements_found":{
         "location":true,
         "quality":true,
         "severity":true,
         "duration":true,
         "timing":true,
         "context":true,
         "modifying_factors":true,
         "associated_signs_symptoms":true
      },
      "elements_required_for":{
         "99281":0,
         "99282":0,
         "99283":0,
         "99284":0,
         "99285":0
      },
      "supports_critical_care":true,
      "unatainable_qualifying_statement_alternative":false,
      "discuss_other_conditions_alternative":false
   }
}