Overview

The API has been developed to meet the following measures:

  • §170.315(g)(7) Application access - patient selection
  • §170.315(g)(9) Application access - all data request
Terms of Use

Acceptance of Terms of Use is a precondition for the use of API.

Authorization

Users will be able to access health information of patients after successful authorization following a series of steps mentioned in this document below. The authorization process is simple and aimed at ensuring that patient’s health information is only accessible to intended users.

To initiate authorization, users will sign up by providing registration details on https://developer.ethizo.com/signup.

Once registered, they will logon to the developer portal at https://developer.ethizo.com/login to start using the API.

To be able to obtain clinical data for a patient, users will proceed to create an access request for patient's practice.

Once a request has been created it will be sent to the respective practice administrator for approval. Users will be able to view their requests. The status of requests will be pending until they are approved or denied.

Practice administrators only authorize requests for which they have received confirmation from patients. A client_id and client_secret will be granted to all approved requests. Users will be able to view the client_id and client_secret in their request details on the developer portal. They will use these in the next authorization step to obtain the practice access token.

Endpoints

The second step of the authorization process involves obtaining a practice_access_token. Users will be required to provide the client_id, client_secret and response type in the request in the format specified below.

Practice Access Token

GET

Request Parameters
Parameter Required Type Instruction
client_id Required String The value of Client ID received in the approved request on Ethizo developer portal
client_secret Required String The value of Client Secret received in the approved request on Ethizo developer portal
response_type Required String ‘practice_access_token’ would be passed when requesting a new practice access token. When requesting a access token after the original practice access token expires, users will pass ‘refresh token’
Sample Request

https://api.ethizo.com/developer_apis/practice_access_token.json?client_id={client_id}&client_secret={client_secret}&response_type=practice_accesss_token

Response Parameters
Parameter Type Length Instruction
practice_access_token Required 256 characters The practice access token will be used in making calls to the patient_search method
expires_in Integer 2 digits The duration in days after which the practice_access_token expires
refresh_token String 256 characters The refresh_token will be used to obtain a new practice_access_token after the original token expires
Sample Response
                                      
                                        {
                                          "response":  {
                                            "practice_access_token": "089c45529cb242f48488cb8f0f33fd92", 
                                            "expires_in": 30,
                                            "refresh_token": “2651g35df351351gd692392689dfghd92”
                                          }
                                        }
Requesting Refresh Token after practice_access_token expires

GET

Request Parameters
Parameter Required Type Instruction
response_type Required String ‘refresh_token’ will be passed when request a new practice_access_token using a refresh_token
refresh_token Required String The value of refresh_token
Sample Request

https://api.ethizo.com/developer_apis/practice_access_token/?response_type=refresh_token&refresh_token ={refresh_token}

Response Parameters
Parameter Type Length Instruction
practice_access_token String 256 characters The new practice access token
expires_in Integer 2 digits The duration in days after which the practice_access_token expires
refresh_token String 256 characters The refresh_token will be used to obtain a new practice_access_token after the original token expires
Sample Response
                                      
                                        {
                                          "response": {
                                            "practice_access_token": "089c45529cb242f48488cb8f0f33fd92", 
                                            "expires_in": 30,
                                            "refresh_token": “2651g35df351351gd692392689dfghd92”
                                          } 
                                        }

Once authorized, users will be required to search for a patient whose data they require. Users will be expected to provide information about all required parameters in the request. In case the patient is searched successfully, system will return a search token to be used in subsequent calls to other methods.

GET

Request Parameters
Parameter Required Type Instruction
practice_access_token Required String Practice access token received in previous step
first_name Required String Patient’s first name
last_name Required String Patient’s last name
dob Required Date The only acceptable format is YYYY-MM-DD
gender Required String System only recognizes the values ‘male’, ‘female’ and ‘unknown’
address_line_1 Optional String Address line 1 of the patient’s address
address_line_2 Optional String Address line 2 of the patient’s address
city Optional String The City recorded as part of the patient’s address
state Optional String Patient’s last name
zip Optional String Zip codes of patient’s address
email Optional String Current email address of the patient
Sample Request

