API Documentation
Access VieCure's API Terms of Use here.
Introduction
In this documentation, we will list all the steps required to access protected health information based on the documentation of an open API.
Note: Patient data used in this document is test data and doesn’t contain any PHI.
Client Configurations
-
IMPORTANT: Local customer security policies must be in place to prevent unauthorized monitoring or eavesdropping of connections to the server.
-
The server is accessed by clients through an HTTPS connection.
-
Only SSL/TLS connections (TLS 1.0 or higher) are accepted. All plaintext connections will be refused.
-
Please limit your connection frequency to a value appropriate for your use case. Connection attempts that are more frequent than permitted by the bandwidth allocation for the data resource are not allowed.
-
Client authentication can be performed using a username and a strong password. A healthcare organization has to reuse existing patient portal credentials for this purpose, in which case the authenticated username map to a unique patient portal user on the resource holder’s side.
-
As a part of the policy, patient portal credentials will be provided to patients during encounters.
-
Client software must be capable of making HTTPS RESTful requests
-
Apart from the above configurations, there is no other software required on the client-side.
Reference
Validate user and get access token
POST
This API is used to validate the user and in return will give an access token along with other parameters. This access token will be used for all future API calls.
Input here username and password in the body part.
The value for input parameter 'grant_type' will remain fixed as 'password'. Please do not change this.
Search Patient
POST
This API is used to search for a patient. In return, it will give a list of patients with its basic demographics.
The access token received in the previous API call should be used here. As can be seen in the headers section here, one needs to pass the access token in the header. So search patient is mandatory to get patient id because patient id and access token will be required for all subsequent calls to get patient data.
Input here is in JSON format as can be seen in the body section. Observe carefully here, that the entire JSON input parameter is sent with a blank name before '='.
Get Patient Encounters
POST
This API is used to get encounters for a patient. In return, it will give a list of encounters.
The access token received in the previous API call should be used here. As can be seen in the headers section here, one needs to pass the access token in the header.
Input here is in JSON format as can be seen in the body section. Observe carefully here, that the entire JSON input parameter is sent with a blank name before '='.
Returnformat will be blank always in this call.
Ccdafromdatetime and ccdatodatetime parameters will be used to filter encounters based on encounter date.
Fetch Patient Data
POST
This API is used to get data for a patient.
The access token needs to be sent in this API call as well. As can be seen in the headers section here, one needs to pass the access token in the header.
The other input here is in JSON format as can be seen in the body section. The section that needs to be brought is sent with a 'true' value. Date filter is also sent as an input. CCDA will be fetched for the patient id and encounter id that is sent in the input. Observe carefully here, that the entire JSON input parameter is sent with a blank name before '='.
The response here will be patient data in XML format. Please send "returnformat": "xml” always.
Fetch Patient Data (Specific Category)
POST
This API is used to get data for a patient. The access token needs to be sent in this API call as well. As can be seen in the headers section here, one needs to pass the access token in the header.
The other input here is in JSON format as can be seen in the body section. The section that needs to be brought is sent with a 'true' value. Date filter is also sent as an input. The date filter will be applicable only at the encounter level. Data will be fetched in XML format for the patient id and encounter id that is sent in the input and only for the section requested. Observe carefully here, that the entire JSON input parameter is sent with a blank name before '='.
The response here will be only patient data sections in XML format. The XML format will be similar to CCDA but there will not be extra data apart from the requested segment.
CCDA header with only specific sections requested or snippet of the XML containing only the specific section(s) requested will be returned.
Additional information for the Data Elements used to represent each data category can be found with the search parameter are mentioned below:
All values are options. If you do not give any parameter, it will return a complete record.
Error Handling
API Server handles the Errors & have valid Exception methods that provide an HTTP status code and Meaningful messages in JSON format.
Unauthorized HTTP response Code - 401
-
If the access token used in the request is invalid, expired, or the user has not been authorized to access the requested Resource, the API will return a 401 Unauthorized HTTP response.
Forbidden Request - HTTP Status Code - 403
-
A user trying to access another user's profile or data will be returned with a Forbidden Request Error.
-
The JSON response is returned from the Server for the forbidden request
Bad Request - HTTP Status Code - 400
-
An invalid or a bad URL request to the server is returned with an HTTP - 400 response and message
-
The JSON response is returned from the Server for the forbidden request
Response OK - HTTP Status Code - 200
-
A valid request to the server is returned with an HTTP - 200 response and message
-
The JSON response is returned from the Server for the forbidden request