Note these are reserved APIs for use by Healthcode internal products only. These APIs must not be consumed by external integrators.

Practitioner

Get/Search Practitioner

This API enables the integrating systems to retrieve, or search for, summary information for practitioner records present within the ICE service.

This API only searches for records local to the Healthcode ICE service. And only returns limitted header information about the practitioner. For a broader search, and to work with full profile information, you need to use the Get/Search Practitioner API within the Private Practice Management APIs bundle.

To retrieve a single practitioner instance for a known ID, the integrating systems can call the Get/Search Practitioner API supplying the practitioner ID as a path parameter. A sample GET request for this is shown below.

curl --request GET 
    --url '{get_booking_practitioner_endpoint}/{practitioner.id}'
    --header 'Authorization: Bearer abCdE12...89mNopq0r' 
    --header 'Content-Type: application/fhir+json'

The remainder of this section details searching for practitioners using different filter criteria. The output of both variations of calls use the same format, except that when retrieving a single practitioner, the resultset will contain only one practitioner instance.

Endpoint

Must be looked up from the discovery document using key search_booking_practitioner_endpoint.

Request

A sample GET request for the API is provided below.

curl --request GET 
    --url '{search_booking_practitioner_endpoint}?
    family=Clinton&
    given=Warren&
    gender=male&
    id=SP09001&
    site=HC0000A&
    profession=00U&
    registeredno=2pjaijho-p2sw-02wh-rcay-ljmr1wk6k0tg&
    channel=202202240654449371AIY0045&
    location=HP005001&
    postcode=W1H 3DA
    near=51.406607:-0.493937:20:km&
    _since= 2020-03-01T09:00:00&
    page=1&
    count=10
    --header 'Authorization: Bearer abCdE12...89mNopq0r' 
    --header 'Content-Type: application/fhir+json'

Where,

Field	Type	Mandatory/ Optional	Description
family	String	O	Surname of the practitioner
given	String	O	First name of the practitioner
gender	String	O	Gender of the practitioner
id	String	O	Practitioner ID
site	String	O	Site that practitioner belongs to
profession	String	O	Profession of the practitioner
registeredno	String	O	Registration number of the practitioner
channel	String	O	Channel ID
location	String	O	Location of the practitioner
postcode	String	O	Postal code of location
near	String	O	Latitude and longitude of the location, distance and units of distance. Valid units are mi-miles, km-kilometres, m-meters.
_since	String	O	Last updated datetime of the practitioner
page	String	O	Page index to be fetched {1,2,3..}
count	String	O	Maximum number of records to be returned in a single page

Response

The API returns a list of practitioner resources in response.

{
    "resourceType": "Bundle",
    "meta": {
        "tag": [
            {
                "code": "count",
                "display": "10"
            },
            {
                "code": "page",
                "display": "1"
            },
            {
                "code": "maxCount",
                "display": "1"
            }
        ]
    },
    "type": "searchset",
    "total": 1,
    "entry": [
        {
            "resource": {
                "resourceType": "Practitioner",
                "meta": {
                    "lastUpdated": "2023-04-12T12:59:09.034+00:00"
                },
                "extension": [
                    {
                        "url": "{ref_URL}/extension/site",
                        "valueReference": {
                            "reference": "Site/HC0000A",
                            "display": "HC0000A"
                        }
                    },
                    {
                        "url": "{ref_URL}/extension/registeredNumber",
                        "valueString": "2pjaijho-p2sw-02wh-rcay-ljmr1wk6k0tg"
                    }
                ],
                "identifier": [
                    {
                        "id": "booking_identifier",
                        "system": "{ref_URL}/identifier",
                        "value": "SP09001"
                    }
                ],
                "active": true,
                "name": [
                    {
                        "family": "Clinton",
                        "given": [
                            "Warren"
                        ]
                    }
                ],
                "gender": "male"
            }
        }
    ]
}

Where,

Field	Type	Description
Practitioner.identifier	String	Practitioner ID

Error handling

