The Private Practice Register (PPR) APIs bundle encapsulates API interfaces related to activities in scope of carrying out private practice – hospital credentialing, insurer recognition, enabling practitioners to manage their private practice profile centrally in one place, etc.
Getting started
General aspects of integrating with Healthcode APIs, like authentication and authorisation, naming conventions, data formatting assumptions, error handling requirements, etc. are documented here.
Pay special attention to the aspects of using discovery document, the need to specify site id within the request headers, and the need to specify exact API version.
Also, be certain you are connecting to the correct environment. If you are trying to integrate into our sandbox (UAT) environment, read instructions here first to understand the requirements.
Practitioner
Search Practitioners
The Search Practitioners API enables searching for practitioners for a given profession, specialty and with a specific postcode.
Endpoint
Must be looked up from the discovery document using key search_practitioner_endpoint.
Request
A sample request searching for a practitioner is provided below.
curl --request GET
--url 'search_practitioner_endpoint?
page=1&
count=1&
gender=male&
profession=00U&
specialty=0003A&
subspecialty=0000L&
insurer-recognition-status=Y&
insurer-provider-number=984572186&
insurer=nuh&
address-postalcode=W1H 3DA&
family=Clinton&
given=Warren
is-onlinebooking-available=false
regulator-reference=1234567'\
--header 'Authorization: Bearer abCdE12...89mNopq0r' \
--header 'Content-Type: application/fhir+json' \Where,
| Field | Type | Mandatory/ Optional | Description |
|---|---|---|---|
| profession | String | O | Profession code for which slots are to be searched. |
| gender | String | O | Gender of the practitioner. |
| given | String | O | First name of the practitioner. |
| family | String | O | Surname of the practitioner. |
| address-postalcode | String | O | Postcode of the practitioner’s location. |
| specialty | String | O | Specialty code for which slots are to be searched. |
| subspecialty | String | O | Subspecialty code for which slots are to be searched. |
| insurer-recognition-status | String | O | The practitioner’s recognition status with the insurer. |
| insurer-provider-number | String | O | Provider number assigned by the insurer. |
| insurer | String | O | The code of the insurer the practitioner is recognised by. |
| is-onlinebooking-available | Boolean | O | “true” if Practitioner has active eBooking schedules in use, otherwise “false” |
| regulator-reference | String | O | The unique regulatory reference number |
The
is-onlinebooking-availableparameter can be used to search for the practitioners who have enabled the online appointment booking service.
Response
Sample FHIR response of resource type bundle with the practitioner resource within it.
{
"resourceType": "Bundle",
"meta": {
"tag": [
{
"code": "count",
"display": "1"
},
{
"code": "page",
"display": "1"
},
{
"code": "maxCount",
"display": "204"
}
]
},
"type": "searchset",
"total": 1,
"entry": [
{
"resource": {
"resourceType": "Practitioner",
"id": "SP09000",
"extension": [
{
"id": "indemnityStatus",
"url": "https://ref.api.healthcode.co.uk/extension/indemnityStatus",
"valueString": "N"
},
{
"id": "isOnlineBookingAvailable",
"url": "https://ref.api.healthcode.co.uk/extension/onlineBookingStatus",
"valueBoolean": false
},
{
"id": "profession",
"url": "https://ref.api.healthcode.co.uk/extension/profession",
"extension": [
{
"id": "profession",
"url": "https://ref.api.healthcode.co.uk/extension/profession",
"valueCodeableConcept": {
"coding": [
{
"system": "https://ref.api.healthcode.co.uk/profession",
"code": "00U",
"display": "Surgeon"
}
]
}
},
{
"id": "specialty",
"url": "https://ref.api.healthcode.co.uk/extension/specialty",
"valueCodeableConcept": {
"coding": [
{
"system": "https://ref.api.healthcode.co.uk/specialty",
"code": "0003A",
"display": "Trauma & Orthopaedics"
}
]
}
},
{
"id": "subspecialty",
"url": "https://ref.api.healthcode.co.uk/extension/subspecialty",
"valueCodeableConcept": {
"coding": [
{
"system": "https://ref.api.healthcode.co.uk/subspecialty",
"code": "0000L",
"display": "Hip"
}
]
}
}
]
},
{
"id": "registrationnumbers",
"url": "https://ref.api.healthcode.co.uk/extension/registrationnumbers",
"extension": [
{
"id": "regulatorybody",
"url": "https://ref.api.healthcode.co.uk/extension/regulatorybody",
"valueCodeableConcept": {
"coding": [
{
"system": "https://ref.api.healthcode.co.uk/regulatorybody",
"code": "GMC",
"display": "General Medical Council"
}
]
}
},
{
"id": "regulatorreference",
"url": "https://ref.api.healthcode.co.uk/extension/regulatorreference",
"valueString": "1234567"
},
{
"id": "registrationdate",
"url": "https://ref.api.healthcode.co.uk/extension/registrationdate",
"valueString": "08.05.1997"
}
]
},
{
"id": "insurers",
"url": "https://ref.api.healthcode.co.uk/extension/insurers",
"extension": [
{
"id": "insurer",
"url": "https://ref.api.healthcode.co.uk/extension/insurer",
"valueCodeableConcept": {
"coding": [
{
"system": "https://ref.api.healthcode.co.uk/insurer",
"code": "nuh",
"display": "Aviva"
}
]
}
},
{
"id": "insurerprovidercode",
"url": "https://ref.api.healthcode.co.uk/extension/insurerprovidercode",
"valueString": "984572186"
},
{
"id": "recognitionstatus",
"url": "https://ref.api.healthcode.co.uk/extension/recognitionstatus",
"valueCodeableConcept": {
"coding": [
{
"system": "https://ref.api.healthcode.co.uk/recognitionstatus",
"code": "Y",
"display": "Recognised"
}
]
}
}
]
}
],
"name": [
{
"family": "Clinton",
"given": [
"Warren"
],
"prefix": [
"Mr"
]
}
],
"telecom": [
{
"id": "phone",
"value": "020 7789 0123"
},
{
"id": "email",
"value": "Warren.Clinton@StElsewhereHospital.com"
}
],
"address": [
{
"type": "postal",
"text": "St Elsewhere Hospital, Sutton Place, London",
"line": [
"St Elsewhere Hospital",
"Sutton Place",
"London"
],
"postalCode": "W1H 3DA"
}
],
"gender": "female",
"birthDate": "09.05.1977",
"qualification": [
{
"id": "FRCS",
"code": {
"coding": [
{
"system": "https://ref.api.healthcode.co.uk/qualification",
"code": "FRCS",
"display": "Fellow Royal College of Surgeons"
}
]
},
"period": {
"start": "2011-01-01T00:00:00+00:00"
}
}
]
}
}
]
}Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | MSG_CANT_PARSE_CONTENT | Failed to parse Practitioner. |
| 400 | MSG_MISSING_MANDATORY_PARAM | Mandatory parameter is missing. |
| 400 | MSG_INVALID_FORMAT | Submitted parameter is not valid. |
| 400 | MSG_PARAM_EMPTY | Parameter is null/empty. |
| 400 | MSG_OP_NOT_ALLOWED | Update for inactive resource is not allowed. |
| 422 | MSG_ENTITY_ALREADY_EXISTS | Entity already exists in database. |
| 422 | MSG_PARAM_INVALID | Parameter content is not valid. |
| 422 | MSG_REFERENCE_ID_NOT_FOUND | Reference ID is not found. |
| 422 | MSG_DATABASE_ERROR | Entity failed to process from database. |
Get Profile Photo
The Get Profile Photo API enables fetching practitioner photo from the PPR profile.
Endpoint
Must be looked up from the discovery document using key get_practitionerphoto_endpoint.
Request
A sample request for get_practitionerphoto is provided below.
curl --request GET
--url '{get_practitionerphoto_endpoint}/{practitioner.id}'
--header 'Authorization: Bearer abCdE12...89mNopq0r'
--header 'Content-Type: application/fhir+json'Response
The API returns the photo as a base-64 encoded binary string wrapped within a Parameters resource.
{
"resourceType": "Parameters",
"parameter": [
{
"name": "photo",
"valueAttachment": {
"contentType": "UTF-8",
"data": "LzlqLzRBQVFTa1pKUmdBQkFnRUFTQUJJQUFELzRSekFSWGhwWmdBQVNVa3FBQWdBQUFBSUFCSUJBd0FCQUFBQUFRQUFBQm9CQlFBQkFBQUFiZ0FBQUJzQkJRQUJBQUFBUFnQUFBR21IQkFBQkFBQUFyd0FBQUN3QkFBQ0EvQW9BRUNjQUFJRDhDZ0FRSndBQVFXUnZZbVVnVUdod...",
"size": 32456,
"title": "Warren_Clinton.jpg"
}
}
]
}Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | MSG_CANT_PARSE_CONTENT | Failed to parse Practitioner. |
| 400 | MSG_MISSING_MANDATORY_PARAM | Mandatory parameter is missing. |
| 400 | MSG_INVALID_FORMAT | Submitted parameter is not valid. |
| 400 | MSG_PARAM_EMPTY | Parameter is null/empty. |
| 400 | MSG_OP_NOT_ALLOWED | Update for inactive resource is not allowed. |
| 422 | MSG_ENTITY_ALREADY_EXISTS | Entity already exists in database. |
| 422 | MSG_PARAM_INVALID | Parameter content is not valid. |
| 422 | MSG_REFERENCE_ID_NOT_FOUND | Reference ID is not found. |
| 422 | MSG_DATABASE_ERROR | Entity failed to process from database. |
Search PractitionerRoles
The Search PractitionerRoles API enables searching across private practice records within Healthcode PPR service.
Endpoint
Must be looked up from the discovery document using key search_practitionerrole_endpoint.
Request
A sample request for get_practitionerrole is provided below.
curl --request GET
--url '{search_practitionerrole_endpoint}?
practitioner=SP09000&
location=HP005000&
ages-treated=C0&
near=53.385225:-2.231105:200:mi&
near-distance=4&
address-postalcode=W1H 3DA&
specialty=0003A&
subspecialty=0000L&
is-onlinebooking-available=false&
insurer=nuh&
profession=00U&
gender=male&
family=Clinton&
given=Warren&
_sort=distance:desc& (OR name:desc)
_include=practitioner:location'
--header 'Authorization: Bearer abCdE12...89mNopq0r'
--header 'Content-Type: application/fhir+json'Where,
| Field | Type | Mandatory/ Optional | Description |
|---|---|---|---|
| practitioner | String | O | Practitioner ID. |
| location | String | O | Location ID. |
| ages-treated | String | O | Code signifying the ages treated. |
| near | String | O | Coordinates from where the distance needs to be calculated Usage: lat:lon:distance:units |
| near-distance | String | O | Radius within which the results need to be searched. |
| address-postalcode | String | O | Postal code of the location. |
| specialty | String | O | Specialty code for the practitioner at the location. |
| subspecialty | String | O | Subspecialty code for the practitioner at the location. |
| is-onlinebooking-available | Boolean | O | Online booking service is available for the practitioner. |
| insurer | String | O | Codes of the insurer(s) the practitioner is recognised by. |
| profession | String | O | Profession code for the practitioner. |
| _sort | String | O | Ask the API to sort the results either in ascending or descending order of distance or for the practitioner’s name. |
| _include | String | O | Ask the API to also include practitioner and location resources. Usage: _include=practitioner:location |
| distinct-by | String | O | To retrieve only distinct records, either practitioner or location. Usage: distinct-by=practitioner |
_sort can only be for distance and name (practitioner name format: Title. GivenName Firstname).
Possible usage is as follows:
1. _sort=distance:asc (for ascending order of results)
2. sort=distance:desc (for descending order of results).
Sort using distance needs to be used only when near and nearis used to get the reference location for calculating the distance.
3. _sort=name:desc OR _sort=name:asc
Is-onlinebooking-available search parameter makes the API look up future-dated schedules available for practitioners in the ICE service and filters the practitioner-role result accordingly.
_include can be applied for practitioner and location resource.
The distinct-by parameter must be used when distinct records by practitioner or location are required. In this case, when distinct-by=practitioner is used the API returns the first available record for each practitioner matching the search criteria.
The near parameter can be used to specify the latitude, longitude, distance and units=km or mi or m. In this case, the coordinates are used to fetch the results within the distance and units specified.
Units:
km = Kilometers
mi = Miles
m = Meters
If no unit is specified, only latitude, longitude and distance, “km” is considered by default.
Alternatively, the near-distance parameter can be used to specify the distance, but preference would be given to the near parameter if a distance is already mentioned in that.
Response
The API returns a list of practitioner-role resources in response.
{
"resourceType": "Bundle",
"meta": {
"tag": [
{
"code": "count",
"display": "2"
},
{
"code": "page",
"display": "1"
},
{
"code": "maxCount",
"display": "2"
}
]
},
"type": "searchset",
"total": 2,
"entry": [
{
"resource": {
"resourceType": "PractitionerRole",
"id": "201808281356174321LBf0241",
"extension": [
{
"id": "agestreated",
"url": "https://ref.api.healthcode.co.uk/extension/agestreated",
"valueCodeableConcept": {
"coding": [
{
"system": "https://ref.api.healthcode.co.uk/agestreated",
"code": "C1",
"display": "4-12 Years"
}
]
}
}
],
"practitioner": {
"reference": "Practitioner/SP09000",
"display": "Mr Warren Clinton"
},
"specialty": [
{
"coding": [
{
"system": "https://ref.api.healthcode.co.uk/specialty",
"code": "0003A",
"display": "Trauma & Orthopaedics"
}
]
}
],
"location": [
{
"reference": "Location/HP005000",
"display": "St Elsewhere Hospital"
}
]
},
"search": {
"mode": "match"
}
},
{
"resource": {
"resourceType": "PractitionerRole",
"id": "201808281119493731SBH0094",
"extension": [
{
"id": "agestreated",
"url": "https://ref.api.healthcode.co.uk/extension/agestreated",
"valueCodeableConcept": {
"coding": [
{
"system": "https://ref.api.healthcode.co.uk/agestreated",
"code": "C0",
"display": "0-3 Years"
}
]
}
},
{
"id": "agestreated",
"url": "https://ref.api.healthcode.co.uk/extension/agestreated",
"valueCodeableConcept": {
"coding": [
{
"system": "https://ref.api.healthcode.co.uk/agestreated",
"code": "C1",
"display": "4-12 Years"
}
]
}
}
],
"practitioner": {
"reference": "Practitioner/SP09000",
"display": "Mr Warren Clinton"
},
"specialty": [
{
"coding": [
{
"system": "https://ref.api.healthcode.co.uk/specialty",
"code": "0003A",
"display": "Trauma & Orthopaedics"
}
]
}
],
"location": [
{
"reference": "Location/HP005000",
"display": "St Elsewhere Hospital"
}
]
},
"search": {
"mode": "match"
}
}
]
}Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | MSG_CANT_PARSE_CONTENT | Failed to parse Practitioner. |
| 400 | MSG_MISSING_MANDATORY_PARAM | Mandatory parameter is missing. |
| 400 | MSG_INVALID_FORMAT | Submitted parameter is not valid. |
| 400 | MSG_PARAM_EMPTY | Parameter is null/empty. |
| 400 | MSG_OP_NOT_ALLOWED | Update for inactive resource is not allowed. |
| 422 | MSG_ENTITY_ALREADY_EXISTS | Entity already exists in database. |
| 422 | MSG_PARAM_INVALID | Parameter content is not valid. |
| 422 | MSG_REFERENCE_ID_NOT_FOUND | Reference ID is not found. |
| 422 | MSG_DATABASE_ERROR | Entity failed to process from database. |