API Technical Details

The API that is being documented here is designed to securely facilitate the patient authentication and the sharing of patient data via a Continuity of Care Document (CCD). eMDs client's, the Practice/Clinic, will supply vendor systems with the necessary access tokens for checking API accessibility status for the practice, validate patient through credential authentication and retrieve the patient CCD based on patient elections for expiration, CCD category and/or date range.

Prerequsites: The vendor system will need both a Practice token and an API token provided by the Practice. Once you have these two tokens (provided by the Practice/Clinic) you will be able to experiment with the following web methods.

Please review the Introduction if you have not yet done so.

System Status Check

Checks the status of the API suite. This web method can be used to provide basic validation that you have active tokens and to verify communication channels.

Request

Parameter Type Value Description
practice_token String REQUIRED: the unique identifying token given to the Practice
api_token String REQUIRED: the token that autorizes the Practice to perform work in the API

Response

HTTP Code Response Response Fields Sample JSON Result
200 API is Running, Everything checked out.
  • status: The status indicator. A string.
 {"status":
"running"}
400 Error checking API status.
  • errors: Error text. A string.
 {"errors":
"Required parameters have not been provided.
Please refer to API documentation."}

Portal Status Check

Checks the status of the Portal based on tokens provided.

This web method is similar to the System Status Check. It validates tokens and can be used to confirm connectivity. But it also confirms connectivity to the Patient Portal software.

Request

Parameter Type Value Description
practice_token String REQUIRED: the unique identifying token given to the Practice
api_token String REQUIRED: the token that autorizes the Practice to perform work in the API

Response

HTTP Code Response Response Fields Sample JSON Result
200 API is Running, Everything checked out.
  • status: The status indicator. A string.
 {"status":
"running"}
400 Error checking API status.
  • errors: Error text. A string.
 {"errors":
"Required parameters have not been provided.
Please refer to API documentation."}

For Patient Authentication, the vendor system will call the API method for Patient Authentication and be returned a url that will allow the vendor system to present a webpage for the patient to use for login. This form will allow the patient to enter private Patient Portal credentials as well as set data access parameters for expiration, date range and CCD categories. Once validated, the vendor system can proceed with the resulted patient request token and call the CCD retrieval method.

The "app_name" and "app_desc" fields have two uses: Firstly, they are shown to the Patient on the authorization page. It gives the Patient a confirmation of the system with which they want to share their private data. These fields are also used for audit purposes in the API.

Once the patient has completed their authorization form, they can optionally be redirected back to system that is the source of the request. The "return_link_name" and "return_url" can be used to specify the return trip.

Request

Parameter Type Value Description
practice_token String REQUIRED: the unique identifying token given to the Practice
api_token String REQUIRED: the unique token given to the Practice to perform work in the API
app_name String REQUIRED: the common name of the application making the request.
app_desc String REQUIRED: a brief description of the application making the request
return_link_name String Optional: the return link name
return_url String Optional: the return url

Response

HTTP Code Response Response Fields Sample JSON Result
200 API is Running, Everything checked out.
  • status: The status indicator. A string.
  • token: The request token. A string.
  • url: The URL for Patient Authorization. A string.
 {"status":"Success",
"token":"REQUEST_TOKEN",
"url":
"http://api.emds.com/api/v1/patients/authenticate?
practice_token=PRACTICE_TOKEN&
api_token=API_TOKEN&
request_token=REQUEST_TOKEN"}
400 Error, Missing Tokens.
  • errors: Error text. A string.
 {"errors":
"Required parameters have not been provided.
Please refer to API documentation."}
400 Error, Missing parameters.
  • status: Failure message. A string.
  • errors: Error list. A list of errors.
 {"status": "Failed",
"errors":
{"external_system_name":
["can't be blank",
"is too short (minimum is 2 characters)"],
"external_system_description":
["can't be blank",
"is too short (minimum is 2 characters)"]}}

For CCD Retrieval, the vendor system will call the API method for retrieving the CCD. Access will be granted with the Practice, API and Request tokens. The CCD will be transformed to comply with patient elections as previously discussed.

Request

Parameter Type Value Description
practice_token String REQUIRED: the unique identifying token given to the Practice
api_token String REQUIRED: the unique token given to the Practice to perform work in the API
request_token String REQUIRED: the unique token that identifies an authorization

Response

HTTP Code Response Response Fields Sample JSON Result
200 Full or partial CCD returned.
  • ccd: The Patient's CCD document. An XML string.
 {"ccd":
"\u003c?xml version=\"1.0\"...
400 Error, Missing Tokens.
  • errors: Error text. A string.
 {"errors":
"Required parameters have not been provided.
Please refer to API documentation."}
400 Error, Missing Request Token.
  • errors: Error list. A list of errors.
 {"errors":
["A valid request token is required"]}
400 Error, Missing Authorization.
  • errors: Error list. A list of errors.
 {"errors":
["The Request has not been authorized"]}
Loading…