CareCentric CCAPI Postman Guide

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.

Download Postman Collection

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:

  1. Create a new request.
  2. Give your request name.
  3. Save the Request.
  4. 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.
  5. Select Type 'OAuth 2.0'.
  6. Click the ‘Get New Access Token’ button.
  7. Populate the fields on the 'Get New Access Token' screen:
    • Token Name: CareCentricAPIToken
    • Grant Type: Password Credentials
    • Access Token URL: https://fhir-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
  8. Click the 'Request Token' button.
  9. When the Access Token appears, scroll down and click the ‘Use Token’ button.

Step 1b - Getting an Access Token (for unattended calls)

In case where there is no user present (e.g. when feeding data into the shared care record) rather than requesting a token using user credentials, you can use an OAuth2 client credentials grant, providing just a client ID and secret.

To do this from Postman:

  1. Create a new request.
  2. Give your request name.
  3. Save the Request.
  4. Select the 'Authorization' tab.
  5. Select Type 'OAuth 2.0'.
  6. Click the ‘Get New Access Token’ button.
  7. Populate the fields on the 'Get New Access Token' screen:
    • Token Name: CareCentricAPIToken
    • Grant Type: Client Credentials
    • Access Token URL: https://coret1.syhapp.com/vlive/hpca/oauth/token
    • Client ID: ccapi-data-submission-test
    • Client Secret: db74f2b2-76d4-4dbf-92ba-72faf48a533f
    • Client Authentication: Send client credentials in body
  8. Click the 'Request Token' button.
  9. 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.

To configure your subscription ID, we need to add a Postman 'environment':

  1. Click the small 'Manage Environments' cog in the top right of the postman screen
  2. Click 'Add' and give your environment a name (anything will do!)
  3. 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)
  4. Click 'Add' then close the Manage Environments window
  5. Finally, from the environments drop-down at the top-right, choose your new envirionment to make it active

Step 3 - Calling your First CCAPI

Now we have an access token, we can call our first API

We'll start by searching for a specific patient - Marjorie Heritage:

  1. Update your request from step 1 above, and rename it to 'Find Patient'
  2. Set the URL in our request to be the URL for the 'Find Patient' API: https://graphnet-api-nonprod.portal.azure-api.net/demographics/patients/search
  3. Change the request type to 'POST'
  4. 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)
  5. Click the 'Body' tab, change the type to "raw", and paste the below JSON parameters into the body box:
      
{
  "AllTenancies": true,
  "Surname": "Heritage"
}

  1. In the drop-down just above the body box, change the type to 'JSON (application/json)'
  2. Click 'Send'
  3. The API call should be sent and return you a JSON object with search results for patients with the surname 'Heritage':
      
{
    "MatchingPatients": [
        {
            "PatientNumber": {
                "NumberId": null,
                "Number": "012354654",
                "PreviousNumber": null,
                "PatientNoType": "DEFAULT"
            },
            "Details": {
                "Context": "CWP Mental Health Feed",
                "PatientID": "1114",
                "NHSNo": "234 571 4999",
                "TenancyId": 4,
                "DetailId": 2278
            },
            "PersonId": 0,
            "Title": "MS",
            "Forenames": "Maggie",
            "Surname": "Heritage",
            "Sex": 1,
            "DoB": "1950-05-21T00:00:00"
        },
        {
            "PatientNumber": {
                "NumberId": null,
                "Number": "234 571 4999",
                "PreviousNumber": null,
                "PatientNoType": "DEFAULT"
            },
            "Details": {
                "Context": "Orglinks",
                "PatientID": "1114",
                "NHSNo": "234 571 4999",
                "TenancyId": 2,
                "DetailId": 2228
            },
            "PersonId": 0,
            "Title": "Mrs",
            "Forenames": "Marjorie",
            "Surname": "Heritage",
            "Sex": 1,
            "DoB": "1950-05-21T00:00:00"
        },
        {
            "PatientNumber": {
                "NumberId": null,
                "Number": "CCC",
                "PreviousNumber": null,
                "PatientNoType": "DEFAULT"
            },
            "Details": {
                "Context": "Clatterbridge Cancer Centre",
                "PatientID": "1114",
                "NHSNo": "234 571 4999",
                "TenancyId": 6,
                "DetailId": 2279
            },
            "PersonId": 0,
            "Title": "MRS",
            "Forenames": "Margo",
            "Surname": "Heritage",
            "Sex": 1,
            "DoB": "1950-05-21T00:00:00"
        },
        {
            "PatientNumber": {
                "NumberId": null,
                "Number": "CCC",
                "PreviousNumber": null,
                "PatientNoType": "DEFAULT"
            },
            "Details": {
                "Context": "Child Services (Cheshire) /Liquid Logic",
                "PatientID": "1114",
                "NHSNo": "234 571 4999",
                "TenancyId": 11,
                "DetailId": 2280
            },
            "PersonId": 0,
            "Title": "MRS",
            "Forenames": "Margo",
            "Surname": "Heritage",
            "Sex": 1,
            "DoB": "1950-05-21T00:00:00"
        },
        {
            "PatientNumber": {
                "NumberId": null,
                "Number": "CCC",
                "PreviousNumber": null,
                "PatientNoType": "DEFAULT"
            },
            "Details": {
                "Context": "Buckinghamshire Hospital NHS Trust",
                "PatientID": "1114",
                "NHSNo": "234 571 4999",
                "TenancyId": 17,
                "DetailId": 2285
            },
            "PersonId": 0,
            "Title": "MRS",
            "Forenames": "Margo",
            "Surname": "Heritage",
            "Sex": 1,
            "DoB": "1950-05-21T00:00:00"
        },
        {
            "PatientNumber": {
                "NumberId": null,
                "Number": "COCH991199",
                "PreviousNumber": null,
                "PatientNoType": "DEFAULT"
            },
            "Details": {
                "Context": "Countess of Chester",
                "PatientID": "1114",
                "NHSNo": "234 571 4999",
                "TenancyId": 5,
                "DetailId": 2277
            },
            "PersonId": 0,
            "Title": "MISS",
            "Forenames": "Marj",
            "Surname": "Heritage",
            "Sex": 1,
            "DoB": "1950-05-21T00:00:00"
        }
    ]
}

Step 4 - Using Patient DetailIDs in subsequent API calls

Many of the other API calls in the CCAPI bundles use a 'patient detail ID' value rather than an NHS number or specific patient ID from the source systems that submit data into CareCentric. This allows local identifiers to change over time, and for patients to be linked and un-linked without the detail IDs for specific record content having to change.

From the search in step 3 above, we can see a few matches for Marjorie - this is because we have received data about Marjorie from a number of source systems. Because they are all linked to the same person within CareCentric, we can use any of the DetailID values for Marjorie, and they should all return results for Marjorie (where data exists). So, for most of the other API calls in the CCAPI bundles, we can generally use detail ID 2228 for Marjorie.

As an example:

  1. Clone the request from step 3 above, and rename the cloned request to "GP Encounters"
  2. Change the type to "GET" and the URL to: https://graphnet-api-nonprod.portal.azure-api.net/gp/patients/:patient-detail-id/gp-encounters
  3. This will add a new parameter called 'patient-detail-id' in the Params tab, set the value of this parameter to 2228
  4. Click Send
  5. You should now receive a set of encounter result records for Marjorie.