HTTP Code	Error Code	Description
400	MSG_CANT_PARSE_CONTENT	Failed to parse Appointment
400	MSG_MISSING_MANDATORY_PARAM	Mandatory parameter is missing
400	MSG_INVALID_FORMAT	Submitted parameter is not valid
400	INVALID_RESOURCE	Unprocessable Entity
422	MSG_FAILED_TO_READ_ENTITY	Failed to read entity from database
404	MSG_ENTITY_NOT_FOUND_IN_DATABASE	No matching resource found
422	MSG_PARAM_INVALID	Parameter content is not valid
422	MSG_REFERENCE_ID_NOT_FOUND	Reference ID is not found
422	MSG_DATE_FORMAT	Date format is not valid

Get/Search PractitionerRole

The PractitionerRole resource represents an instance of private practice, involving a single practitioner at a single location.

This API only searches for records local to the Healthcode ICE service. And only returns limitted header information about the private-practice record. For a broader search, you need to use the Get/Search PractitionerRole API within the Private Practice Management APIs bundle.

To retrieve a single private-practice instance for a known id, the integrating systems can call the Get/Search PractitionerRole API supplying the private practice id as a path parameter. A sample GET request for this is shown below.

curl --request GET 
    --url '{get_practitionerrole_endpoint}/{practitionerrole.id}'
    --header 'Authorization: Bearer abCdE12...89mNopq0r' 
    --header 'Content-Type: application/fhir+json'

The remainder of this section details searching for private practice records using different filter criteria. The output of both variations of calls use the same format, except that when retrieving a single private practice record, the resultset will contain only one practitioner-role instance.

Endpoint

Must be looked up from the discovery document using key search_practitionerrole_endpoint.

Request

A sample GET request for the API is provided below.

curl --request GET 
    --url '{search_practitionerrole_endpoint}? 
    practitioner=SP09001&
    location=HP005001&
    _since= 2020-03-01T09:00:00
    --header 'Authorization: Bearer abCdE12...89mNopq0r' 
    --header 'Content-Type: application/fhir+json'

Where,

Field	Type	Mandatory/ Optional	Description
practitioner	String	O	Practitioner for whom the non availability is defined
location	String	O	Location where the practitionerRole is applied
_since	String	O	Date from which the records needs to be searched
page	String	O	Page index to be fetched {1,2,3..}
count	String	O	Maximum number of records to be returned in a single page

Response

On successful search, the API returns a list of PractitionerRole resources.

{
   "resourceType":"Bundle",
   "meta":{
      "tag":[
         {
            "code":"count",
            "display":"10"
         },
         {
            "code":"page",
            "display":"1"
         },
         {
            "code":"maxCount",
            "display":"1"
         }
      ]
   },
   "type":"searchset",
   "total":1,
   "entry":[
      {
         "resource":{
            "resourceType":"PractitionerRole",
            "id":"20210503172847283BGzQ0047",
            "meta":{
               "lastUpdated":"2021-06-01T10:25:36.044"
            },
            "identifier":[
               {
                  "id":"booking_identifier",
                  "use":"official",
                  "system":"{ref_URL}/identifier",
                  "value":"20210503172847283BGzQ0047"
               },
               {
                  "id":"external_identifier",
                  "use":"official",
                  "system":"{ref_URL}/identifier",
                  "value":"20210503172847283BGzQ0047"
               }
            ],
            "active":true,
            "practitioner":{
               "reference":"Practitioner/SP09001",
               "display":"Mrs Betty Dean"
            },
            "location":[
               {
                  "reference":"Location/HP005001",
                  "display":"Fordingdyke Hospital"
               }
            ]
         }
      }
   ]
}

Where,

Field	Type	Description
id	String	PractitionerRole ID

Error handling

HTTP Code	Error Code	Description
400	MSG_CANT_PARSE_CONTENT	Failed to parse Appointment
400	MSG_MISSING_MANDATORY_PARAM	Mandatory parameter is missing
400	MSG_INVALID_FORMAT	Submitted parameter is not valid
400	INVALID_RESOURCE	Unprocessable Entity
422	MSG_FAILED_TO_READ_ENTITY	Failed to read entity from database
404	MSG_ENTITY_NOT_FOUND_IN_DATABASE	No matching resource found
422	MSG_PARAM_INVALID	Parameter content is not valid
422	MSG_REFERENCE_ID_NOT_FOUND	Reference ID is not found
422	MSG_DATE_FORMAT	Date format is not valid