The Authorisation APIs bundle exposes APIs to enable membership enquiry.
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.
Coverage
The Coverage resource is used to provide information about the membership details of a patient for a particular insurer. Following APIs enable operating against the resource.
Find Member
The Find Member API enables searching for membership details using different filter criteria.
Endpoint
Must be looked up from the discovery document using key find_member_endpoint.
Request
Please note, this API uses HTTP POST method and accepts url-encoded key value pairs in request body. A sample POST request for this API is provided below. The insurerIdentifier is a mandatory parameter and depending upon the insurer all other parameters can be mandatory or optional which is documented here.
curl --request POST
--url '{find_member_endpoint}'?
--header 'SU-SiteId: HC12393'
--header 'Content-Type: application/x-www-form-urlencoded'
--header 'Authorization: Bearer abCdE12...89mNopq0r'
--data-urlencode 'insurerIdentifier=bup'
--data-urlencode 'firstName=S'
--data-urlencode 'lastName=Gray'
--data-urlencode 'sex=Male'
--data-urlencode 'dateOfbirth=1998-08-08'
--data-urlencode 'postCode=BT43%207BU'
--data-urlencode 'membershipNumber=002WMQ'
--data-urlencode 'groupId=015T6W'
--data-urlencode 'policyActiveOn=2023-09-25'Where,
| Field | Type | Description |
|---|---|---|
| insurerIdentifier | String | Insurer’s identifier. Following are the supported insurers and its identifiers: Bupa = bup AXA Health = ppp Aviva = nuh Vitality Health = slh Cigna Healthcare = cig Trust in Health = tih |
| firstInitial | String | Member’s first initial |
| lastName | String | Member’s last name |
| sex | String | Member’s gender |
| dateOfBirth | String | Member’s date of birth |
| postCode | String | Member’s postal code |
| membershipNumber | String | Insurers unique identifier for the member |
| groupId | String | Identifier for this member’s policy, where the member is part of a group policy |
| policyActiveOn | String | Date to check if policy is active or not |
Response
The API returns a Coverage resource if a single match is found. In case of no match or multiple matches the API will return OperationOutcome resource.
{
"resourceType": "Coverage",
"id": "101",
"contained": [
{
"resourceType": "Patient",
"id": "1",
"extension": [
{
"url": "https://ref.api.healthcode.co.uk/extension/otherInitials",
"valueString": "P"
},
{
"url": "https://ref.api.healthcode.co.uk/extension/genderIdentity",
"valueString": "male"
}
],
"name": [
{
"family": "Gray",
"given": [
"Stuart"
]
}
],
"gender": "male",
"birthDate": "1998-08-08",
"address": [
{
"line": [
"10 Downing Street"
],
"city": "London",
"district": "Westminster",
"state": "England",
"postalCode": "SW1A 2AA",
"country": "United Kingdom"
}
]
},
{
"resourceType": "Organization",
"id": "2",
"name": "Bupa",
"telecom": [
{
"system": "email",
"value": "bupa@support.com"
},
{
"system": "phone",
"value": "447488803755"
}
]
}
],
"extension": [
{
"url": "https://ref.api.healthcode.co.uk/extension/doNotReject",
"valueString": "No"
},
{
"url": "https://ref.api.healthcode.co.uk/extension/currency",
"valueString": "GBP"
},
{
"url": "https://ref.api.healthcode.co.uk/extension/memberCoPayment",
"valueMoney": {
"value": 50
}
},
{
"url": "https://ref.api.healthcode.co.uk/insuranceSchemePlan",
"valueString": "Key"
},
{
"url": "https://ref.api.healthcode.co.uk/extension/policyExpired",
"valueString": "Yes"
},
{
"url": "https://ref.api.healthcode.co.uk/extension/expiryDate",
"valueDateTime": "2022-01-01T00:00:00+05:30"
},
{
"url": "https://ref.api.healthcode.co.uk/extension/groupId",
"valueString": "015T6W"
},
{
"url": "https://ref.api.healthcode.co.uk/extension/benefitLimit",
"valueMoney": {
"value": 1000
}
},
{
"url": "https://ref.api.healthcode.co.uk/extension/benefitUsed",
"valueMoney": {
"value": 250
}
},
{
"url": "https://ref.api.healthcode.co.uk/extension/benefitUsedAsOf",
"valueDateTime": "2023-08-03T00:00:00+05:30"
},
{
"url": "https://ref.api.healthcode.co.uk/extension/memberExcess",
"valueMoney": {
"value": 100
}
},
{
"url": "https://ref.api.healthcode.co.uk/extension/excessUsed",
"valueMoney": {
"value": 50
}
},
{
"url": "https://ref.api.healthcode.co.uk/extension/excessUsedAsOf",
"valueDateTime": "2023-08-03T00:00:00+05:30"
},
{
"url": "https://ref.api.healthcode.co.uk/extension/memberExcessType",
"valueString": "Each Claim/Episode"
},
{
"url": "https://ref.api.healthcode.co.uk/extension/memberCoPaymentType",
"valueString": "Monetary Value"
}
],
"identifier": [
{
"id": "membershipNumber",
"value": "002WMQ"
}
],
"beneficiary": {
"reference": "#1"
},
"period": {
"start": "2023-08-01T00:00:00+05:30",
"end": "2023-12-03T00:00:00+05:30"
},
"payor": [
{
"reference": "#2"
}
]
}Where,
| Name | Type | Card. | Description | FHIR Field |
|---|---|---|---|---|
| Coverage ID | Id | 1-1 | Coverage ID | Coverage.id |
| Given Name | String | 1-1 | Member’s given or first name | Coverage.contained.Patient.name.given |
| Family Name | String | 1-1 | Member’s family or last name | Coverage.contained.Patient.name.family |
| Gender | Code | 1-1 | Member’s sex at birth | Coverage.contained.Patient.gender |
| Birth Date | Date | 1-1 | Member’s date of birth | Coverage.contained.Patient.birthDate |
| Address | Address | 1-1 | Member’s address which contains line, city, district, state, postalCode and country fields | Coverage.contained.Patient.address |
| Gender Identity | String | 0-1 | The gender by which the member prefers to be identified | Coverage.contained.Patient.extension.valueString – genderIdentity |
| Other Initials | String | 0-1 | Member’s other initials | Coverage.contained.Patient.extension.valueString – otherInitials |
| Insurer Name | String | 1-1 | Insurer’s name | Coverage.contained.Organization.name |
| ContactPoint | 0-1 | Insurer’s email | Coverage.contained.Organization.telecom.email | |
| Phone | ContactPoint | 0-1 | Insurer’s phone number | Coverage.contained.Organization.telecom.phone |
| Insurer Identifier | Identifier | 1-1 | Insurer’s unique identifier for this member | Coverage.identifier |
| Start | DateTime | 1-1 | The date on which the cover for this member starts | Coverage.period.start |
| End | DateTime | 1-1 | The date on which the cover for this member ends | Coverage.period.end |
| Group ID | String | 0-1 | Identifier for this member’s policy, where the member is part of a group policy | Coverage.extension.valueString – groupId |
| Policy Expired | String | 1-1 | Indicates policy expiry status. Expected value is either ‘Yes’ or ‘No’ | Coverage.extension.valueString – policyExpired |
| Expiry Date | Date | 0-1 | The date on which cover expired | Coverage.extension.valueDate – expiryDate |
| Cover Type | String | 0-1 | Policy scheme to which group/member belongs | Coverage.extension.valueString – coverType |
| Benefit Limit | Money | 0-1 | The maximum benefit available to the member on this policy | Coverage.extension.valueMoney – benefitLimit |
| Benefit Used | Money | 0-1 | The amount of benefit already used by this member on this policy | Coverage.extension.valueMoney – benefitUsed |
| Benefit Used As Of | DateTime | 0-1 | The date/time on which the consumed benefit amount was calculated | Coverage.extension.valueDateTime – benefitUsedAsOf |
| Member Excess | Money | 0-1 | The excess amount to be paid by the member on this policy | Coverage.extension.valueMoney – memberExcess |
| Member Excess Type | String | 0-1 | The period over which the excess amount is applicable. Expected value is either ‘Policy period’ or ‘Each Claim/Episode’ | Coverage.extension.valueString – memberExcessType |
| Excess Used | Money | 0-1 | The excess amount already paid by the member on this policy | Coverage.extension.valueMoney – excessUsed |
| Excess Used As Of | DateTime | 0-1 | The date/time on which the paid excess was calculated | Coverage.extension.valueDateTime – excessUsedAsOf |
| Member CoPayment | Money or Decimal | 0-1 | The amount to be paid by the member under any policy co-payment arrangement. This will return valueMoney object if value is supplied as ‘Monetary value’ by insurer or it will return valueDecimal object if the value is supplied as ‘Percentage’ by insurer | Coverage.extension.valueMoney – memberCoPayment OR Coverage.extension.valueDecimal – memberCoPayment |
| Member CoPayment Type | String | 0-1 | The type in which the copayment value is supplied by insurer. Expected value is either ‘Monetary value’ or ‘Percentage’ | Coverage.extension.valueString – memberCoPaymentType |
| Currency | String | 0-1 | Currency code for the monetary values | Coverage.extension.valueString – currency |
Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | NO_MATCH_FOUND | No match found for search parameter |
| 400 | MULTIPLE_MATCH_FOUND | Multiple match found for search parameters |
| 400 | MSG_MISSING_MANDATORY_PARAM | Missing mandatory parameter |
| 422 | MSG_PARAM_INVALID | Parameter content is invalid |
| 400 | MSG_CANT_PARSE_CONTENT | Unprocessable Entity |
| 500 | MSG_DATABASE_ERROR | Failed processing entity in Database |
Please note that the HTTP Code 400 for NO_MATCH_FOUND and MULTIPLE_MATCH_FOUND is a deviation from the empty resultset as specified here within general-overview part of API Docs, but is intentional to keep the handling consistent between NO_MATCH_FOUND and MULTIPLE_MATCH_FOUND.
PreAuth
PreAuth is defined by a Claim FHIR resource that contains Pre-Authorisation details. ‘preauthorization‘ will be used within the Claim resource ‘use’ field to indicate it is a Pre-Authorisation resource. The following APIs enable operating against this resource.
Search Authorisation
The Search Authorisation API enables the caller to retrieve a list of authorisations based on search criteria.
Endpoint
Must be looked up from the discovery document using key search_authorisation_endpoint.
Request
curl --request POST
--url '{search_authorisation_endpoint}' \
--header 'SU-SiteId: HC14420' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer abCdE12...89mNopq0r' \
--header 'Cookie: id=75B8D80E77CCFDEE7F1D88F6AA8135A2' \
--data-urlencode 'membershipNumber=TG176A1' \
--data-urlencode 'page=1' \
--data-urlencode 'count=10' \
--data-urlencode 'caseId=202412021650374711Vf20123'
--data-urlencode 'authCode=AUTH3021430'
--data-urlencode 'issueDate=2024-12-02' \
--data-urlencode '_sort=issueDate' \
--data-urlencode 'insurerIdentifier=tih' \
--data-urlencode 'status=unread' \
--data-urlencode 'preAuthStatus=active'Where,
| Field | Type | Mandatory/ Optional | Description |
|---|---|---|---|
| insurerIdentifier | String | O | Insurer’s identifier. The following are supported insurers and identifiers: Aviva = nuh Vitality Health = slh Trust in Health = tih |
| issueDate | String | O | Authorisation issue date |
| caseId | String | O | Authorisation Case ID |
| authCode | String | O | Authorisation code |
| status | String | O | Read/Unread status for an authorisation record |
| preAuthStatus | String | O | The preAuthStatus indicates the authorisation’s current state. It can be one of the following: Active, Closed, Cancelled, or All (representing all statuses) |
| membershipNumber | String | O | Insurers unique identifier for the member |
| _sort | String | O | Sort results by issue date. Use _sort=issueDate to sort results on issue date in ascending order, or _sort=-issueDate for descending order |
| _since | String | O | Last updated date time of records |
| page | String | O | Page index to be fetched {1,2,3..} |
| count | String | O | Maximum records in a page |
Response
The API returns a Bundle of Claim resources based on the search filters.
{
"resourceType": "Bundle",
"meta": {
"tag": [
{
"code": "page",
"display": "1"
},
{
"code": "count",
"display": "10"
},
{
"code": "maxCount",
"display": "1"
}
]
},
"type": "collection",
"total": 1,
"entry": [
{
"resource": {
"resourceType": "Claim",
"id": "20241202165037557gRKT0124",
"extension": [
{
"url": "https://policies.api.healthcode.co.uk/extension/authCode",
"valueString": "AUTH3021430"
},
{
"url": "https://policies.api.healthcode.co.uk/extension/lastUpdatedOn",
"valueDateTime": "2024-12-02T16:50:37+00:00"
},
{
"url": "https://policies.api.healthcode.co.uk/extension/issueDate",
"valueDateTime": "2024-12-02T16:50:37+00:00"
},
{
"url": "https://policies.api.healthcode.co.uk/extension/insurerIdentifier",
"valueString": "tih"
},
{
"url": "https://policies.api.healthcode.co.uk/extension/isRead",
"valueBoolean": false
},
{
"url": "https://policies.api.healthcode.co.uk/extension/status",
"valueString": "ACTIVE"
}
],
"identifier": [
{
"system": "https://policies.api.healthcode.co.uk/caseId",
"value": "202412021650374711Vf20123"
},
{
"system": "https://policies.api.healthcode.co.uk/membershipNumber",
"value": "TG176A1"
}
],
"use": "preauthorization",
"diagnosis": [
{
"type": [
{
"coding": [
{
"system": "https://ref.api.healthcode.co.uk/diagnosis/ICD9",
"code": "83600",
"display": "DISLOCATION OF KNEE"
}
]
}
]
}
]
}
}
]
}Where,
| Name | Type | Card. | Description | FHIR Field |
|---|---|---|---|---|
| Id | Id | 1-1 | Authorisation ID | Claim.id |
| Use | Code | 1-1 | Code to indicate an authorisation resource | Claim.use |
| Case ID | String | 0-1 | Authorisation Case ID | Claim.identifier.value – caseId |
| Membership Number | String | 1-1 | Insurer’s unique identifier for this member | Claim.identifier.value – membershipNumber |
| Diagnosis | CodeableConcept | 1-1 | The condition for which the treatment(s) are being provided and response includes diagnosis scheme, code and name | Claim.diagnosis.type.coding |
| Auth Code | String | 1-1 | Authorisation identifier allocated by the insurer | Claim.extension.valueString – authCode |
| Insurer Identifier | String | 1-1 | Insurer identifier | Claim.extension.valueString – insurerIdentifier |
| Is Read | Boolean | 0-1 | Read/Unread status for an authorisation record | Claim.extension.valueBoolean – isRead |
| Status | String | 0-1 | The status indicates the authorisations current state | Claim.extension.valueString – status |
| Last Updated On | DateTime | 0-1 | Authorisation last updated date time | Claim.extension.valueDateTime – lastUpdatedOn |
| Issue Date | DateTime | 0-1 | Authorisation issued date | Claim.extension.valueDateTime – issueDate |
Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | MSG_PARAM_EMPTY | Parameter is null/empty |
| 422 | MSG_PARAM_INVALID | Parameter content is invalid |
| 422 | MSG_DATE_FORMAT | Invalid date format |
| 400 | MSG_CANT_PARSE_CONTENT | Unprocessable Entity |
| 500 | MSG_DATABASE_ERROR | Failed processing entity in Database |
Get Authorisation
The Get Authorisation API enables the caller to retrieve authorisation details with a known authorisation ID.
Endpoint
Must be looked up from the discovery document using key get_authorisation_endpoint.
Request
curl --request GET
--url '{get_authorisation_endpoint}/{authorisationId}'?
--header 'SU-SiteId: HC14420'
--header 'Content-Type: application/fhir+json'
--header 'Authorization: Bearer abCdE12...89mNopq0r'Where,
| Field | Type | Mandatory/ Optional | Description |
|---|---|---|---|
| authorisationId | String | M | Authorisation ID |
Response
The API returns a Claim resource which contains the required authorisation details.
{
"resourceType": "Claim",
"id": "20241202170546078SbV00138",
"contained": [
{
"resourceType": "Coverage",
"contained": [
{
"resourceType": "Organization",
"id": "PR00009D",
"identifier": [
{
"system": "https://policies.api.healthcode.co.uk/insurerIdentifier",
"value": "tih"
}
],
"name": "Trust In Health",
"telecom": [
{
"system": "email",
"value": "preauth@trustinhealth.co.uk"
}
]
},
{
"resourceType": "Patient",
"name": [
{
"family": "Gray",
"given": [
"Stuart"
]
}
],
"gender": "male",
"birthDate": "1998-08-08",
"address": [
{
"line": [
"10 Downing Street"
],
"city": "London",
"district": "Westminster",
"state": "England",
"postalCode": "SW1A 2AA",
"country": "United Kingdom"
}
]
}
],
"extension": [
{
"url": "https://policies.api.healthcode.co.uk/extension/groupPolicyId",
"valueString": "CS098C1"
},
{
"url": "https://policies.api.healthcode.co.uk/extension/policyScheme",
"valueString": "PLMDZI5I-Standard"
}
],
"period": {
"start": "2021-09-09T00:00:00+00:00",
"end": "2026-08-06T00:00:00+00:00"
}
}
],
"extension": [
{
"url": "https://policies.api.healthcode.co.uk/extension/status",
"valueString": "ACTIVE"
},
{
"url": "https://policies.api.healthcode.co.uk/extension/issueDate",
"valueDateTime": "2024-12-02T17:05:45+00:00"
},
{
"url": "https://policies.api.healthcode.co.uk/extension/authCode",
"valueString": "AUTH5580122"
},
{
"valueCodeableConcept": {
"coding": [
{
"extension": [
{
"url": "https://policies.api.healthcode.co.uk/extension/createdon",
"valueDateTime": "2024-12-02T17:51:52+00:00"
},
{
"url": "https://policies.api.healthcode.co.uk/extension/userName",
"valueString": "Mr. William Halstead"
}
],
"system": "https://policies.api.healthcode.co.uk/extension/note",
"display": "Recovery time depends on the Patient, Age and other factors"
}
]
}
}
],
"identifier": [
{
"system": "https://policies.api.healthcode.co.uk/caseId",
"value": "202412021705460201SxB0137"
},
{
"system": "https://policies.api.healthcode.co.uk/membershipNumber",
"value": "TG176A1"
}
],
"use": "preauthorization",
"diagnosis": [
{
"type": [
{
"coding": [
{
"system": "https://ref.api.healthcode.co.uk/diagnosis/ICD9",
"code": "83600",
"display": "DISLOCATION OF KNEE"
}
]
}
]
}
],
"item": [
{
"id": "202412021705460801ndg0140",
"extension": [
{
"url": "https://policies.api.healthcode.co.uk/extension/decision",
"valueString": "PENDING"
},
{
"url": "https://policies.api.healthcode.co.uk/extension/episodeSetting",
"valueString": "Inpatient"
},
{
"url": "https://policies.api.healthcode.co.uk/extension/laterality",
"valueString": "Bilateral"
},
{
"url": "https://policies.api.healthcode.co.uk/extension/firstDateOfService",
"valueDateTime": "2024-12-02T00:00:00+00:00"
},
{
"url": "https://policies.api.healthcode.co.uk/extension/lastDateOfService",
"valueDateTime": "2024-12-04T00:00:00+00:00"
},
{
"url": "https://policies.api.healthcode.co.uk/extension/inpatientNights",
"valueInteger": 2
},
{
"valueCodeableConcept": {
"coding": [
{
"system": "https://policies.api.healthcode.co.uk/extension/service",
"code": "20241202164143143Zmt70122",
"display": "Orthopedic Services"
}
]
}
},
{
"valueCodeableConcept": {
"coding": [
{
"id": "20241202170546080cEJo0141",
"extension": [
{
"url": "https://policies.api.healthcode.co.uk/extension/decision",
"valueString": "PENDING"
}
],
"system": "https://ref.api.healthcode.co.uk/procedure/9BUPP",
"code": "AA658",
"display": "Knee brace(s)"
}
]
}
},
{
"valueCodeableConcept": {
"coding": [
{
"id": "202412021705460811dnT0143",
"extension": [
{
"url": "https://policies.api.healthcode.co.uk/extension/decision",
"valueString": "PENDING"
}
],
"system": "https://ref.api.healthcode.co.uk/location",
"code": "HP003631",
"display": "Rainbow Orthopedic Care"
}
]
}
},
{
"valueCodeableConcept": {
"coding": [
{
"id": "202412021705460806Ciz0142",
"extension": [
{
"url": "https://policies.api.healthcode.co.uk/extension/decision",
"valueString": "PENDING"
}
],
"system": "https://ppr.api.healthcode.co.uk/practitioner",
"code": "SP038687",
"display": "Doctor God'Swill Etokowo"
}
]
}
},
{
"url": "https://policies.api.healthcode.co.uk/extension/consolidatedStatus",
"valueString": "PENDING"
}
]
}
]
}Where,
| Name | Type | Card. | Description | FHIR Field |
|---|---|---|---|---|
| Id | Id | 1-1 | Authorisation ID | Claim.id |
| Use | Code | 1-1 | Code to indicate an authorisation resource | Claim.use |
| Case ID | String | 0-1 | Authorisation Case ID | Claim.identifier.value – caseId |
| Membership Number | String | 1-1 | Insurer’s unique identifier for this member | Claim.identifier.value – membershipNumber |
| Diagnosis | CodeableConcept | 1-1 | The condition for which the treatment(s) are being provided and response includes diagnosis scheme, code and name | Claim.diagnosis.type.coding |
| Auth Code | String | 1-1 | Authorisation identifier allocated by the insurer | Claim.extension.valueString – authCode |
| Status | String | 1-1 | Indicates authorisation status | Claim.extension.valueString – status |
| Package | String | 0-1 | Indicates whether authorisation includes a packaged treatment | Claim.extension.valueString – package |
| Claim Number | String | 0-1 | Claim number | Claim.extension.valueString – claimNumber |
| Issue Date | DateTime | 1-1 | The date on which the authorisation was issued | Claim.extension.valueString – issueDate |
| Industry Standard Code | CodeableConcept | 1-1 | The actual service for which the authorisation belongs to and response includes industry standard scheme, code and name | Claim.item.extension.valueCodeableConcept.coding |
| Episode Setting | String | 1-1 | The episode setting of a given service. Expected values are Inpatient, Outpatient, Daycase | Claim.item.extension.valueString – episodeSetting |
| Decision | String | 1-1 | The decision for a given service. Expected values are Approved, Declined, Pending | Claim.item.extension.valueString – decision |
| Authorised From | DateTime | 1-1 | The start date for which authorisation of the given service is valid | Claim.item.extension.valueDateTime – authorisedFrom |
| Authorised To | DateTime | 1-1 | The end date for which authorisation of the given service is valid | Claim.item.extension.valueDateTime – authorisedTo |
| First Date of Service | DateTime | 0-1 | The start date of actual treatment | Claim.item.extension.valueDateTime – firstDateOfService |
| Last Date of Service | DateTime | 0-1 | The end date of actual treatment | Claim.item.extension.valueDateTime – lastDateOfService |
| Inpatient Nights | Integer | 0-1 | Number of inpatient nights. This value will be available only if episode setting is set to inpatient | Claim.item.extension.valueInteger – inpatientNights |
| Location | CodeableConcept | 1-* | The location or treatment site where the service may be provided and response includes HP number and name of the location | Claim.item.extension.valueCodeableconcept.coding |
| Decision | String | 1-1 | The decision for a given location. Expected values are Approved, Declined, Pending | Claim.item.extension.valueCodeableconcept.coding.extension.valueString – decision |
| Insurer Provider Code | String | 1-1 | The insurer provider code for the given location | Claim.item.extension.valueCodeableconcept.coding.extension.valueString – insurerProviderCode |
| Practitioner | CodeableConcept | 1-* | The practitioner or specialist authorised to carry out the treatment and response includes SP number and name of the practitioner | Claim.item.extension.valueCodeableconcept.coding |
| Decision | String | 1-1 | The decision for a given practitioner. Expected values are Approved, Declined, Pending | Claim.item.extension.valueCodeableconcept.coding.extension.valueString – decision |
| Insurer Provider Code | String | 1-1 | The insurer provider code for the given practitioner | Claim.item.extension.valueCodeableconcept.coding.extension.valueString – insurerProviderCode |
| Procedure | CodeableConcept | 0-* | The procedure code is expected to be carried out as part of the service and response includes procedure scheme, code and name | Claim.item.extension.valueCodeableconcept.coding |
| Service | CodeableConcept | 1-1 | The service is expected to be carried out as part of the service and response includes code. This is Manage preauth service which was created by insurer | Claim.item.extension.valueCodeableconcept.coding |
| Decision | String | 1-1 | The decision for a given procedure. Expected values are Approved, Declined, Pending | Claim.item.extension.valueCodeableconcept.coding.extension.valueString – decision |
| Note | CodeableConcept | 0-* | The notes related to the authorisation | Claim.extension.valueCodeableconcept.coding |
| Created On | DateTime | 1-1 | The date on which the note was added | Claim.item.extension.valueCodeableconcept.coding.extension.valueDateTime |
| Insurer | Resource | 1-1 | This resource includes insurer’s id, identifier and name related to the given authorisation | Claim.contained.Coverage.contained.Organization |
| Member | Resource | 1-1 | This resource includes member details like name, gender, date of birth and address | Claim.contained.Coverage.contained.Patient |
| Consolidated Status | String | 0-1 | The status is determined by decisions on the service, procedure, location, and practitioner. It will be Approved if all decisions are approved, Rejected if any decision is declined, and Pending if at least one decision is pending without any declines. | Claim.item.extension.valueString – consolidatedStatus |
Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | MSG_PARAM_EMPTY | Parameter is null/empty |
| 422 | MSG_PARAM_INVALID | Parameter content is invalid |
| 400 | MSG_MISSING_MANDATORY_PARAM | Missing mandatory parameter |
| 400 | INVALID_RESOURCE | Unprocessable Entity |
| 500 | MSG_DATABASE_ERROR | Failed processing entity in Database |
Request or Create Authorisation
The Request or Create Authorisation API allows the caller to create a new authorisation either under an existing case or a new case. If the caller is a provider, they can request authorisation, while if the caller is an insurer, they can create the authorisation.
Endpoint
Must be looked up from the discovery document using key create_authorisation_endpoint.
Request for Providers
curl --request POST
--url '{create_authorisation_endpoint}'
--header 'SU-SiteId: HC14420'
--header 'Content-Type: application/fhir+json'
--header 'Authorization: Bearer eyJraWQi......xIiwiYW
--data '{
"resourceType": "Claim",
"contained": [
{
"resourceType": "Coverage",
"contained": [
{
"resourceType": "Organization",
"id": "PR00009D",
"identifier": [
{
"id": "insurerIdentifier",
"value": "tih"
}
]
},
{
"resourceType": "Patient",
"name": [
{
"family": "Gray",
"given": [
"Stuart"
]
}
],
"gender": "male",
"birthDate": "1995-11-20",
"address": [
{
"line": [
"10 Downing Street"
],
"city": "London",
"district": "Westminster",
"state": "England",
"postalCode": "SW1A 2AA",
"country": "United Kingdom"
}
]
}
],
"extension": [
{
"id": "groupPolicyId",
"valueString": "CS098C1"
},
{
"id": "policyScheme",
"valueString": "PLMDZI5I-Standard"
}
],
"period": {
"start": "2021-09-09T00:00:00+00:00",
"end": "2026-08-06T00:00:00+00:00"
}
}
],
"extension": [
{
"id": "package",
"valueString": "Yes"
},
{
"valueCodeableConcept": {
"coding": [
{
"id": "note",
"display": "Recommended - water therapy for knee pain"
}
]
}
}
],
"identifier": [
{
"id": "membershipNumber",
"value": "TG176A1"
},
{
"id": "caseId",
"value": "202412021650374711Vf20123"
}
],
"diagnosis": [
{
"type": [
{
"coding": [
{
"id": "diagnosis",
"system": "ICD009",
"code": "TBF23"
}
]
}
]
}
],
"item": [
{
"extension": [
{
"id": "episodeSetting",
"valueString": "I"
},
{
"id": "laterality",
"valueString": "B"
},
{
"id": "firstDateOfService",
"valueDate": "2024-12-02"
},
{
"id": "lastDateOfService",
"valueDate": "2024-12-04"
},
{
"id": "inpatientNights",
"valueInteger": 2
},
{
"valueCodeableConcept": {
"coding": [
{
"id": "service",
"code": "20241202164143143Zmt70122"
}
]
}
},
{
"valueCodeableConcept": {
"coding": [
{
"id": "procedure",
"system": "9BUPP",
"code": "AA658"
}
]
}
},
{
"valueCodeableConcept": {
"coding": [
{
"id": "location",
"code": "HP003631"
}
]
}
},
{
"valueCodeableConcept": {
"coding": [
{
"id": "practitioner",
"code": "SP038687"
}
]
}
}
]
}
]
}'Where,
| Field | Type | Mandatory/ Optional | Description |
|---|---|---|---|
| organization | Resource | M | This resource includes insurer’s id, identifier and name related to the given authorisation |
| patient | Resource | M | This resource includes member details like name, gender, date of birth and address |
| package | String | O | Indicates whether authorisation includes a packaged treatment |
| claimNumber | String | O | The claimNumber in a Claim resource represents the unique identifier assigned to the claim by the insurer. This number is used to track and reference the claim throughout its lifecycle |
| note | CodeableConcept | O | The notes related to the authorisation |
| membershipNumber | String | M | Unique identifier for the member |
| caseId | String | O | Authorisation Case ID |
| diagnosis | CodeableConcept | O | The condition for which the treatment(s) are being provided and response includes diagnosis scheme, code and name |
| decision | String | O | The decision for a given service. Expected values are Approved, Declined, Pending |
| episodeSetting | String | M | The episode setting of a given service. Expected values are Inpatient, Outpatient, Daycase |
| laterality | String | O | Laterality refers to the specification of which side of the body is involved in a medical condition or treatment. Expected values are Unilateral Left, Unilateral Right, Bilateral. |
| authorisedFrom | Date | O | The start date for which authorisation of the given service is valid. |
| authorisedTo | Date | O | The end date for which authorisation of the given service is valid. |
| firstDateOfService | Date | M | The start date of actual treatment. |
| lastDateOfService | Date | M | The end date of actual treatment. |
| inpatientNights | Integer | O | Number of inpatient nights. This value should be available only if episode setting is set to inpatient. In other cases it will be ignored. |
| service | CodeableConcept | M | The service that is expected to be carried out as part of the authorisation and response includes code. This is Manage preauth service which was created by insurer |
| procedure | CodeableConcept | O | The procedure code is expected to be carried out as part of the service and response includes procedure scheme, code and name. |
| location | CodeableConcept | M | The location or treatment site where the service may be provided and response includes HP number and name of the location |
| practitioner | CodeableConcept | O | The practitioner or specialist authorised to carry out the treatment and response includes SP number and name of the practitioner. |
Request for Insurers
curl --request POST
--url '{create_authorisation_endpoint}'
--header 'SU-SiteId: HC14420'
--header 'Content-Type: application/fhir+json'
--header 'Authorization: Bearer eyJraWQi......xIiwiYW
--data '{
"resourceType": "Claim",
"contained": [
{
"resourceType": "Coverage",
"contained": [
{
"resourceType": "Organization",
"id": "PR00009D",
"identifier": [
{
"id":"insurerIdentifier",
"value": "tih"
}
]
},
{
"resourceType": "Patient",
"name": [
{
"family": "Gray",
"given": [
"Stuart"
]
}
],
"gender": "male",
"birthDate": "1995-11-20",
"address": [
{
"line": [
"10 Downing Street"
],
"city": "London",
"district": "Westminster",
"state": "England",
"postalCode": "SW1A 2AA",
"country": "United Kingdom"
}
]
}
],
"extension": [
{
"id":"groupPolicyId",
"valueString": "CS098C1"
},
{
"id":"policyScheme",
"valueString": "PLMDZI5I-Standard"
}
],
"period": {
"start": "2021-09-09T00:00:00+00:00",
"end": "2026-08-06T00:00:00+00:00"
}
}
],
"extension": [
{
"id":"package",
"valueString": "Yes"
},
{
"id":"claimNumber",
"valueString": "UVWX5678"
},
{
"valueCodeableConcept": {
"coding": [
{
"id": "note",
"display": "Recommended - water therapy for knee pain"
}
]
}
}
],
"identifier": [
{
"id":"membershipNumber",
"value": "TG176A1"
},
{
"id":"caseId",
"value": "202412021650374711Vf20123"
}
],"diagnosis": [
{
"type": [
{
"coding": [
{
"id":"diagnosis",
"system": "ICD009",
"code": "83600"
}
]
}
]
}
],
"item": [
{
"extension": [
{
"id":"decision",
"valueString": "APPROVED"
},
{
"id":"episodeSetting",
"valueString": "I"
},
{
"id":"laterality",
"valueString": "B"
},
{
"id":"authorisedFrom",
"valueDate": "2024-12-01"
},
{
"id":"authorisedTo",
"valueDate": "2024-12-20"
},
{
"id":"firstDateOfService",
"valueDate": "2024-12-02"
},
{
"id":"lastDateOfService",
"valueDate": "2024-12-04"
},
{
"id":"inpatientNights",
"valueInteger": 2
},
{
"valueCodeableConcept": {
"coding": [
{
"id":"service",
"code": "05abea7a271c42da98b3a6e07"
}
]
}
},
{
"valueCodeableConcept": {
"coding": [
{
"extension": [
{
"id":"decision",
"valueString": "APPROVED"
}
],
"id":"procedure",
"system": "9BUPP",
"code": "AA658"
}
]
}
},
{
"valueCodeableConcept": {
"coding": [
{
"extension": [
{
"id":"decision",
"valueString": "APPROVED"
}
],
"id":"location",
"code":"HP003631"
}
]
}
},
{
"valueCodeableConcept": {
"coding": [
{
"extension": [
{
"id":"decision",
"valueString": "DECLINED"
}
],
"id":"practitioner",
"code":"SP038687"
}
]
}
}
]
}
]
}'Where,
| Field | Type | Mandatory/ Optional | Description |
|---|---|---|---|
| organization | Resource | M | This resource includes insurer’s id, identifier and name related to the given authorisation |
| patient | Resource | M | This resource includes member details like name, gender, date of birth and address |
| package | String | O | Indicates whether authorisation includes a packaged treatment |
| claimNumber | String | O | The claimNumber in a Claim resource represents the unique identifier assigned to the claim by the insurer. This number is used to track and reference the claim throughout its lifecycle |
| note | CodeableConcept | O | The notes related to the authorisation |
| membershipNumber | String | M | Unique identifier for the member |
| caseId | String | O | Authorisation Case ID |
| diagnosis | CodeableConcept | O | The condition for which the treatment(s) are being provided and response includes diagnosis scheme, code and name |
| decision | String | O | The decision for a given service. Expected values are Approved, Declined, Pending |
| episodeSetting | String | M | The episode setting of a given service. Expected values are Inpatient, Outpatient, Daycase |
| laterality | String | O | Laterality refers to the specification of which side of the body is involved in a medical condition or treatment. Expected values are Unilateral Left, Unilateral Right, Bilateral. |
| authorisedFrom | Date | M | The start date for which authorisation of the given service is valid. |
| authorisedTo | Date | M | The end date for which authorisation of the given service is valid. |
| firstDateOfService | Date | O | The start date of actual treatment. |
| lastDateOfService | Date | O | The end date of actual treatment. |
| inpatientNights | Integer | O | Number of inpatient nights. This value should be available only if episode setting is set to inpatient. In other cases it will be ignored. |
| service | CodeableConcept | M | The service is expected to be carried out as part of the service and response includes code. This is Manage preauth service which was created by insurer |
| procedure | CodeableConcept | O | The procedure code is expected to be carried out as part of the service and response includes procedure scheme, code and name. |
| location | CodeableConcept | M | The location or treatment site where the service may be provided and response includes HP number and name of the location |
| practitioner | CodeableConcept | O | The practitioner or specialist authorised to carry out the treatment and response includes SP number and name of the practitioner. |
Each Authorisation can have multiple item fields within the Claim resource which is used to define services
Response
The API returns a Operation outcome resource which contains the authorisation ID.
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "information",
"code": "informational",
"details": {
"coding": [
{
"system": "https://policies.api.healthcode.co.uk/identifier/authorisation",
"code": "202411251038167521wbF0544",
"display": "MSG_CREATED"
}
]
},
"diagnostics": "authorisation created",
"location": [
"Claim"
],
"expression": []
}
]
}Where,
| Name | Type | Card. | Description | FHIR Field |
|---|---|---|---|---|
| Code | String | 0-1 | The code represents the id of Authorisation | details.coding.code |
Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | MSG_PARAM_EMPTY | Parameter is null/empty |
| 422 | MSG_PARAM_INVALID | Parameter content is invalid |
| 400 | MSG_MISSING_MANDATORY_PARAM | Missing mandatory parameter |
| 400 | INVALID_RESOURCE | Unprocessable Entity |
| 500 | MSG_DATABASE_ERROR | Failed processing entity in Database |
Send Notes & Messages
The Send Notes & Messages API is used to add a note to an existing authorisation.
Endpoint
Must be looked up from the discovery document using key send_authorisation_notes_endpoint.
Request
curl --request PATCH
--url '{send_authorisation_notes_endpoint}/{authorisationId}' \
--header 'Content-Type: application/fhir+json' \
--header 'SU-SiteId: HC14420' \
--header 'Authorization: Bearer abCdE12...89mNopq0r' \
--data '{
"resourceType": "Claim",
"extension": [
{
"valueCodeableConcept": {
"coding": [
{
"id": "note",
"display": "Physical examination findings - Swelling, redness and range of motion limitations"
}
]
}
}
]
}'Where parameters as,
| Field | Type | Description |
| authorisationId | String | Authorisation number |
| SU-SiteId | String | siteid is the site which is mandatory |
| data | String | Data is json format for the notes as extensions |
Response
The API returns Claim resource which includes all the notes for the given authorisation ID.
{
"resourceType": "Claim",
"id": "20241202170546078SbV00138",
"item": [
{
"extension": [
{
"valueCodeableConcept": {
"coding": [
{
"extension": [
{
"url": "https://policies.api.healthcode.co.uk/extension/createdOn",
"valueDateTime": "2024-12-01T19:05:14+00:00"
},
{
"url": "https://policies.api.healthcode.co.uk/extension/username",
"valueString": "Ms. Amelia Whitmore"
}
],
"system": "https://policies.api.healthcode.co.uk/extension/note",
"display": "Any previous knee injuries, surgeries, or medical conditions that might be related ?"
},
{
"extension": [
{
"url": "https://policies.api.healthcode.co.uk/extension/createdOn",
"valueDateTime": "2024-12-01T20:25:14+00:00"
},
{
"url": "https://policies.api.healthcode.co.uk/extension/username",
"valueString": "Mr. William Halstead"
}
],
"system": "https://policies.api.healthcode.co.uk/extension/note",
"display": "Physical examination findings - Swelling, redness and range of motion limitations"
}
]
}
}
]
}
]
}
Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | MSG_PARAM_EMPTY | Parameter is null/empty |
| 422 | MSG_CANT_PARSE_CONTENT | Parameter can not be parsed |
| 400 | MSG_MISSING_MANDATORY_PARAM | Parameter is mandatory |
| 400 | MSG_PARAM_INVALID | In valid parameter |
Get Notes & Messages
The Get Notes & Messages API is used to retrieve notes for a specific authorisation.
Endpoint
Must be looked up from the discovery document using key get_authorisation_notes_endpoint.
Request
curl --request GET
--url '{get_authorisation_note_endpoint}/{authorisationId}' \
--header 'Content-Type: application/fhir+json' \
--header 'SU-SiteId: HC13086' \
--header 'Authorization: Bearer eyJraWQiO...404DC46'
Where parameters as,
| Field | Type | Description |
| authorisationId | String | Authorisation ID |
Response
The API returns Claim resource which includes all the notes for the requested authorisation ID.
{
"resourceType": "Claim",
"id": "20241202170546078SbV00138",
"item": [
{
"extension": [
{
"valueCodeableConcept": {
"coding": [
{
"extension": [
{
"url": "https://policies.api.healthcode.co.uk/extension/createdOn",
"valueDateTime": "2024-12-01T19:05:14+00:00"
},
{
"url": "https://policies.api.healthcode.co.uk/extension/username",
"valueString": "Ms. Amelia Whitmore"
}
],
"system": "https://policies.api.healthcode.co.uk/extension/note",
"display": "Any previous knee injuries, surgeries, or medical conditions that might be related ?"
},
{
"extension": [
{
"url": "https://policies.api.healthcode.co.uk/extension/createdOn",
"valueDateTime": "2024-12-01T20:25:14+00:00"
},
{
"url": "https://policies.api.healthcode.co.uk/extension/username",
"valueString": "Mr. William Halstead"
}
],
"system": "https://policies.api.healthcode.co.uk/extension/note",
"display": "Physical examination findings - Swelling, redness and range of motion limitations"
}
]
}
}
]
}
]
}Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | MSG_PARAM_EMPTY | Parameter is null/empty |
| 422 | MSG_PARAM_INVALID | Parameter content is invalid |
| 400 | MSG_MISSING_MANDATORY_PARAM | Parameter is mandatory |
| 400 | INVALID_RESOURCE | Unprocessable Entity |
Search Condition
The Search Condition API enables the caller to look up the required diagnosis code.
Endpoint
Must be looked up from the discovery document using key search_condition_endpoint.
Request
curl --request POST
--url '{search_condition_endpoint}/' \
--header 'SU-SiteId: HC14420' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer abCdE12...89mNopq0r' \
--data-urlencode 'page=1' \
--data-urlencode 'count=10' \
--data-urlencode 'searchTerm=dislocation' \
--data-urlencode 'sort=-lastUpdatedOn'
Where,
| Field | Type | Mandatory/ Optional | Description |
|---|---|---|---|
| searchTerm | String | O | Partial search based on diagnosis code or description |
| _sort | String | O | Sort results by last updated date. Use _sort=lastUpdatedOn to sort results on issue date in ascending order, or _sort=-lastUpdatedOn for descending order |
| page | String | O | Page index to be fetched {1,2,3..} |
| count | String | O | Maximum records in a page |
Response
The API returns a ValueSet resource which includes filtered diagnosis codes based on search criteria.
{
"resourceType": "ValueSet",
"id": "diagnosis",
"meta": {
"tag": [
{
"code": "page",
"display": "1"
},
{
"code": "count",
"display": "10"
},
{
"code": "maxCount",
"display": "1"
}
]
},
"name": "diagnosis",
"expansion": {
"total": 2,
"contains": [
{
"system": "https://ref.api.healthcode.co.uk/diagnosis/ICD9",
"code": "83600",
"display": "DISLOCATION OF KNEE"
}
]
}
}Where,
| Name | Type | Card. | Description | FHIR Field |
|---|---|---|---|---|
| Code | String | 1-1 | Diagnosis code | ValueSet.expansion.contains.code |
| Display | String | 1-1 | Description of diagnosis code | ValueSet.expansion.contains.display |
| System | String | 1-1 | Diagnosis scheme | ValueSet.expansion.contains.system – {refURL}/diagnosis/{scheme} |
Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | MSG_PARAM_EMPTY | Parameter is null/empty |
| 422 | MSG_PARAM_INVALID | Parameter content is invalid |
| 400 | MSG_MISSING_MANDATORY_PARAM | Parameter is mandatory |
| 400 | INVALID_RESOURCE | Unprocessable Entity |
Search Procedure
The Search Procedure API enables the caller to look up the required procedure code.
Endpoint
Must be looked up from the discovery document using key search_procedure_endpoint.
Request
curl --request POST
--url '{search_procedure_endpoint}/' \
--header 'SU-SiteId: HC14420' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer abCdE12...89mNopq0r' \
--data-urlencode 'page=1' \
--data-urlencode 'count=10' \
--data-urlencode 'searchTerm=knee brace' \
--data-urlencode 'sort=-lastUpdatedOn'
Where,
| Field | Type | Mandatory/ Optional | Description |
|---|---|---|---|
| searchTerm | String | O | Partial search based on procedure code or description |
| _sort | String | O | Sort results by last updated date. Use _sort=lastUpdatedOn to sort results on issue date in ascending order, or _sort=-lastUpdatedOn for descending order |
| page | String | O | Page index to be fetched {1,2,3..} |
| count | String | O | Maximum records in a page |
Response
The API returns a ValueSet resource which includes filtered procedure codes based on search criteria.
{
"resourceType": "ValueSet",
"id": "procedure",
"meta": {
"tag": [
{
"code": "page",
"display": "1"
},
{
"code": "count",
"display": "10"
},
{
"code": "maxCount",
"display": "1"
}
]
},
"name": "procedure",
"expansion": {
"total": 1,
"contains": [
{
"system": "https://ref.api.healthcode.co.uk/procedure/9BUPP",
"code": "AA658",
"display": "Knee brace(s)"
}
]
}
}Where,
| Name | Type | Card. | Description | FHIR Field |
|---|---|---|---|---|
| Code | String | 1-1 | Procedure code | ValueSet.expansion.contains.code |
| Display | String | 1-1 | Description of procedure code | ValueSet.expansion.contains.display |
| System | String | 1-1 | Procedure scheme | ValueSet.expansion.contains.system – {refURL}/procedure/{scheme} |
Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | MSG_PARAM_EMPTY | Parameter is null/empty |
| 422 | MSG_PARAM_INVALID | Parameter content is invalid |
| 400 | MSG_MISSING_MANDATORY_PARAM | Parameter is mandatory |
| 400 | INVALID_RESOURCE | Unprocessable Entity |
Get Episode Setting
The Get Episode Setting API enables the caller to retrieve a list of episode settings.
Endpoint
Must be looked up from the discovery document using key get_episode_setting_endpoint.
Request
curl --request GET
--url '{get_episode_setting_endpoint}?
page=1&
count=10&
isPreauth=true' \
--header 'SU-SiteId: HC14420' \
--header 'Content-Type: application/fhir+json' \
--header 'Authorization: Bearer abCdE12...89mNopq0r'Where,
| Field | Type | Mandatory/ Optional | Description |
|---|---|---|---|
| isPreauth | Boolean | O | This field is used to retrieve episode settings that are specific to the authorisation process |
| page | String | O | Page index to be fetched {1,2,3..} |
| count | String | O | Maximum records in a page |
Response
The API returns a ValueSet resource in below format
{
"resourceType": "ValueSet",
"id": "episode-setting",
"meta": {
"tag": [
{
"code": "page",
"display": "1"
},
{
"code": "count",
"display": "10"
},
{
"code": "maxCount",
"display": "3"
}
]
},
"name": "episode-setting",
"expansion": {
"total": 3,
"contains": [
{
"system": "https://policies.api.healthcode.co.uk/episode-setting",
"code": "D",
"display": "Daycase"
},
{
"system": "https://policies.api.healthcode.co.uk/episode-setting",
"code": "I",
"display": "Inpatient"
},
{
"system": "https://policies.api.healthcode.co.uk/episode-setting",
"code": "O",
"display": "Outpatient"
}
]
}
}Where,
| Name | Type | Card. | Description | FHIR Field |
|---|---|---|---|---|
| Code | String | 1-1 | Code of episode setting type | ValueSet.expansion.contains.code |
| Display | String | 1-1 | Name of episode setting type | ValueSet.expansion.contains.display |
Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | MSG_PARAM_EMPTY | Parameter is null/empty |
| 422 | MSG_PARAM_INVALID | Parameter content is invalid |
| 400 | MSG_CANT_PARSE_CONTENT | Unprocessable Entity |
Get Laterality
The Get Laterality API enables the caller to retrieve types of laterality.
Endpoint
Must be looked up from the discovery document using key get_laterality_endpoint.
Request
curl --request GET
--url'{get_laterality_endpoint}'
--header 'SU-SiteId: HC14420'
--header 'Content-Type: application/fhir+json'
--header 'Authorization: Bearer abCdE12...89mNopq0rResponse
The API returns a ValueSet resource in below format
{
"resourceType": "ValueSet",
"id": "laterality",
"name": "laterality",
"expansion": {
"total": 3,
"contains": [
{
"system": "https://policies.api.healthcode.co.uk/laterality",
"code": "L",
"display": "Unilateral Left"
},
{
"system": "https://policies.api.healthcode.co.uk/laterality",
"code": "R",
"display": "Unilateral Right"
},
{
"system": "https://policies.api.healthcode.co.uk/laterality",
"code": "B",
"display": "Bilateral"
}
]
}
}Where,
| Name | Type | Card. | Description | FHIR Field |
|---|---|---|---|---|
| Code | String | 1-1 | Code of laterality type | ValueSet.expansion.contains.code |
| Display | String | 1-1 | Name of laterality type | ValueSet.expansion.contains.display |
Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | MSG_PARAM_EMPTY | Parameter is null/empty |
| 422 | MSG_PARAM_INVALID | Parameter content is invalid |
| 400 | MSG_CANT_PARSE_CONTENT | Unprocessable Entity |
Search Practitioner
The Search Practitioner API enables the caller to look up the practitioner based on following search criteria
| Search Field | Description |
|---|---|
| first-name | Search based on first name |
| last-name | Search based on last name |
| registration-number | Search based on regulatory body reference number |
Endpoint
Must be looked up from the discovery document using key search_practitioner_endpoint.
Request
curl --request POST
--url '{search_practitioner_endpoint}/{search_field}' \
--header 'SU-SiteId: HC14420' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer abCdE12...89mNopq0r \
--data-urlencode 'searchTerm=Etokowo' \
--data-urlencode 'page=1' \
--data-urlencode 'count=10' \
--data-urlencode 'sort=-lastUpdatedOn'Where,
| Field | Type | Mandatory/ Optional | Description |
|---|---|---|---|
| searchTerm | String | O | Partial search based on practitioner search field |
| _sort | String | O | Sort results by last updated date. Use _sort=lastUpdatedOn to sort results on issue date in ascending order, or _sort=-lastUpdatedOn for descending order |
| page | String | O | Page index to be fetched {1,2,3..} |
| count | String | O | Maximum records in a page |
Response
The API returns a Bundle of Practitioner resources based on the search criteria
{
"resourceType": "Bundle",
"meta": {
"tag": [
{
"code": "page",
"display": "1"
},
{
"code": "count",
"display": "10"
},
{
"code": "maxCount",
"display": "1"
}
]
},
"type": "searchset",
"total": 1,
"entry": [
{
"resource": {
"resourceType": "Practitioner",
"id": "SP00005",
"extension": [
{
"valueCodeableConcept": {
"id": "profession",
"coding": [
{
"extension": [
{
"url": "https://ref.api.healthcode.co.uk/extension/isPrimary",
"valueBoolean": true
}
],
"system": "https://ref.api.healthcode.co.uk/profession",
"code": "00U",
"display": "Surgeon"
},
{
"extension": [
{
"url": "https://ref.api.healthcode.co.uk/extension/isPrimary",
"valueBoolean": true
}
],
"system": "https://ref.api.healthcode.co.uk/profession",
"code": "00V",
"display": "Therapist"
}
]
}
},
{
"valueCodeableConcept": {
"id": "regulatorybody",
"coding": [
{
"extension": [
{
"url": "https://ref.api.healthcode.co.uk/extension/registrationNumber",
"valueString": "3203181"
}
],
"system": "https://ref.api.healthcode.co.uk/regulatorybody",
"code": "GMC",
"display": "GMC"
},
{
"extension": [
{
"url": "https://ref.api.healthcode.co.uk/extension/registrationNumber",
"valueString": "658745"
}
],
"system": "https://ref.api.healthcode.co.uk/regulatorybody",
"code": "CNHC",
"display": "CNHC"
}
]
}
}
],
"name": [
{
"family": "Etokowo",
"given": [
"God'Swill"
]
}
]
}
}
]
}Where,
| Name | Type | Card. | Description | FHIR Field |
|---|---|---|---|---|
| ID | String | 1-1 | Practitioner SP number | Practitioner.id |
| Name | HumanName | 1-1 | The name of the type that represents laterality | Practitioner.name |
| Profession | CodeableConcept | 1-* | Practitioner’s profession details which includes code, name and primary profession flag | Practitioner.extension.valueCodeableConcept.coding |
| Regulatory Body | CodeableConcept | 1-* | Practitioner’s regulatory body details which includes code, name and registration number | Practitioner.extension.valueCodeableConcept.coding |
Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | MSG_PARAM_EMPTY | Parameter is null/empty |
| 422 | MSG_PARAM_INVALID | Parameter content is invalid |
| 400 | MSG_MISSING_MANDATORY_PARAM | Parameter is mandatory |
| 400 | INVALID_RESOURCE | Unprocessable Entity |
Search Location
The Search Location API enables the caller to look up the location or treatment site.
Endpoint
Must be looked up from the discovery document using key search_location_endpoint.
Request
curl --request POST
--url '{search_location_endpoint}' \
--header 'SU-SiteId: HC14420' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer abCdE12...89mNopq0r \
--data-urlencode 'searchTerm=care' \
--data-urlencode 'page=1' \
--data-urlencode 'Count=10' \
--data-urlencode 'sort=-lastUpdatedOn'Where,
| Field | Type | Mandatory/ Optional | Description |
|---|---|---|---|
| searchTerm | String | O | Partial search based on location HP number or name |
| _sort | String | O | Sort results by last updated date. Use _sort=lastUpdatedOn to sort results on issue date in ascending order, or _sort=-lastUpdatedOn for descending order |
| page | String | O | Page index to be fetched {1,2,3..} |
| count | String | O | Maximum records in a page |
Response
The API returns a resource type of bundle with collections of locations in JSON format
{
"resourceType": "Bundle",
"meta": {
"tag": [
{
"code": "page",
"display": "1"
},
{
"code": "count",
"display": "10"
},
{
"code": "maxCount",
"display": "1"
}
]
},
"type": "collection",
"entry": [
{
"resource": {
"resourceType": "Location",
"id": "HP003631",
"name": "Rainbow Children Care"
}
}
]
}Where,
| Name | Type | Card. | Description | FHIR Field |
|---|---|---|---|---|
| ID | String | 1-1 | Location HP number | Location.id |
| Name | String | 1-1 | Location name | Location.name |
Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | MSG_PARAM_EMPTY | Parameter is null/empty |
| 422 | MSG_PARAM_INVALID | Parameter content is invalid |
| 400 | MSG_MISSING_MANDATORY_PARAM | Parameter is mandatory |
| 400 | INVALID_RESOURCE | Unprocessable Entity |
Service
Service is defined by a HealthcareService FHIR resource that contains details related to services which managed by the insurers. The following APIs enable operating against this resource.
Search Service
The Search Service API enables the caller to retrieve a list of services based on search criteria.
Endpoint
Must be looked up from the discovery document using key search_service_endpoint.
Request
curl --request POST
--url '{search_service_endpoint}'?
--header 'SU-SiteId: HC12393'
--header 'Content-Type: application/x-www-form-urlencoded'
--header 'Authorization: Bearer abCdE12...89mNopq0r'
--data-urlencode 'insurerIdentifier=tih'
--data-urlencode 'searchText=Dental Service'
--data-urlencode '_sort=-lastUpdatedOn'
--data-urlencode '_since=2024-03-01T09:00:00.00'
--data-urlencode 'page=1'
--data-urlencode 'count=10' Where,
| Field | Type | Mandatory/ Optional | Description |
|---|---|---|---|
| insurerIdentifier | String | M | Insurer’s identifier. The following are supported insurers and identifiers: Aviva = nuh Vitality Health = slh Trust in Health = tih |
| searchText | String | O | Partial search based on service ID or name |
| _sort | String | O | Sort results by last updated date. Use _sort=lastUpdatedOn to sort results on lastUpdatedOn in ascending order, or _sort=-lastUpdatedOn for descending order |
| _since | String | O | Last updated date time of records |
| page | String | O | Page index to be fetched {1,2,3..} |
| count | String | O | Maximum records in a page |
Response
The API returns a Bundle of HealthcareService resources based on the search filters.
{
"resourceType": "Bundle",
"meta": {
"tag": [
{
"code": "page",
"display": "1"
},
{
"code": "count",
"display": "10"
},
{
"code": "maxCount",
"display": "1"
}
]
},
"type": "collection",
"total": 1,
"entry": [
{
"resource": {
"resourceType": "HealthcareService",
"id": "20241121143340556MAtf0000",
"contained": [
{
"resourceType": "ValueSet",
"expansion": {
"contains": [
{
"system": "https://ref.api.healthcode.co.uk/industryStandardCode/ISC",
"code": "AU000019",
"display": "Paediatric Audio Review"
}
]
}
}
],
"name": "Dental Service",
"comment": "Offers dental services and treatments"
}
}
]
}Where,
| Name | Type | Card. | Description | FHIR Field |
|---|---|---|---|---|
| Industry Standard Code | ValueSet | 1-* | List of industry standard codes to look up with the service | HealthcareService.contained.ValueSet.expansion.contains |
| Name | String | 1-1 | Service name | HealthcareService.name |
| Description | String | 1-1 | Service description | HealthcareService.comment |
Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | MSG_PARAM_EMPTY | Parameter is null/empty |
| 422 | MSG_PARAM_INVALID | Parameter content is invalid |
| 422 | MSG_DATE_FORMAT | Invalid date format |
| 400 | MSG_CANT_PARSE_CONTENT | Unprocessable Entity |
| 500 | MSG_DATABASE_ERROR | Failed processing entity in Database |
Search Industry Standard Codes
The Get Industry Standard Code API enables the caller to retrieve a list of industry standard codes based on search criteria.
Endpoint
Must be looked up from the discovery document using key search_industry_standard_code_endpoint.
Request
curl --request POST
--url '{search_industry_standard_code_endpoint}'?
--header 'SU-SiteId: HC13086'
--header 'Content-Type: application/x-www-form-urlencoded'
--header 'Authorization: Bearer eyJra....nIjoiUlMyNTYifQ'
--data-urlencode 'searchText=Amino Acid Chromatography'
--data-urlencode '_sort=lastUpdatedOn'
--data-urlencode '_since=2024-03-01T09:00:00.00'
--data-urlencode 'page=1'
--data-urlencode 'count=10'
Where,
| Field | Type | Mandatory/ Optional | Description |
|---|---|---|---|
| searchText | String | O | Partial search based on industry standard code or description |
| _sort | String | O | Sort results by last updated date. Use _sort=lastUpdatedOn to sort results on lastUpdatedOn in ascending order, or _sort=-lastUpdatedOn for descending order |
| _since | String | O | Last updated date time of records |
| page | String | O | Page index to be fetched {1,2,3..} |
| count | String | O | Maximum records in a page |
Response
The API returns a Value Set resource based on the search filters.
{
"resourceType": "ValueSet",
"id": "industry-standard-code",
"meta": {
"tag": [
{
"code": "page",
"display": "1"
},
{
"code": "count",
"display": "10"
},
{
"code": "maxCount",
"display": "1"
}
]
},
"name": "industry-standard-code",
"expansion": {
"total": 1,
"contains": [
{
"system": "https://ref.api.healthcode.co.uk/industryStandardCode/ISC",
"code": "BC000009",
"display": "Amino Acid Chromatography"
}
]
}
}Where,
| Name | Type | Card. | Description | FHIR Field |
|---|---|---|---|---|
| Code | String | 1-1 | Industry standard code | ValueSet.expansion.contains.code |
| Display | String | 1-1 | Description of Industry standard code | ValueSet.expansion.contains.display |
| System | String | 1-1 | Industry standard scheme | ValueSet.expansion.contains.system – {refURL}/industryStandardCode/{scheme} |
Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | MSG_PARAM_EMPTY | Parameter is null/empty |
| 422 | MSG_PARAM_INVALID | Parameter content is invalid |
| 422 | MSG_DATE_FORMAT | Invalid date format |
| 400 | MSG_CANT_PARSE_CONTENT | Unprocessable Entity |
| 500 | MSG_DATABASE_ERROR | Failed processing entity in Database |
Create Service
The Create Service API enables the insurers to create the service and look up industry standard codes to it.
Endpoint
Must be looked up from the discovery document using key create_service_endpoint.
Request
curl --request POST
--url '{create_service_endpoint}'
--header 'SU-SiteId: slh'
--header 'Content-Type: application/fhir+json'
--header 'Authorization: Bearer eyJraWQiO....joiUl'
--data '{
"resourceType": "HealthcareService",
"contained": [
{
"resourceType": "ValueSet",
"expansion": {
"contains": [
{
"id": "industryStandardCode",
"system": "ISC",
"code": "AU000019"
}
]
}
}
],
"name": "Dental Service",
"comment": "Offers dental services and treatments"
}'
Where,
| Field | Type | Mandatory/ Optional | Description |
|---|---|---|---|
| industryStandardCode | ValueSet | M | List of industry standard codes to look up with the service |
| name | String | M | Service name |
| comment | String | M | Service description |
Response
On successful creation of the service, the API returns Operation outcome response.
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "information",
"code": "informational",
"details": {
"coding": [
{
"system": "https://ref.api.healthcode.co.uk/identifier/service",
"code": "20241125114444340uvAc0000",
"display": "MSG_CREATED"
}
]
},
"diagnostics": "service created",
"location": [
"Claim"
],
"expression": []
}
]
}Where,
| Name | Type | Card. | Description | FHIR Field |
|---|---|---|---|---|
| code | String | 1-1 | Service ID | OperationOutcome.details.coding.code |
Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | MSG_PARAM_EMPTY | Parameter is null/empty |
| 422 | MSG_PARAM_INVALID | Parameter content is invalid |
| 422 | MSG_DATE_FORMAT | Invalid date format |
| 400 | MSG_CANT_PARSE_CONTENT | Unprocessable Entity |
| 500 | MSG_DATABASE_ERROR | Failed processing entity in Database |
Update Service
The Update Service API enables the insurer to update the existing the service .
Endpoint
Must be looked up from the discovery document using key update_service_endpoint.
Request
curl --request UPDATE
--url '{update_service_endpoint}'
--header 'SU-SiteId: slh'
--header 'Content-Type: application/fhir+json'
--header 'Authorization: Bearer eyJraWQiO....joiUl'
--data '{
"resourceType": "HealthcareService",
"contained": [
{
"resourceType": "ValueSet",
"expansion": {
"contains": [
{
"id": "industryStandardCode",
"system": "ISC",
"code": "AU000019"
}
]
}
}
],
"id":"202411211903072631xX10000",
"name": "Dental Service",
"comment": "Offers dental services and treatments"
}'
Where,
| Field | Type | Mandatory/ Optional | Description |
|---|---|---|---|
| id | String | M | Service ID |
| industryStandardCode | ValueSet | M | List of industry standard codes to look up with the service |
| name | String | M | Service name |
| comment | String | M | Service description |
Response
On successful updating the service, the API returns Operation outcome response.
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "information",
"code": "informational",
"details": {
"coding": [
{
"system": "https://ref.api.healthcode.co.uk/identifier/service",
"code": "202411211903072631xX10000",
"display": "MSG_UPDATED"
}
]
},
"diagnostics": "service updated",
"location": [
"Claim"
],
"expression": []
}
]
}Where,
| Name | Type | Card. | Description | FHIR Field |
|---|---|---|---|---|
| code | String | 1-1 | Service ID | OperationOutcome.details.coding.code |
Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | MSG_PARAM_EMPTY | Parameter is null/empty |
| 422 | MSG_PARAM_INVALID | Parameter content is invalid |
| 422 | MSG_DATE_FORMAT | Invalid date format |
| 400 | MSG_CANT_PARSE_CONTENT | Unprocessable Entity |
| 500 | MSG_DATABASE_ERROR | Failed processing entity in Database |
Delete Service
The Delete Service API enables the insurer to delete the specific service .
Endpoint
Must be looked up from the discovery document using key delete_service_endpoint.
Request
curl --request DELETE
--url '{delete_service_endpoint}/{serviceId}'
--header 'SU-SiteId: slh'
--header 'Content-Type: application/fhir+json'
--header 'Authorization: Bearer eyJraWQi.....oiUlMyNTYi
Where,
| Field | Type | Mandatory/ Optional | Description |
|---|---|---|---|
| serviceId | String | M | Service ID |
Response
On successful deleting the service, the API returns Operation outcome response.
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "information",
"code": "informational",
"details": {
"coding": [
{
"system": "https://ref.api.healthcode.co.uk/identifier/service",
"code": "202411211903072631xX10000",
"display": "MSG_DELETED"
}
]
},
"diagnostics": "service deleted",
"location": [
"Claim"
],
"expression": []
}
]
}Where,
| Name | Type | Card. | Description | FHIR Field |
|---|---|---|---|---|
| code | String | 1-1 | Service ID | OperationOutcome.details.coding.code |
Error handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | MSG_PARAM_EMPTY | Parameter is null/empty |
| 422 | MSG_PARAM_INVALID | Parameter content is invalid |
| 422 | MSG_DATE_FORMAT | Invalid date format |
| 400 | MSG_CANT_PARSE_CONTENT | Unprocessable Entity |
| 500 | MSG_DATABASE_ERROR | Failed processing entity in Database |