Patient Access API Documentation

  1. Getting Started
    1. Registration Process
    2. Payer-To-Payer
    3. OAuth Basics
    4. Scopes
  2. FHIR Profiles
    1. Profile Implementation Differences
  3. Error handling

Getting Started

The Patient Access API is AllCare Health's HL7 FHIR API which implements a wide variety of FHIR Profiles to give access to the data elements which comprise the United States Core Data for Interoperability version 1.

Registration Process

To gain access the Patient Access API you must first register as a developer. To register, click here. Once registered you may add your application. To register your application please provide the name of the application and the redirect URI that AllCare Health will forward the user to after they grant or deny access. Registering will generate your OAuth Client Id and secret. Be careful to store your client secret securely. If lost, you will be required to generate a new key as the secrets are not recoverable once generated.

Payer-To-Payer

AllCare Health uses the same Patient Access API as the mechanism for payer-to-payer data exchange. Please note, in order to prevent the need for member matching, we provide the patient identifier as part of the access token response. The patient field holds our identifier and should be used as the ID for any API call in which you specify the member.

For the purposes of this documentation, a developer and payer should be considered synonymous.

OAuth Basics

The Patient Access API is protected through the use of OAuth 2.0. For a better understanding of how the OAuth protocol works, please visit here.

Once you have registered your application with us, you will need a consenting AllCare member to allow access to be shared with your application. To request access from the member, you will need to use the following URL with your application specifics filled in : 

https://ccoportal.allcarehealth.com/connect/authorize?client_id=<YOUR CLIENTID HERE>
&redirect_uri=<YOUR REDIRECT URI HERE>
&state=<state parameter here>
&response_type=code id_token
&scope=<requested scopes here>
&response_mode=form_post
&nonce=<NONCE HERE>
If the member grants access, the authorization code will be granted and returned to your callback URI. Note that the URL used here is for CCO Members, for advantage members you would use 'https://advportal.allcarehealth.com' instead. You must then request an Access Token using that code. For example 
https://ccoportal.allcarehealth.com/connect/token?ClientId=<YOUR CLIENTID HERE>
&ClientSecret=<YOUR SECRET HERE>
&Code=<AUTHORIZATION CODE HERE> 
&RedirectUri=<YOUR REDIRECT URI HERE>
The response should look something like this : 
{
    "id_token":"IDTOKEN HERE",
    "access_token":"access token here",
    "expires_in":3600,
    "token_type":"Bearer",
    "scope":"patientapi.demographics.read openid",
    "patient":"00000000"
}
Now, when querying the API you would submit that access token in the header as such 
GET https://interop-cco.api.allcarehealth.com/Patient/00000000 HTTP/1.1
Accept: application/json, text/json, text/x-json, text/javascript, application/xml, text/xml
Authorization: Bearer accesstokengoeshere
Accept-Encoding: gzip, deflate
If everything worked correctly you should now be able to access the REST FHIR resources for that user. See the different profiles available below.

Supported Scopes

When creating the OAuth initial request, be sure to include only the specific scopes your application needs. The supported list of scopes can be found on the OpenID Configuration in the "scopes_supported" section of the JSON. **Please note that wildcard scopes are not currently listed**. If you require all supported scopes include each one individually in the opening OAuth request (connect/authorize).

FHIR Profiles

Each of the following FHIR Profiles have been implemented and are available. These profiles provide example data types and give information about what search parameters are supported. All data elements with a minimum cardinality of 1 and marked MUST SUPPORT are available. Elements not labeled MUST SUPPORT and a cardinality of 0 may not be available.

Additionally you may view the API server's conformance document as well at the /metadata endpoint.

* - Indicates some differences from the Implementation Guide for the Profile

Profile Implementation Differences


Formulary Drug

Please note that the search parameters for Formulary drug always require the "drugplan" parameter to be passed in addition to any other parameter such as drugtier or drugname.

Error Handling

The Patient access API uses standard HTTP Status codes to indicate if an error occurred. If you receive a 404 status code this typically means we do not have the data you are searching for as submitted in your REST request. A 500 error will typically indicate something went wrong when attempting to process the request. We actively monitor these errors and ask that you try again at a later time. For more information on the meaning of different HTTP status codes, please look here.