Secure Patient Portal

Docutap 6.4 API Documentation

Explanation

This REST api can be access via any RESTful client (aka Postman) or programming language that supports REST, TLS 1.2, and Basic Authentication. Credentials for the API are the patient's same credentials used to access the Secure Patient Portal. To use the API the first call should be made to the affiliations endpoint to get the list of organizations the patient is affiliated with. Each organization represents a single or group of clinic locations that are owned by a single entity. We support many organization and a patient can be affiliated with one to many of these organization depending on where they have had been seen. Subsequent calls to the API endpoint (ccda or ccda-search) require the organization id to be included and will return results from that organization for the patient. If information is needed for all organizations a separate call will need to be made with each organization id that the patient is affiliated with.

Organization Affiliations

  • HTTPS GET
  • https://www.healthdataexchange.com/api/affiliations
  • Use Basic Authentication with username and password to generate the Authorization Header
  • Get back JSON with the name(s) and ID number(s) of associated organizations.
  • Example response: 
                {
                "Organizations": [
                    {
                        "Name": "TestUser",
                        "Id": 1
                    }
                ]
            }

Retrieve CCDA XML document

  • HTTPS POST
  • https://www.healthdataexchange.com/api/ccda
  • Use Basic Authentication with username and password to generate the Authorization Header
  • Send a JSON request body
  • Get back a single XML CCDA for the most recent completed visit.

Retrieve all CCDA XML documents within a date range.

  • HTTPS POST
  • https://www.healthdataexchange.com/api/ccda-search
  • Use Basic Authentication with username and password to generate the Authorization Header
  • Send a JSON request body
  • Get back XMLstring formatted CCDAs embeded in a JSON list.
    Example result with data that's been found: 
    {
  "results": [
    {
      "date": "05/05/18",
      "visitId": "1676298",
      "status": "Completed",
      "ccd": "<?xml version=\"1.0\" ?>\n<ClinicalDocument ...=... </ClinicalDocument>"
    },
    {
      "date": "02/18/18",
      "visitId": "1499963",
      "status": "Closed",
      "ccd": "<?xml version=\"1.0\" ?>\n<ClinicalDocument ...=... </ClinicalDocument>"
    }
  ]
}
    Example result with no data found: 
    {
  "results": []
}

Sending a JSON Request Body

  • OrganizationId (integer, required field.)
  • Version (integer, optional field.)
    Default value: 2
    Only value of 1 or 2 is accepted. If the version is not valid, you will recieve an Bad Request error.
  • DateFrom (string, optional field.)
    Default value: 01/01/0001
    Must be in the format of MM/DD/YYYY. Only used by ccda-search endpoint. Ignored by the ccda endpoint.
  • DateTo (string, optional field.)
    Default value: Today's date.
    Must be in the format of MM/DD/YYYY. Only used by ccda-search endpoint. Ignored by the ccda endpoint.
  • SecurityCode: (string, optional field, case insensitive.) Default value: N
    Valid SecurityCodes:
    • N = Normal
    • R = Restricted
    • V = Very Restricted
    Version 1 does not support this property, and will cause a Bad Request error if present. If the code isn't valid, you will recieve a Bad Request error.
  • SecurityText (string, optional field.)
    The default value is no text. Version 1 does not support this property, and will cause a Bad Request error if present. This is the text field in the security section. Only used if the SecurityCode is R or V.
  • ListOfSections (list of strings, optional field, case insensitve.) Default value: All sections.
    Valid Section Names:
    • assessment
    • cognitive-status
    • consultation-note
    • discharge-summary-note
    • encounter-diagnosis
    • evaluations-and-outcomes
    • family-health-history
    • functional-status
    • future-appointments
    • future-scheduled-tests
    • goals
    • health-concerns
    • history-&-physical
    • imaging-narrative
    • immunizations
    • interventions
    • lab-tests-and-results
    • laboratory-report-narrative
    • med-allergies
    • med-list
    • medical-equipment
    • pathology-report-narrative
    • patient-education
    • payers
    • pending-diagnostic-tests
    • problems
    • procedure-note
    • procedures
    • progress-note
    • referral
    • social-history
    • vitals
    Version 1 does not support this property, and will cause a Bad Request error if present. If a section is not valid, you will recieve a Bad Request error.
    Note on the List of Sections:
    • The Plan of Treatment section in the CCD doesn't have the name 'plan-of-treatment' mapped to it in the body parameter. Instead, if any combination of the following section names are sent in the sections body parameter, the Plan of Treatment section will be generated exactly once. Otherwise, the Plan of Treatment section won't be generated.
      • future-appointments
      • future-scheduled-tests
      • pending-diagnostic-tests
      • patient-education
  • Template (string, optional field, case insensitive.)
    Default value: Clinical-Summary. Valid Template Names:
    • care-plan
    • clinical-summary
    • transition-of-care/referral
    Version 1 does not support this property, and will cause a Bad Request error if present.
    If the template name is not valid, you will recieve a Bad Request error.
  • Example request using all optional fields: 
                    {
                    "OrganizationId": 9001,
                    "Version": 2,
                    "DateFrom": "12/01/1970",
                    "DateTo": "01/01/2019",
                    "SecurityCode": "R",
                    "SecurityText": "This is the security text box.",
                    "Template": "Care-PlaN",
                    "ListOfSections": [
                        "VitalS",
                        "future-scheDuLed-tests"
                    ]
                }

Errors:

There are several possible responses you can get from the API in the case of an error. Some examples include:
Error CodeCause
-1 - Request Failed This code will occur if the server address is incorrect and does not correspond with a valid DNS lookup.
404 - Not Found This code will occur if the server address is incorrect but does correspond to a valid DNS lookup. The response body will vary depending on which server actually is contacted.
504 - Gateway Timeout This code will occur if the incorrect protocol is used (http vs https). The response body will vary depending on the application used to interface with the server.
400 - Bad Request This code will occur if the JSON request is properly formed but has invalid values (such as the Security Code value being “T”, the Template is misspelled, or a section name is misspelled).
500 - Internal Server Error This code will occur along with the basic html error page in the response body for bad credentials, malformed JSON, and bad Organization ID.
200 - OK This code will occur along with the basic html error page in the response body if the server address is correct but using an invalid path or the wrong request method is used (GET vs POST vs OPTIONS, etc).

Terms of Use

Page Last Updated: 04/20/2020