Introduction


This guide is for third party developers to enable patients to access their data from InPracSys.

It contains details about how a third party application can connect to InPracSys and give access to patients for requesting their data from InPracSys.

  • How to register third party application with InPracSys API.
  • How to request for patient data.
    • Request format
    • Request parameters
  • How the API will respond to data request
    • Response format
    • Response Sections
    • List of errors

The response for requested data will be in JSON format.(JSON) JavaScript Object Notation defines a set of "Resources" that represent granular clinical concepts.

The resources can be managed in isolation, or aggregated into complex documents. Technically, JSON is designed for the web; the resources are based on JSON structures, with an HTTP-based RESTful protocol where each resource has predictable URL. Wherever possible, open internet standards are used for data representation. JSON aims to simplify implementation without sacrificing information integrity. It leverages existing logical and theoretical models to provide a consistent, easy to implement, and rigorous mechanism for exchanging data between healthcare applications.

The following is a list of data categories in compliance with USCDI V1.

Data Element Data Category
Patient name patient
Sex patient
Date of birth patient
Race patient
Ethnicity patient
Preferred language patient
Encounters encounters
Smoking status smokingstatus
Problems problems
Medications medication
Medication allergies allergy
Laboratory test(s) laboratoryresults
Laboratory value(s)/result(s) laboratoryresults
Vital signs vitalsigns
Procedures procedure
Care team member(s) careteam
Immunizations immunization
Unique device identifier(s) for a patient's implantable device(s) device
Assessment assessment
Treatment Plan treatmentplan
Goals goal
Care plan careplan
Health concerns healthconcern

Registration


Register client with InPracSys API

Third party applications have to register at InPracSys API

The following details are required for registration :

  • Application Name
  • Company Name
  • Application URL
  • E-mail id
  • PracticeName

On successful authentication and registration with InPracSys API, an e-mail is sent to the registered e-mail address along with username, password and grant_type. This username, password and grant_type will be required to request patient data from InPracSys API

Authorization – OAUTH 2.0


Authorize

Authorizes client with passed username, password and grant_type and it will returns JSON data

JSON data contains a token, this process of granting access is known as client credentials grant type

Client Credentials

The Client Credentials grant type is used when the client is requesting access to protected resources under its control (i.e. there is no third party)

For e.g.

private Dictionary GetAccessToken()
                {
                Dictionary tokenDetails = null;
    
                using (HttpClient httpClient = new HttpClient())
                {
                    HttpContent content = new FormUrlEncodedContent(new[]
                    {
                        new KeyValuePair"username", username received in registration email),
    new KeyValuePair("password", password received in registration email),
        new KeyValuePair("grant_type","password")
            });


            httpClient.DefaultRequestHeaders.Add("Accept", "application/json");
            httpClient.DefaultRequestHeaders.Add("Accept-Language", "en-gb");
            httpClient.DefaultRequestHeaders.Add("Audience", "Any");

            
            resp.Wait(TimeSpan.FromSeconds(10));

            if (resp.IsCompleted)
            {
            if (resp.Result.Content.ReadAsStringAsync().Result.Contains("access_token"))
            {
            tokenDetails = JsonConvert.DeserializeObject>(resp.Result.Content.ReadAsStringAsync().Result);
                                    }
                            }
                        }
                            return tokenDetails;
                    }

The GetAccessToken returns a Dictionary from which we will get token for key "access_token"

URL

https://ipsemrapi.inpracsys.com/GetAccessToken

Method:

POST

Header Parameter

Accept: application/json
Accept-Language: en-gb
Audience: Any

Body Parameter

“username” = username received in registration email

“password” = password received in registration email

“grant_type” = password

Request format


Register to get started

Registration

Request Method: Post

Headers:

Accept: application/json
Accept-Language: en-gb
Content-Type: application/json
Authorization: "Bearer {accessToken}"

Authorization: This is the token generated from OAuth server

Request format:

Except for End Date, data for all other fields are mandatory

{

  "PracticeName": "InPracSys",

  "PatientMRN": "xaanDL234800",

  "PatientFirstName": "ALICE",

  "PatientLastName": "NEWMAN",

  "PatientDateOfBirth": "05/01/1970"

  "PatientSex": "Female"

  "StartDate": "09/01/2018",

  "EndDate": "09/01/2019",

}