https://api.ethizo.com/developer_apis/search_patient/?practice_access_token={access_token} &first_name={patient first name}&last_name={patient last name}&dob=1960-01-01&gender=male

Response Parameters
Parameter Type Length Instruction
msg String 256 characters It displays information of whether the system was able to successfully search patient against the request or not.
data String
search_token String 256 characters This will be provided against the search request. It will be unique for every patient searched and will be used in subsequent calls of other methods of the API.
patient_name String 256 characters Full name of the Patient
Sample Response
                                        
                                            {
                                              "response": {
                                                "msg": "Patient Retrieved", 
                                                "data": [
                                                  {
                                                    "uuid": "089c45529cb242f48488cb8f0f33fd92", 
                                                    "patient_name": "Mr. John Doe"
                                                  } 
                                                ]
                                              } 
                                            }

After patient search has been successfully performed, users will select if they want to obtain patient’s data category wise or in entirety. The method data_category_request returns category wise patient data in JSON. The request to this method requires the search token obtained from patient_search method

Specific Data Category Request

GET

Request Parameters
Parameter Required Type Instruction
practice_access_token Required String Practice authorization token received in the first step. Users will need to get a new practice_access_token after 30 days. They will be able to generate the new token from the Ethizo API developer portal.
search_token Required String The token received from patient_search function.
start_date Optional Date Start date from which the data is to be requested. Supported format for date is YYYY- MM-DD
end_date Optional Date End date till which the data is being requested. Supported format for date is YYYY-MM-DD
components Required String Users will specify the categories whose information they want to obtain. Multiple categories will be comma separated. Users will be able to select from the following list of categories:
  • patientname
  • dateofbirth
  • ethnicity
  • preferredlanguage
  • problems
  • medications
  • allergies
  • orders
  • results
  • vitalsigns
  • procedures
  • careteammembers
  • medicalequipment
  • planoftreatment
  • goals
  • healthconcerns
  • sex
  • race
  • socialhistory
  • immunizations
  • assessments
Sample Request

https://api-prepod.ethizo.com/cda/data_category_request.json?uuid=d7af0943c0fc467aa9449ee42ac7b43b&start _date=2017-01-01&end_date=2020-05- 01&practice_access_token=29bca596fb9b2e4475f56b31bca4e289&components=PatientName

Sample Response
                                        
                                            {
                                              "Header": {
                                                "Patient": { 
                                                  "Demographics":  {
                                                      "FirstName": "John", "LastName": "Doe", "MiddleName": "", "DOB": "","Sex": "", "Race": null, "Ethnicity": null, "Language": ""
                                                    } 
                                                  }
                                              } 
                                            }
All Data Request

This method allows users to obtain all data of the patient in a CCDA file. Users will provide the search token they obtained from patient_search method along with other required parameters mentioned below.

GET

Request Parameters
Parameter Required Type Instruction
practice_access_token Required String Practice authorization token received in the first step.
search_token Required String The token received from patient_search function.
start_date Optional Date Start date from which the data is to be requested. Supported format for date is YYYY- MM-DD
end_date Optional Date End date till which the data is being requested. Supported format for date is YYYY-MM-DD
Sample Request

https://api-prepod.ethizo.com/cda/data_category_request_all.json?uuid=d7af0943c0fc467aa9449ee42ac7b43b&start_date=2017-01-01&end_date=2020-05-01&practice_access_token=29bca596fb9b2e4475f56b31bca4e289

Sample Response

HTTP Response Codes

Code Description Reason
200 Suceess The request was successfully processed.
300 Multiple Match Error More than one patient corresponds to the search criterion entered. Users will be asked to use additional search filers to search their unique patient.
404 Patient not found No patient matched the search criterion in the request.
500 Internal Server Error An error occurred while processing the request. If this error is observed continuously, users are requested to contact the support team at support@ethizo.com.
400 Bad Request Server was not able to process the request. This is usually due to problems with request format, structure or parameters.
422 Invalid Request The request is incomplete.
401 Unauthorized request Users is not authorized to make this request.