Note these are reserved APIs for use by Healthcode internal products only. These APIs must be consumed by external integrators.
Introduction
ePx Patient APIs are external API’s used by different user applications.
Authentication of APIs
All the APIs are accessible only using authentication token provided by Healthcode’s Authentication server.
Client application must fetch the token using basic authentication (username, password) and use the token to access the eBooking APIs.
Documentation of authentication APIs is available at below location.
https://apidocs.uat.healthcode.co.uk/overview/authentication/
Create Patient
The Create Patient API enables creating a new patient in ePX system. Patient resources are used to provide information about patient demographics, contact address, telecom and insurer membership information
EndPoint
Must be looked up from discovery-document using key create_patient_endpoint
Request
A sample POST request for creating patient is provided below
curl --location 'https://{BASE_URL}/patient/' \
--header 'Content-Type: application/fhir+json' \
--header 'Authorization: Bearer eyJraWQiOiJyc…' \
--header 'SU-SiteId: HC00JIY' \
--data '{
"resourceType": "Patient",
"extension": [
{
"url": "https://ref.api.healthcode.co.uk/extension/patient/insurer",
"valueString": "ppp"
},
{
"url": "https://ref.api.healthcode.co.uk/extension/patient/registrationid",
"valueString": "THI002933G"
},
{
"url": "https://ref.api.healthcode.co.uk/extension/patient/authorizationno",
"valueString": "ATH03394"
}
],
"name": [
{
"family": "Smith",
"given": [
"John"
],
"prefix": [
"Mr"
]
}
],
"telecom": [
{
"system": "phone",
"value": "01234 567 878",
"use": "home"
}
],
"gender": "male",
"birthDate": "1974-11-23",
"address": [
{
"type": "home",
"text": "123 High Street, Leeds LS1 4HR",
"line": [
"123 High Street, Leeds"
],
"city": "Leeds",
"postalCode": "LS1 4HR"
}
]
}'
Headers
Authorization, ‘SU-SiteID’ and Version Id headers are mandatory to successfully execute the API. If these headers are not present in the request, then the API returns HTTPStatus code 401 with an error response object.
Response Processing
On successful creation of the patient the API will return unique identifier for the new patient. It is recommended the calling system stores this identifier value in order to update or delete the patient at a later point in time
The API returns the newly created patient in JSON format.
{
"resourceType": "Patient",
"id": "20240521055549710Xj8f0001",
"extension": [
{
"url": "https://ref.api.healthcode.co.uk/extension/patient/insurer",
"valueString": "ppp"
},
{
"url": "https://ref.api.healthcode.co.uk/extension/patient/registrationid",
"valueString": "THI002933G"
},
{
"url": "https://ref.api.healthcode.co.uk/extension/patient/authorizationno",
"valueString": "ATH03394"
}
],
"name": [
{
"family": "Smith",
"given": [
"John"
],
"prefix": [
"Mr"
]
}
],
"telecom": [
{
"system": "phone",
"value": "01234 567 878",
"use": "home"
}
],
"gender": "male",
"birthDate": "1974-11-23",
"address": [
{
"type": "home",
"text": "123 High Street, Leeds LS1 4HR",
"line": [
"123 High Street, Leeds"
],
"city": "Leeds",
"postalCode": "LS1 4HR"
}
]
}
Error Handling
| HTTP Code | Error Code | Description |
| 400 | MSG_CANT_PARSE_CONTENT | Failed to parse Appointment |
| 400 | MSG_MISSING_MANDATORY_PARAM | Missing Mandatory Parameter |
| 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 invalid |
| 422 | MSG_REFERENCE_ID_NOT_FOUND | Reference ID not found |
| 422 | MSG_DATE_FORMAT | Invalid date format |
Below are the fields of patient resource which are supported in the response.
| DataType | Occ | Description | FHIR Field |
| String | 1-1 | Patient identifier in third party application | Patient.id |
| String | 0-1 | Insurer | Patient.extension |
| String | 0-1 | registrationid | Patient.extension |
| String | 0-1 | Firstname | Patient.Humanname.given |
| String | 0-1 | Lastname | Patient.Humanname.family |
| String | 0-1 | Title | Patient.Humanname.prefix |
| Telecom | 0-1 | Phone | Patient.Telecom.Value (Where system = ‘phone’) |
| Telecom | 0-1 | Patient.Telecom.Value (Where system = ‘email’) | |
| String | 0-1 | Gender | Patient.gender |
| String | 0-1 | Birthdate | Patient.birthdate |
| Address | 0-1 | Address | Patient.address |
Get Patient
The Get Patient API enables to fetch the created patient from ePX.
End Point
Must be looked up from discovery-document using key get_patienet_endpoint
Request
A sample request for fetching patient is provided below
curl --request GET \
--location '{BASE_URL}/patient/{ID of the Patient}' \
--header 'Content-Type: application/fhir+json' \
--header 'Authorization: Bearer eyJraWQiOiJyc2ExIiwiYWx..' \
--header 'SU-SiteId: HC00JIY' \
--data ''
Response Processing
Sample API response is as below.
{
"resourceType": "Patient",
"id": "20240603091441535eR1s0001",
"extension": [
{
"url": "https://ref.api.healthcode.co.uk/extension/patient/insurer",
"valueString": "ppp"
},
{
"url": "https://ref.api.healthcode.co.uk/extension/patient/registrationid",
"valueString": "THI002933G"
}
],
"active": false,
"name": [
{
"family": "Smith",
"given": [
"John"
],
"prefix": [
"Mr"
]
}
],
"telecom": [
{
"id": "202406030914413167zXj0000",
"system": "phone",
"value": "01234 567 878",
"use": "home"
},
{
"id": "2024060309382190399Ry0004",
"system": "phone",
"value": "01234 567 878",
"use": "home"
},
{
"id": "20240603095329609ijmE0006",
"system": "phone",
"value": "01234 567 878",
"use": "home"
},
{
"id": "202406031002407241syM0000",
"system": "phone",
"value": "01234 567 878",
"use": "home"
},
{
"id": "20240603100418408Y7130002",
"system": "phone",
"value": "01234 567 878",
"use": "home"
},
{
"id": "20240603100418408u9zX0003",
"system": "sms",
"value": "4771221452",
"use": "home"
}
],
"gender": "male",
"birthDate": "1971-11-23",
"deceasedBoolean": false,
"address": [
{
"id": "202406030914418461lzN0002",
"type": "home",
"text": "123 High Street, Leeds LS1 4HR",
"line": [
"123 High Street, Leeds LS1 4HR"
],
"city": "Leeds",
"postalCode": "LS1 4HR"
},
{
"id": "202406030938219361wDT0005",
"type": "home",
"text": "123 High Street, Leeds LS1 4HR",
"line": [
"123 High Street, Leeds LS1 4HR"
],
"city": "Leeds",
"postalCode": "LS1 4HR"
},
{
"id": "20240603095329680XIKC0007",
"type": "home",
"text": "123 High Street, Leeds LS1 4HR",
"line": [
"123 High Street, Leeds LS1 4HR"
],
"city": "Leeds",
"postalCode": "LS1 4HR"
},
{
"id": "20240603100241079NcIp0001",
"type": "home",
"text": "123 High Street, Leeds LS1 4HR",
"line": [
"123 High Street, Leeds LS1 4HR"
],
"city": "Leeds",
"postalCode": "LS1 4HR"
},
{
"id": "202406031004184271uJe0004",
"type": "home",
"text": "123 High Street, Leeds LS1 4HR",
"line": [
"123 High Street, Leeds LS1 4HR"
],
"city": "Leeds",
"postalCode": "LS1 4HR"
}
]
}
Headers
Authorization, ‘SU-SiteID’ and Version Id headers are mandatory to successfully execute the API. If these headers are not present in the request, then the API returns HTTPStatus code 401 with an error response object.
Error Handling
| HTTP Code | Error Code | Description |
| 400 | MSG_CANT_PARSE_CONTENT | Failed to parse Appointment |
| 400 | MSG_MISSING_MANDATORY_PARAM | Missing Mandatory Parameter |
| 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 invalid |
| 422 | MSG_REFERENCE_ID_NOT_FOUND | Reference ID not found |
| 422 | MSG_DATE_FORMAT | Invalid date format |
Update Patient
The Update Patient API enables submitting an update request for already created Patient in ePX System. Update schedule is not possible if the patient is inactive
End Point
Must be looked up from discovery-document using key update_patient_endpoint
Request
A sample request for updating patient is provided below
curl --location --request PUT '{BASE_URL}/20240521055549710Xj8f0001' \
--header 'Content-Type: application/fhir+json' \
--header 'Authorization: Bearer eyJraWQiOiJ..' \
--header 'SU-SiteId: HC00JIY' \
--data '{
"resourceType": "Patient",
"id": "20240521055549710Xj8f0001",
"extension": [
{
"url": "https://ref.api.healthcode.co.uk/extension/patient/insurer",
"valueString": "ppp"
},
{
"url": "https://ref.api.healthcode.co.uk/extension/patient/registrationid",
"valueString": "THI002934G"
},
{
"url": "https://ref.api.healthcode.co.uk/extension/patient/authorizationno",
"valueString": "ATH03394"
}
],
"name": [
{
"family": "SmithKL",
"given": [
"John"
],
"prefix": [
"Mr"
]
}
],
"telecom": [
{
"system": "phone",
"value": "01234 567 8781",
"use": "home"
}
],
"gender": "male",
"birthDate": "1975-11-23",
"address": [
{
"type": "home",
"text": "123 High Street, Leeds1 LS1 4HR",
"line": [
"123 High Street, Leeds1"
],
"city": "Leeds",
"postalCode": "LS1 4HR"
}
]
}
Headers
Authorization, ‘SU-SiteID’ and Version Id headers are mandatory to successfully execute the API. If these headers are not present in the request, then the API returns HTTPStatus code 401 with an error response object.
Response Processing
On successful update of the patient the API will return the updated patient resource.
{
"resourceType": "Patient",
"id": "20240521055549710Xj8f0001",
"extension": [
{
"url": "https://ref.api.healthcode.co.uk/extension/patient/insurer",
"valueString": "ppp"
},
{
"url": "https://ref.api.healthcode.co.uk/extension/patient/registrationid",
"valueString": "THI002934G"
},
{
"url": "https://ref.api.healthcode.co.uk/extension/patient/authorizationno",
"valueString": "ATH03394"
}
],
"name": [
{
"family": "SmithKL",
"given": [
"John"
],
"prefix": [
"Mr"
]
}
],
"telecom": [
{
"system": "phone",
"value": "01234 567 8781",
"use": "home"
}
],
"gender": "male",
"birthDate": "1975-11-23",
"address": [
{
"type": "home",
"text": "123 High Street, Leeds1 LS1 4HR",
"line": [
"123 High Street, Leeds1"
],
"city": "Leeds",
"postalCode": "LS1 4HR"
}
]
}
Error Handling
| HTTP Code | Error Code | Description |
422 | REFERENCE_NOT_FOUND | Referenced resource not found. |
422 | INVALID_RESOURCE | Submitted resource is not valid. |
422 | MISSING_MANDATORY_ELEMENT | Mandatory element missing. |
422 | INVALID_EXTENSION | Submitted extension is not valid. |
422 | INVALID_REFERENCE | Reference used is invalid. |
Delete Patient
The Delete Patient API allows to remove an existing Patient record from the system
End Point
Must be looked up from discovery-document using key delete_patient_endpoint
Request
Delete patient request passed as below.
curl --location --request DELETE '{BASE_URL}/patient/{PATIENT_ID}' \
--header 'Content-Type: application/fhir+json' \
--header 'Authorization: Bearer eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMy..' \
--header 'SU-SiteId: HC00JIY' \
--data ''Where
| Field | Type | Description |
| patientid | String | Patient id that must be deleted. |
Headers
Authorization, ‘SU-SiteID’ and Version Id headers are mandatory to successfully execute the API. If these headers are not present in the request, then the API returns HTTPStatus code 401 with an error response object.
Response Processing
On successful deletion of patient, status of the operation is returned using parameters resource as response to API.
{
"resourceType": "Parameters",
"parameter": [
{
"name": "Status",
"valueString": "DELETED"
}
]
}
Add Condition with attachment
The Create Condition API enables adding a condition to existing patient resource. This resource can reference to the corresponding patient condition images within the resource to add them as attachments against the condition and patient. Notes corresponding to the condition can also be added in he resource.
Note that, patient should already exist in ePX system before calling this API as patientId is referred in this resource
End Point
Must be looked up from discovery-document using key create_condition_endpoint
Request
A sample request to create condition is provided below
curl --location 'https://{BASE_URL}/patient/condition' \
--header 'Content-Type: application/fhir+json' \
--header 'Authorization: Bearer eyJraWQiOiJyc…' \
--header 'SU-SiteId: HC00JIY' \
--data ' {
"resourceType": "Condition",
"evidence": [
{
"detail": [
{
"display":"THPAJ51UES.pdf",
"identifier": {
"id": "08d1cc39-0d7f-4b72-9100-763865c31675",
"system": "MSDS3",
"value": "documenbase/08d1cc39-0d7f-4b72-9100-763865c31675/THPAJ51UES.pdf"
}
}
]
}
],
"note": [
{
"text": " notes for smit via FHIR API",
"authorReference": [
{
"reference": "patient/{PatientId}"
}
]
}
]
}
Headers
Authorization, ‘SU-SiteID’ and Version Id headers are mandatory to successfully execute the API. If these headers are not present in the request, then the API returns HTTPStatus code 401 with an error response object.
Response Processing
On successful creation of the condition the API will return unique identifier for the new condition.
The API returns the newly created condition in JSON format.
{
"resourceType": "Condition",
"id": "VlyO5SYDU0Vv9SpqDj8lamYyG",
"evidence": [
{
"detail": [
{
"reference": "Docs/ePxDocs/HC14308/Patients/20240603091441535eR1s0001/Notes/03062024",
"identifier": {
"id": "Pf1uH0QHx1un5G9GuMGa7sXIj",
"system": "S3/image",
"value": "Docs/ePxDocs/HC14308/Patients/20240603091441535eR1s0001/Notes/03062024"
},
"display": "237fa840-98b4-4470-a7f6-8bf5081d41002123732429635278776.jpg"
}
]
}
],
"note": [
{
"authorReference": {
"reference": "patient/20240603091441535eR1s0001"
},
"text": " notes for smit via FHIR API"
}
]
}
Error Handling
| HTTP Code | Error Code | Description |
| 400 | MSG_CANT_PARSE_CONTENT | Failed to parse Appointment |
400 | MSG_MISSING_MANDATORY_PARAM | Missing Mandatory Parameter |
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 invalid |
422 | MSG_REFERENCE_ID_NOT_FOUND | Reference ID not found |
422 | MSG_DATE_FORMAT | Invalid date format |
Below are the fields of condition resource which are supported in the response.
| DataType | Occ | Description | FHIR Field |
| String | 0-1 | Condition evidence | condition.evidence |
| String | 1-1 | notes | condition.note |
| String | 1-1 | Text for notes | condition.notes[].text |
| String | 1-1 | Patient reference for notes | Condition.note[].authorReference |
| String | 1-1 | Details of evidence | Condition.evidence.detail |
| String | 1-1 | Name of attachment | Condition.evidence.detail[].display |
| String | 1-1 | Attachment details | Condition.evidence.detail[].identifier |
| String | 1-1 | Identifier of attachment | Condition.evidence.detail[].identifier.id |
| String | 1-1 | Identifier for the Source system of the attachment | Condition.evidence.detail[].identifier.system |
| String | 1-1 | URL of the attachment | Condition.evidence.detail[].identifier.value |
Delete Patient Condition
The Delete Patient Condition API allows to remove an existing Patient Condition record from the system
End Point
Must be looked up from discovery-document using key delete_patient_condition_endpoint
Request
Delete patient request passed as below.
curl --location --request DELETE '{BASE_URL}/patient/condition/IRDRjnT5ltjlY51sLo7PxdMZD
--header 'Content-Type: application/fhir+json' \
--header 'Authorization: Bearer eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMy..' \
--header 'SU-SiteId: HC00JIY' \
--data ''Where
| Field | Type | Description |
| conditionid | String | Patient id that must be deleted. |
Headers
Authorization, ‘SU-SiteID’ and Version Id headers are mandatory to successfully execute the API. If these headers are not present in the request, then the API returns HTTPStatus code 401 with an error response object.
Response Processing
On successful deletion of patient condition, status of the operation is returned using parameters resource as response to API.
{
"resourceType": "Parameters",
"parameter": [
{
"name": "Status",
"valueString": "DELETED"
}
]
}