Reference/Master Data APIs

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

List EDI Insurers

The list insurers API enables the calling system to obtain a list of EDI insurers.

Endpoint

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

Request

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

Response

The list-insurers API returns a list of Organization resources..

{
    "resourceType": "Bundle",
    "id": "insurer",
    "meta": {
        "tag": [
            {
                "code": "page",
                "display": "1"
            },
            {
                "code": "count",
                "display": "2147483647"
            },
            {
                "code": "maxCount",
                "display": "17"
            }
        ]
    },
    "type": "collection",
    "total": 1,
    "entry": [
        {
            "fullUrl": "https://ref.api.healthcode.co.uk/organization/ins/PR000003",
            "resource": {
                "resourceType": "Organization",
                "id": "PR000003",
                "identifier": [
                    {
                        "system": "https://ref.api.healthcode.co.uk/insurer-id",
                        "value": "ppp"
                    }
                ],
                "type": [
                    {
                        "coding": [
                            {
                                "system": "http://terminology.hl7.org/CodeSystem/organization-type",
                                "code": "ins",
                                "display": "Insurance Company"
                            }
                        ]
                    }
                ],
                "name": "AXA Health"
            },
            "extension": [
                {
                    "id": "lastUpdated",
                    "valueDateTime": "2022-06-07T18:29:15+05:30"
                }
            ]
        }
    ]
}

Where,

Field TypeDescription
resource.identifier.valueStringInsurer ID
resource.nameStringInsurer name

Error handling

The list-EDI-Insurers API does 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.

Get Insurer Control Parameters

The get-insurer-control-parameters API enables calling the system to obtain control parameter values specific to a given insurer, such as whether the insurer supports EDI billing, whether the insurer supports membership enquiry, etc.

Endpoint

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

Request

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

Where,

FieldTypeDescription
insurerIdStringInsurer ID for which the control parameters are required.

Response

The list-insurer-control-parameters API returns an Organization resource encapsulating the parameters and corresponding values.

{
    "resourceType": "Organization",
    "id": "PR000084",
    "extension": [
        {
            "url": "https://ref.api.healthcode.co.uk/organization/ins/{insurerId}/$control-parameters/acceptsEDIClaims",
            "valueString": "Y"
        },
        {
            "url": "https://ref.api.healthcode.co.uk/organization/ins/{insurerId}/$control-parameters/requiresDiagnosis",
            "valueString": "Y"
        },
        {
            "url": "https://ref.api.healthcode.co.uk/organization/ins/{insurerId}/$control-parameters/synchronousME",
            "valueString": "Y"
        },
        {
            "url": "https://ref.api.healthcode.co.uk/organization/ins/{insurerId}/$control-parameters/stvEnabled",
            "valueString": "Y"
        }
    ],
    "identifier": [
        {
            "system": "https://ref.api.healthcode.co.uk/insurer-id",
            "value": "ppp"
        }
    ],
    "name": "AXA PPP healthcare"
}

Where,

FieldTypeDescription
idStringInsurer Unique ID (Sequence ID)
identifier.valueStringInsurer ID
nameStringInsurer name
acceptsEDIClaims ExtensionURL =  “https://ref.api.healthcode.co.uk/organization/ins/{insurerId}/$control-parameters/acceptsEDIClaims”
Value = Y or N
requiresDiagnosisExtension URL =  “https://ref.api.healthcode.co.uk/organization/ins/{insurerId}/$control-parameters/requiresDiagnosis”
Value = Y or N
synchronousMEExtension URL =  “https://ref.api.healthcode.co.uk/organization/ins/{insurerId}/$control-parameters/synchronousME”
Value = Y or N
stvEnabledExtension URL =  “https://ref.api.healthcode.co.uk/organization/ins/{insurerId}/$control-parameters/stvEnabled”
Value = Y / N / E where Y is for STV and E is for ESTV

Error handling

The list-Insurer-Control-Parameters API does not return any API-specific errors. Calling applications must handle the standard error scenarios such as API endpoint not being available, connection timeout, etc.

Search Address

A typical address search is made up of a series of address requests, followed by a retrieve-address API based on the user selection. This API is used to narrow down a possible list of addresses, followed by a retrieve-address request to retrieve a fully formatted address. 

This API does not return formatted addresses and repeated calls to this API may be required to drill-down through results until an address ID is returned. The address ID should then be passed into the retrieve-address API to obtain a fully formatted and qualified address.

This API is accessible for sites using site credentials. Calling applications need to fetch the authentication token using site credentials and pass the token to the API to fetch the results.

Endpoint

Must be looked up from discovery-document using key search_address_endpoint

Request

curl --request GET \
--url 'https://ref.api.uat.healthcode.co.uk/postcode/address?text=watermans' \
--header 'Content-Type: application/json' \

Where “text” is the search string intended to fetch the address.

Note: address API is part of reference APIs but is a (non-FHIR) rest API supporting content type “application/json”.

Response Processing

The API returns a JSON in below format.

