CareCentric FHIR API Postman Guide
FHIR APIs in CareCentric are still in early development, so we'd welcome suggestions and feedback on what you'd like to see from them in future!
This tutorial is designed to get you up and running quickly, and get some data from the APIs using Postman.
Before you begin this tutorial, you’ll need the following:
- An account on the CareCentric API Developer Portal (this site!). If you haven't already signed up for an account, click here to do so now!
- A subscription to one of our API "products" - you can see what subscriptions you have, and request a new subscription here
- A copy of Postman to run on your PC/Laptop. You can download Postman from here
Note: This guide will make use of our publicly available "sandpit" environment, so there is no risk of accidentally accessing any sensitive patient data using these APIs.
Using the pre-built Postman collection
If you don't want the hassle of following the below steps, you can download a pre-made postman collection with all the public APIs in it.
IMPORTANT NOTE: Exported Postman collections don't include the configuration for requesting an access token, and also won't include a subscription ID, so you will still need to follow Step 1 and Step 2 below to configure this for the imported collection before you can test any of the API calls.
Step 1 - Getting an Access Token
The APIs require an OAuth2 access token to grant access. You will need to request a token from the OAuth2 token endpoint, and use the token in all API calls to Authorise access.
Luckily Postman provides tools to do the OAuth2 token request for you - to do this:
- Create a new request.
- Give your request name.
- Save the Request.
- Select the 'Authorization' tab.
- TIP: If you save your requests into a collection (or are using the pre-built collection above), you can apply the Authorisation to the collection as a whole rather than in each individual request. To do that - right click the collection name, click 'Edit', then click the Authorisation tab here to configure it for the whole collection.
- Select Type 'OAuth 2.0'.
- Click the ‘Get New Access Token’ button.
- Populate the fields on the 'Get New Access Token' screen:
- Token Name: CareCentricAPIToken
- Grant Type: Password Credentials
- Access Token URL: https://prv-is.grhapp.com/connect/token
- Username: RewiredHackathon
- Password: Rew1redH&ck
- Client ID: FHIRUser
- Client Secret: fh1rA$dial0gUe
- Scope: launch user/*.read openid profile
- Client Authentication: Send client credentials in body
- Click the 'Request Token' button.
- When the Access Token appears, scroll down and click the ‘Use Token’ button.
Step 2 - Create a Postman Environment and configure your Subscription Key
You need to have a subscription to be able to call any APIs.
You need to have a subscription to be able to call any APIs.
To configure your subscription ID, we need to add a Postman 'environment':
- Click the small 'Manage Environments' cog in the top right of the postman screen
- Click 'Add' and give your environment a name (anything will do!)
- Now, in the variables table, add a row with variable name: subscription-key and set the value to your subscription key (you can get that here)
- Click 'Add' then close the Manage Environments window
- Finally, from the environments drop-down at the top-right, choose your new envirionment to make it active
Step 3 - Calling your First FHIR API
Now we have an access token, we can call our first API
We'll start by searching for a specific Patient resource for Marjorie Heritage:
- Update your request from step 1 above, and rename it to "Patient Search"
- Set the URL in our request to be a FHIR search for Marjorie Heritage: https://graphnet-api-nonprod.portal.azure-api.net/STU3/Patient?family=Heritage&given=Marjorie
- Click the 'Headers' tab, and add a header for our subscription key
- Key: Ocp-Apim-Subscription-Key
- Value: {{subscription-key}} (This will insert the subscription key you configured in step 2 above when the request is sent)
- Click 'Send'
- The API call should be sent and return you a bundle of search results for patients called Marjorie Heritage:
{
"resourceType": "Bundle",
"id": "147ea227-a18e-4977-b9cf-e59a4bb57647",
"meta": {
"versionId": "d0a206f5-6aa8-495f-ae49-1e5989f5a32a",
"lastUpdated": "2019-03-21T16:34:44.502+00:00"
},
"type": "searchset",
"total": 1,
"link": [
{
"relation": "self",
"url": "https://fhir-vonk.grhapp.com:4081/Patient?family=Heritage&given=Marjorie"
}
],
"entry": [
{
"fullUrl": "https://fhir-vonk.grhapp.com:4081/Patient/395cadfd-350c-463c-80f9-0702d6c29975",
"resource": {
"resourceType": "Patient",
"id": "395cadfd-350c-463c-80f9-0702d6c29975",
"meta": {
"versionId": "104b42b7-63bf-46a5-85aa-707540380b28",
"lastUpdated": "2018-11-23T15:25:23.598+00:00"
},
"extension": [
{
"url": "https://fhir.hl7.org.uk/STU3/StructureDefinition/Extension-CareConnect-EthnicCategory-1",
"valueCodeableConcept": {
"coding": [
{
"system": "Ethnicity"
}
]
}
},
{
"url": "https://fhir.hl7.org.uk/STU3/StructureDefinition/Extension-CareConnect-ReligiousAffiliation-1",
"valueCodeableConcept": {
"coding": [
{
"system": "Religion"
}
]
}
}
],
"identifier": [
{
"use": "official",
"system": "Graphnet-Patient-Id",
"value": "1144"
},
{
"use": "usual",
"system": "system",
"value": "2289"
},
{
"use": "official",
"system": "https://fhir.nhs.uk/Id/local-patient-identifier",
"value": "234 571 4999"
},
{
"use": "official",
"system": "https://fhir.nhs.uk/Id/nhs-number",
"value": "234 571 4999"
}
],
"active": true,
"name": [
{
"use": "official",
"family": "Heritage",
"given": [
"Marjorie"
],
"prefix": [
"Mrs"
]
},
{
"use": "temp"
}
],
"telecom": [
{
"system": "phone",
"value": "01829 251252",
"use": "home"
},
{
"system": "phone",
"value": "01829 251252",
"use": "work"
},
{
"system": "phone",
"use": "mobile"
},
{
"system": "email",
"use": "home"
}
],
"gender": "female",
"birthDate": "1950-05-21",
"deceasedBoolean": false,
"address": [
{
"line": [
"",
"Meadow Close",
"Tarvin ",
"Cheshire",
""
],
"postalCode": "CH3 8LY"
}
],
"maritalStatus": {
"coding": [
{
"system": "http://hl7.org/fhir/v3/MaritalStatus",
"code": "U"
}
]
}
},
"search": {
"mode": "match"
}
}
]
}