Request parameters


PracticeName: This represents the InPracSys practice where the patient visited for medical treatment.

PatientMRN: This represents patient’s medical record number.

PatientFirstName: This represents patient’s first name.

PatientLastName: This represents patient’s last name.

PatientDateOfBirth: This represents patient’s date of birth.

PatientSex: This represents patient’s gender.

StartDate: This represents start date filter for patient’s health data. This field is mandatory in JSON request.

EndDate: This represents end date filter for patient’s health data. This field is not mandatory in JSON request. If only start date is specified then patient health data for that particular day would be returned by JSON server.

Value set for Sex information to be sent to JSON server
Male
Female

Response format


The response is in base64 encoded format. Developer can decode this response and get the CCD in xml format.

                        {
                          "ccda": "77u/PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjw/eG1sLXN0eWxlc2hlZXQgdHlwZT0ndGV4dC94c2wnIGhyZWY9J0NEQS54c2wnPz4NCjxDbGluaWNhbERvY3VtZW50IHhtbG"
                        }
                

List of exceptions and exception handling methods and messages.



Severity Exception
Content: 
{
message: "The user or system was not able to be authenticated"
}
Reason Invalid or empty client id or if there is no linkup with requested practice 
Severity Exception
Content: 
{
message: "Authorization has been denied for this request."
}
Reason Incase of invalid “token” 
Requested patient not found
Severity Exception
Content: 
{
message: "Patient not found"                                                          
}
Reason Incorrect PatientMRN, PatientFirstName, PatientLastName, PatientRace, PatientZip 
Severity Exception
Severity Exception
Content: 
{
message: "Missing input values."
}
Reason Null or Empty DataCategory or StartDate or PatientMRN or PatientFirstName or PatientLastName or PatientLastName or PatientRace or PatientZip
The request contains invalid data for Start Date or End Date
Severity Exception
Content: 
{ 
message: "The request contains invalid data for Start Date, End Date"
}
Reason Incorrect or invalid start date or end date or section requested
Start date should not be greater than end date
Severity Exception
Code: 
{
message: "Start date should not be greater than end date"
}
Reason If start date is greater than end date of the requested filters

Terms and Conditions



This Terms of Service (read 'License Agreement') details the terms and conditions in regard to the licensed use of InPracSys Health Application Programming Interface (“InPracSys Health API” or “API”) in the following topics:

  1. Developer License
  2. Deployment License
  3. Support Terms

The InPracSys Health API, software developer kit, documentation, and any software, materials or data and any new revisions or updates to the API that Innovative Practice Systems Inc. makes available to you, in its sole discretion, (collectively, the “InPracSys Health API Materials”) are made available subject solely to the terms and conditions of this Agreement.