[
{
"key": "GB|RM|A|5459629",
"addressType": "Address",
"formattedAddress": "Watermans, 72-74, Limpsfield Road, Warlingham, CR6 9RA"
},
{
"key": "GB|RM|A|8885917",
"addressType": "Address",
"formattedAddress": "Watermans, Bolham Road, Tiverton, EX16 6SG"
},
{
"key": "GB|RM|A|11681126",
"addressType": "Address",
"formattedAddress": "Watermans, 20 Well Street, Thetford, IP24 2BL"
},
{
"key": "GB|RM|A|18216608",
"addressType": "Address",
"formattedAddress": "Watermans, 50 Parsons Street, Banbury, OX16 5NB"
}
]

Where,

FieldTypeDescription
keyStringUnique identifier or KEY of the returned address used to retrieve the fully formatted and qualified address.
addressTypeStringType of the record returned. This type should be “address” to enable retrieval of a fully qualified address from retrieve-address API.
formattedAddressStringFormatted address for the returned record.

Error Handling

When the “text” parameter is not found in the request an HTTP status of “400 Bad Request” is returned.

Retrieve Address

This API returns the full address details based on the “ID” parameter in the request. This API needs to be called after fetching the address ID from the system using the above search address API.

This API is accessible for sites using site credentials. Calling applications need to fetch the authentication token using site credentials and pass the token to the API to fetch the results.

Endpoint

Must be looked up from discovery-document using key retrieve_address_endpoint

Request

curl --request GET \ 
--url 'https://ref.api.healthcode.co.uk/postcode/retrieve-address?id={address identifier returned by search address API}' \
'Content-Type: application/json'

Where “ID” is the address identifier selected by the user from the results (fetched addresses) of the search address API.

Note: retrieve-address API is part of reference APIs but is a (non FHIR) rest API supporting content type “application/json”. 

As the character “|” is used within the address identifier, this needs to be replaced with “%7C” when submitting the HTTP request.

Response Processing

The API returns a JSON in below format.

[
{
"key": "GB|RM|A|55553679",
"line1": "Rourke House",
"line2": "3 Watermans Business Park",
"line3": "Kingsbury Crescent",
"line4": "",
"buildingName": "Rourke House",
"street": "Kingsbury Crescent",
"provinceName": "Surrey",
"postcode": "TW18 3BA",
"city": "Staines-upon-Thames",
"district": "",
"country": "United Kingdom",
"countryCode3": "GBR",
"addressType": "Address",
"formattedAddress": "Niquesa World Ltd\nRourke House\n3 Watermans Business Park\nKingsbury Crescent\nSTAINES-UPON-THAMES\nTW18 3BA\nUNITED KINGDOM",
"latitude": "51.4335",
"longitude": "-0.5187"
}
]

Error Handling

When the “text” parameter is not found in the request an HTTP status of “400 Bad Request” is returned.

Geo-Coding

This API returns the formatted address and the corresponding latitude and longitude of the postcode. This API is accessible for sites using site credentials. Calling applications need to fetch the authentication token using site credentials and pass the token to the API to fetch the results.

Endpoint

Must be looked up from discovery-document using key geo_coding_endpoint.

Request

curl --request GET \
  --url 'https://ref.api.uat.healthcode.co.uk/postcode/geo-coding?postcode=TW1 2BA'  \
        'Content-Type: application/json'

Where “postcode” is the postcode for which the geographical coordinates need to be fetched.

Note: geo-coding API is part of reference APIs but is a (non FHIR) rest API supporting content type “application/json”. 

Response Processing

The API returns a JSON in below format.

{
"formattedAddress": "Twickenham TW1, UK",
"latitude": "51.44889939999999",
"longitude": "-0.3199502"
}

Error Handling

When the “text” parameter is not found in the request an HTTP status of “400 Bad Request” is returned.

Validate Postcode

This API returns the formatted address and the corresponding latitude and longitude of the postcode. This API is accessible for sites using site credentials. Calling applications need to fetch the authentication token using site credentials and pass the token to the API to fetch the results.

Endpoint

Must be looked up from discovery-document using key geo_coding_endpoint

Request

curl --request GET \
  --url 'https://ref.api.uat.healthcode.co.uk/postcode/validate-postcode?postcode=TN12 6ND'  \
        'Content-Type: application/json'

Where “postcode” is the postcode that needs to be validated.

Note: validate-postcode API is part of reference APIs but is a (non FHIR) rest API supporting content type “application/json”. 

Response Processing

The API returns a JSON in below format. Returns “false” when the supplied postcode is not valid.

{
"postcode": "TN12 6ND",
"status": true
}

Where the “status” field is a Boolean data type.

Error Handling

When the “text” parameter is not found in the request an HTTP status of “400 Bad Request” is returned.

1 thought on “Reference/Master Data APIs”

  1. I like the helpful info you supply on your articles. I
    will bookmark your weblog and take a look at again right here frequently.
    I’m reasonably sure I will be told plenty of new stuff right here!
    Best of luck for the next!

Comments are closed.