To provide industry-standard services, Healthcode maintains suites of coding standards and classifications. The Reference/Master Data Management APIs bundle exposes APIs to enable retrieving and looking up the common code sets. The APIs also allow calling systems to look up the Healthcode references for common entities like practitioners, treatment sites, insurers, 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.
Retrieve Master Code Sets
The code-sets APIs allow the calling system to obtain the master code sets. The following table lists the code-sets currently available.
| Name | Scheme | Definition | Description |
|---|---|---|---|
| service-category | ISC | Service categories | |
| service-type | ISC | Service codes | |
| procedure-code | CCSD, 9BUPP | Procedure codes | |
| condition-code | ICD9, ICD10 | Diagnosis codes | |
| practitioner-role | Practitioner professions | ||
| practitioner-specialty | Practitioner specialties | The API supports a practitioner-role path parameter to enable retrieving specialties corresponding to a specific profession. In order to use this feature, you can suffix practitioner-role code to the API endpoint as ~/practitioner-specialty/{practitionerRole}. | |
| practitioner-subspecialty | Practitioner subspecialties |
Endpoint
Must be looked up from the discovery document using key codes_valueset_namespace.
Request
The name, and optionally scheme, of the specific code set, as specified in the table above, need to supplied as path parameters.
curl --request GET
--url '{codes_valueset_namespace}/{set name}/{scheme}?
count=2&
page=1'
--header 'Authorization: Bearer abCdE12...89mNopq0r'
--header 'Content-Type: application/fhir+json' This API supports pagination and incremental data sync query parameters as documented here. These APIs support a custom page size of 1 to 1,000.
Response
In the case of an ISC retrieval request the API returns a ValueSet resource in below format.
{
"resourceType": "ValueSet",
"id": "service-type",
"meta": {
"tag": [
{
"code": "page",
"display": "1"
},
{
"code": "count",
"display": "2"
},
{
"code": "maxCount",
"display": "6275"
}
]
},
"name": "service-type",
"expansion": {
"total": 2,
"offset": 1,
"contains": [
{
"system": "http://ref.api.dev.healthcode.co.uk/valueset/service-type/ISC",
"code": "D0000240",
"display": "Consultant"s Charge, Myringotomy",
"extension": [
{
"url": "requiresProcedure",
"valueString": "N"
},
{
"id": "lastUpdated"
}
]
},
{
"system": "http://ref.api.dev.healthcode.co.uk/valueset/service-type/ISC",
"code": "D0000250",
"display": "Ward's Consumables",
"extension": [
{
"url": "requiresProcedure",
"valueString": "N"
},
{
"id": "lastUpdated",
"valueDateTime": "2021-05-23T10:00:16+00:00"
}
]
}
]
}
}Where,
| Field | Type | Description |
|---|---|---|
| expansion.contains.code | String | ISC code |
| expansion.contains.display | String | Description for this ISC |
Error handling
The value-set APIs do not return any API-specific errors. When no matches are found, the API will return an empty result set. Calling applications must handle the standard error scenarios such as API endpoint not being available, connection timeout, etc.
Practitioner Lookup
The Practitioner Lookup API enables integrating systems to look up against master practitioner directory.
This API intentionally only returns a very minimum header information about practitioner records and intended to be used for uses cases like providing users with a dropdown on a form to select a practitioner entry. For searching across practitioner profiles or for getting full profile of a given practitioner, use the Search Practitioners API under the Private Practice Register (PPR) APIs bundle.
Endpoint
Must be looked up from the discovery document using key lookup_practitioner_endpoint.
Request
curl --request GET
--url '{lookup_practitioner_endpoint}?
page=1&
count=2'
--header 'Authorization: Bearer abCdE12...89mNopq0r'
--header 'Content-Type: application/fhir+json' Response
{
"resourceType": "Bundle",
"id": "practitioner",
"meta": {
"tag": [
{
"code": "page",
"display": "1"
},
{
"code": "count",
"display": "2"
},
{
"code": "maxCount",
"display": "451"
}
]
},
"type": "collection",
"total": 451,
"entry": [
{
"fullUrl": "https://ref.api.healthcode.co.uk/practitioner/SP050419",
"resource": {
"resourceType": "Practitioner",
"id": "SP050419",
"meta": {
"id": "lastupdatedon",
"lastUpdated": "2017-06-21T10:23:14.000"
},
"extension": [
{
"url": "https://ref.api.healthcode.co.uk/valueset/profession/004",
"valueCodeableConcept": {
"coding": [
{
"system": "HEALTHCODE",
"code": "004",
"display": "Clinical Scientist"
}
]
}
}
],
"active": true,
"name": [
{
"family": "Sekkae",
"given": [
"Poorni"
]
}
],
"gender": "female"
}
},
{
"fullUrl": "https://ref.api.healthcode.co.uk/practitioner/SP050421",
"resource": {
"resourceType": "Practitioner",
"id": "SP050421",
"meta": {
"id": "lastupdatedon",
"lastUpdated": "2017-06-21T13:05:19.000"
},
"extension": [
{
"url": "https://ref.api.healthcode.co.uk/valueset/profession/004",
"valueCodeableConcept": {
"coding": [
{
"system": "HEALTHCODE",
"code": "004",
"display": "Clinical Scientist"
}
]
}
}
],
"active": true,
"name": [
{
"family": "Patil",
"given": [
"Aparna"
]
}
],
"gender": "female"
}
}
]
}Error handling
When the “text” parameter is not found in the request an HTTP status of “400 Bad Request” is returned.
Location Lookup
The Location Lookup API enables integrating systems to look up against master treatment sites directory.
This API intentionally only returns a very minimum header information about treatment site records and intended to be used for uses cases like providing users with a dropdown on a form to select a treatment site entry. If needing to retrieve list of private practice records as registered within The PPR, use the Search PractitionerRoles API under the Private Practice Register (PPR) APIs bundle.
Endpoint
Must be looked up from the discovery document using key lookup_location_endpoint.
Request
curl --request GET
--url '{lookup_location_endpoint}?
type=P&
page=1&
count=2'
--header 'Authorization: Bearer abCdE12...89mNopq0r'
--header 'Content-Type: application/fhir+json' Response
{
"resourceType": "Bundle",
"id": "location",
"meta": {
"tag": [
{
"code": "page",
"display": "1"
},
{
"code": "count",
"display": "2"
},
{
"code": "maxCount",
"display": "932"
}
]
},
"type": "collection",
"total": 932,
"entry": [
{
"fullUrl": "https://ref.api.healthcode.co.uk/location/HP002278",
"resource": {
"resourceType": "Location",
"id": "HP002278",
"meta": {
"id": "lastupdatedon",
"lastUpdated": "2021-05-12T15:10:56.000"
},
"name": "Bmi Princess Margaret Hospital Health Fund",
"address": {
"line": [
"39 - 42 Osborne Road",
"Windsor",
"Berks"
],
"postalCode": "SL4 3SJ"
}
}
},
{
"fullUrl": "https://ref.api.healthcode.co.uk/location/HP002279",
"resource": {
"resourceType": "Location",
"id": "HP002279",
"meta": {
"id": "lastupdatedon",
"lastUpdated": "2022-01-27T08:52:17.000"
},
"name": "Bmi Shelburne Hospital",
"address": {
"line": [
"Queen Alexandra Road",
"High Wycombe",
"Buckinghamshire"
],
"postalCode": "HP11 2TR"
},
"position": {
"longitude": -0.7535295999999999,
"latitude": 51.6258942
}
}
}
]
}Error handling
When the “text” parameter is not found in the request an HTTP status of “400 Bad Request” is returned.