Please read this Agreement in its entirety carefully, before either (i) accessing InPracSys Health API from an authorized web site, or (ii) developing an installed or web-based application using InPracSys Health API. By accessing or using the InPracSys Health API Materials, you acknowledge that you have read, and agree to abide by this Agreement. If you are unable to comply with this Agreement, you must immediately cease all use of the InPracSys Health API Materials.

  1. Developer License and Ownership

    InPracSys Health API is owned by Innovative Practice Systems Inc. and is copyrighted and licensed, not sold. As part of purchasing development license for each developer, Innovative Practice Systems Inc. grants you a non-exclusive, non-transferable license to use InPracSys Health API as part of your application development. Once your development license is purchased and established, you are authorized to use the InPracSys API Materials to develop products, sites, applications or services that are designed to interact with and enhance the InPracSys Health products and services (“Developer Applications”) subject to the restrictions, conditions and limitations in this Agreement. Sandbox environment will be provided for development purpose.

    This development license does not entitle you to any technical support or bug fixes or other maintenance services from Innovative Practice Systems Inc. If technical support or maintenance services, as described in Section 3, are desired, a development support license needs to be obtained from Innovative Practice Systems Inc.

  2. Deployment License

    You must obtain a Deployment License from Innovative Practice Systems Inc. for publishing an application that accesses InPracSys Health API as part of your application. The Deployment License grants you a worldwide, non-exclusive, non-transferable right to use and deploy an application that utilizes InPracSys Health API embedded as part of your Developer Applications. You need to present/showcase your application to Innovative Practice Systems Inc., for the deployment license to be granted.

    Display of Copyright Information: You must not remove any of the copyright information from the InPracSys Health API documentation.

  3. Development and Deployment Support

    During the development phase of your application, Innovative Practice Systems Inc. provides you the option of Deployment/Production Support services. The development and deployment license pricing terms will be outlined, which will also address any applicable fees for the support services

  4. Restrictions on Use

    You have no rights with respect to the API or any portion thereof and will not use the API or any portion thereof except as expressly permitted in this Agreement. Regardless of how the InPracSys Health API is being used and without limiting the generality of the foregoing, you will not

    • (i) reverse engineer, or otherwise attempt to determine source code of InPracSys Health API;
    • publish or provide any results of benchmark tests run on InPracSys Health API to a third party without prior written consent from Innovative Practice Systems Inc.
    • (iii) use the API in a manner that delays, impairs, or interferes with system functionality for others or that compromises the security or integrity of any data, equipment, software, or system input or output;
    • (iv) use or access the API for purposes of monitoring the availability, performance, or functionality of our services or for any other benchmarking or competitive purposes;
    • (v) modify or create derivative works of the API;
    • (vi) distribute the API as a stand-alone product;
    • (vii) reverse-assemble the API without the prior written consent of Innovative Practice Systems Inc.;
    • (viii) use the API to transmit illegal, obscene, threatening, libelous, harassing, or offensive messages, or otherwise unlawful material;
    • (ix) transmit, install or insert malicious code, malware, Trojans, viruses or other illicit code, program or software;
    • (x) abuse or misuse the API by gaining or attempting to gain unauthorized access to the API or other API user information;
    • (xi) alter or destroy information housed in the API in a manner that interferes with our or other users’ use of the API;
    • (xii) use the API in any manner that violates our policies, procedures or guidelines made available to you by us, your health care provider or authorized third-parties;
    • (xiii) circumvent any physical, administrative or technical security measures we have put in place to safeguard the API or interfere with the confidentiality, integrity or accessibility of any information housed therein, or any technical measures we have put in place to restrict access to the Services solely by authorized users;
    • (xiv) use the API in any manner or for any purpose that violates any law or regulation, any right of any person, including but not limited to Intellectual Property Rights, rights of privacy, or rights of personality, or in any manner inconsistent with this Agreement;
    • (xv) sell, lease, share, transfer, or sublicense the API or access or access codes thereto or derive income from the use or provision of the API, whether for direct commercial or monetary gain or otherwise, without Innovative Practice Systems Inc.’s prior, express, written permission;
    • (xvi) use the API in a manner that exceeds reasonable request volume, constitutes excessive or abusive usage, or otherwise fails to comply or is inconsistent with any part of the API documentation provided to you in connection with this Agreement;
    • (xvii) use the API in a product or service that competes with products or services offered by Innovative Practice Systems Inc.;
    • (xviii) use the API to develop for commercial distribution software products that compete with or substantially replicate InPracSys Health API or InPracSys Health products
    • (xix) maintain a cache or store using any kind of storage of any set or subset of data accessed using the API;
    • (xx) cause, assist or permit any third party to do any of the foregoing.

      Innovative Practice Systems Inc. reserves the right to restrict, stop or deny your access to our API server in case of suspicion of malicious activity or excessive load as in the case of security attacks or similar threats or when InPracSys, Inc. reasonably perceive that your use of the API competes directly with any of Innovative Practice Systems Inc. products and/or services. We will inform you of such action as soon as reasonably possible by email and/or phone. InPracSys Inc may also reasonably limit the number of daily API queries that may be submitted by You, the Developer Application, or Developer Site.


  5. Confidentiality and Authentication

    You may be given access to certain information, data, materials, know-how, methodologies, documentation, and software relating to the InPracSys Health API Materials that is not generally known by the public (“Confidential Information”), which is confidential and proprietary to Medical Mine Inc. You agree to use the Confidential Information only for the purpose of using the InPracSys Health API Materials in accordance with this Agreement, and you agree to not disclose any of the Confidential Information to any third party without Innovative Practice Systems Inc.’s prior written consent. You agree to protect the Confidential Information in the same manner that you would protect your own confidential and proprietary information but in no event using less than a reasonable degree of care.

    You are solely responsible for maintaining the confidentiality of your user name, password, API access token, and for restricting access to your computer, and you agree to accept responsibility for all activities that occur under your credentials. You may not assign or otherwise transfer your account information to any other person or entity, except your legally authorized representative if you are acting in an individual capacity. You acknowledge that we are not responsible for third party access to your account that results from theft, misuse, misappropriation of your credentials or your negligence. You agree that your access to or use of the API, or certain features or functionality of the API, may require our verification of your identity and credentials for and to your ongoing eligibility as an authorized API user. You agree that we may use and disclose your personal information you supply to us for such purposes, including without limitation making inquiry of third parties concerning your identity and eligibility. You authorize such third parties to disclose to us such information as we may request for such purposes, and you agree to hold them and us harmless from any claim or liability arising from the request for or disclosure of such information. You agree that we may terminate or suspend your access to or use of the API at any time if we are unable at any time to determine or verify your identity or eligibility.

  6. HIPAA and Security Terms

    In accordance with HIPAA recommendations (cited below for reference) InPracSys Inc products including all InPracSys Health services and products are compliant in securing the authenticity, access control, audits and authorization of Personal Health Information. You are solely responsible for all aspects of HIPAA compliance in your application and your use of InPracSys Health API, and you will ensure that you will provide authentication, access control, authorization and a trusted connection to our API servers.

    You shall indemnify, defend and hold harmless Innovative Practice Systems Inc. and its shareholders, members, partners, owners, officers, directors, managers, and employees from and against all claims, liabilities, losses and damages resulting from any potential breach of HIPAA regulations or gross negligence, resulting from your application or use of InPracSys Health API.

  7. Application Programming Interface (API) Task Force Recommendations

    Application Programming Interface (API) refers to technology that allows one software program to access the services provided by another software program. In its 2015 Edition of Health IT Certification Criteria (2015 CHIT), the Office of the National Coordinator for Health Information Technology (ONC) established criteria at §170.316(g)(7), and (g)(9) that requires certified health IT to demonstrate the ability provide a patient-facing app access to the Common Clinical Data Set via an API.

    §170.316(g)(7) - Application Access, Patient Selection
    §170.316(g)(9) - Application Access, All Data Request

    To be certified for API criteria, three privacy and security criterion must also be met:

    §170.315(d)(1) “authentication, access control and authorization;”
    §170.315(d)(9) “trusted connection;”
    §170.315(d)(10) “auditing actions on health information” or §170.315(d)(2) “auditable events and tamper resistance”

  8. Term and Termination

    This Agreement is effective until terminated. You may terminate this Agreement at any time by ceasing to use InPracSys Health API. This Agreement will terminate immediately without notice from Innovative Practice Systems Inc. if you fail to comply with any provision of this Agreement. Upon termination, you must cease to deploy any application using InPracSys Health API.

  9. Warranty Disclaimer and Limitation of Liability

    Innovative Practice Systems Inc. licenses InPracSys Health API to you on an "as is" basis, without warranty of any kind. Innovative Practice Systems Inc. hereby expressly disclaims all warranties or conditions, either express or implied, including, but not limited to, the implied warranties or conditions of merchantability and fitness for a particular purpose. You are solely responsible for determining the appropriateness of using InPracSys Health API and assume all risks associated with the use of it, including but not limited to the risks of program errors, damage to or loss of data, programs or equipment, and unavailability or interruption of operations. Some jurisdictions do not allow for the exclusion or limitation of implied warranties, so the above limitations or exclusions may not apply to you.

    Innovative Practice Systems Inc. will not be liable for any direct damages or for any special, incidental, or indirect damages or for any economic consequential damages (including lost profits or savings), even if Innovative Practice Systems Inc. has been advised of the possibility of such damages. Innovative Practice Systems Inc. will not be liable for the loss of, or damage to, your records or data, or any damages claimed by you based on a third party claim. Some jurisdictions do not allow for the exclusion or limitation of incidental or consequential damages, so the above limitations or exclusions may not apply to you.

  10. Intellectual Property
    1. You agree that Innovative Practice Systems Inc. and its affiliates retain all worldwide right, title and interest in and to the InPracSys Health API Materials, including, without limitation, all intellectual property rights therein. Any rights not expressly granted herein are prohibited and reserved.
    2. You understand that Innovative Practice Systems Inc. may currently or in the future develop products and services that may be similar to or compete with your Developer Applications. Nothing in this Agreement shall in any way restrict Innovative Practice Systems Inc. from pursuing any business activities or from entering into any agreement with any other person or company.
    3. In the event that you choose to provide Innovative Practice Systems Inc. with feedback, suggestions or comments regarding the InPracSys Health API Materials or your use thereof, you agree that Innovative Practice Systems Inc. will be free to use, copy, modify, create derivative works, distribute, publicly display, publicly perform, grant sublicenses to, and otherwise exploit in any manner such feedback, suggestions or comments, for any and all purposes, with no obligation of any kind to you.
    4. You hereby grant to Innovative Practice Systems Inc. a paid-up, royalty-free, non- exclusive, worldwide, transferable, sublicenseable, right and license, under all applicable intellectual property rights, for Innovative Practice Systems Inc.’s marketing and promotional purposes to: (a) use, perform, make available, display to the public, reproduce your Developer Application and your integration of the InPracSys Health API Materials and (b) use your name, likeness, or brand (which includes all your trademarks, service marks, logos, brand names, or trade names) (“Your Marks”) to the extent it is incorporated into your Developer Application. Following the termination of this Agreement and upon written request from you, Innovative Practice Systems Inc. shall make commercially reasonable efforts, as determined in its sole discretion, to remove references to your Develop Application and any of Your Marks from the Innovative Practice Systems Inc. website.

  11. Right to Modify

    You acknowledge and agree that Innovative Practice Systems Inc. may modify this Agreement, the API, and the InPracSys Health API Materials from time to time (a “Modification”). You will be notified of a Modification through direct communication from Innovative Practice Systems Inc. to you as soon as possible. Notwithstanding the above, you acknowledge and agree that such Modifications may be implemented at any time and without any prior notice to you. You shall, within thirty (30) days from the date of first notice of any Modification(s) (or such shorter period of time specified in the notice of the Modification(s)) (the “Conformance Period”) comply with such Modification(s) by implementing and using the most current version of the API and making any changes to your applications that may be required as a result of such Modification(s). You acknowledges that a Modification may have an adverse effect on your applications, including but not limited to changing the manner in which your applications communicate with the API. Medical mine Inc. shall have no liability of any kind to you or any user of your applications with respect to such Modifications or any adverse effects resulting from such Modifications. Your continued access to or use of the Services or API following the Conformance Period shall constitute binding acceptance of the Modification(s) at issue.

  12. General

    You acknowledge and agree that Innovative Practice Systems Inc. may modify this Agreement, the API, and the InPracSys Health API Materials from time to time (a “Modification”). You will be notified of a Modification through direct communication from Innovative Practice Systems Inc. to you as soon as possible. Notwithstanding the above, you acknowledge and agree that such Modifications may be implemented at any time and without any prior notice to you. You shall, within thirty (30) days from the date of first notice of any Modification(s) (or such shorter period of time specified in the notice of the Modification(s)) (the “Conformance Period”) comply with such Modification(s) by implementing and using the most current version of the API and making any changes to your applications that may be required as a result of such Modification(s). You acknowledges that a Modification may have an adverse effect on your applications, including but not limited to changing the manner in which your applications communicate with the API. Medical mine Inc. shall have no liability of any kind to you or any user of your applications with respect to such Modifications or any adverse effects resulting from such Modifications. Your continued access to or use of the Services or API following the Conformance Period shall constitute binding acceptance of the Modification(s) at issue.

    This Agreement is governed by the laws of the State of Minnesota. This Agreement is the only understanding and agreement we have regarding your use of InPracSys Health API. You shall not export InPracSys Health API or the derived application except in compliance with United States export regulations and applicable laws and regulations. It supersedes all other communications, understandings or agreements we may have had prior to this Agreement.