Clearing Services APIs – Healthcode REST APIs

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

Remittances

Remittance data can be retrieved in two parts: summary and detail. The remittance summary uses the PaymentReconciliation resource, whereas the remittance detail uses the ClaimResponse resource. The following APIs enable operations on these resources.

Search Remittance Summary

The Search Remittance Summary – API provides enhanced search capabilities through advanced filtering and sorting options to retrieve remittance summary information.

Endpoint

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

Request

curl --request POST
	--url '{search_remittance_summary_endpoint}' 
	--header 'SU-SiteId: HC16190' 
	--header 'Content-Type: application/x-www-form-urlencoded' 
	--header 'Authorization: Bearer abCdE12...89mNopq0r' 
	--data-urlencode 'page=1' 
	--data-urlencode 'count=10' 
	--data-urlencode 'insurerIdentifier=slh' 
	--data-urlencode 'provider=P162345' 
	--data-urlencode 'invoiceNumber=INV069' 
	--data-urlencode 'patientName=Nelson' 
	--data-urlencode 'membershipNumber=REG004' 
	--data-urlencode 'dateCreated=2025-05-01_2025-05-03' 
	--data-urlencode 'datePaid=2025-01-01_2025-01-03' 
	--data-urlencode 'paymentAmount=ge1500.00' 
	--data-urlencode 'amountInvoiced=ge2000.00' 
	--data-urlencode 'paymentReference=PAY169991' 
	--data-urlencode 'hasShortFall=true' 
	--data-urlencode 'excludeExported=true' 
	--data-urlencode '_sort=providerName'

Where,

Field	Type	Mandatory/ Optional	Description
insurerIdentifier	String	O	Insurer/Payor identifier. Following are the supported insurers/payors and its identifiers: Bupa = bup Bupa Global = bui AXA Health = ppp Aviva = nuh Vitality Health = slh Cigna International = cin Trust In Health = tih WPA = wpa Patientzone = pzo
provider	String	O	Provider’s code or name Note This parameter is available only if Advanced_Search_1_0 and Advanced_Filtering_And_Sorting_1_0 is enabled.
invoiceNumber	String	O	Invoice number Note This parameter is available only if Advanced_Search_1_0 is enabled.
patientName	String	O	Patient name Note This parameter is available only if Advanced_Search_1_0 is enabled.
membershipNumber	String	O	Membership number Note This parameter is available only if Advanced_Search_1_0 is enabled.
dateCreated	String	O	Date created range Note This parameter is available only if Advanced_Search_1_0 and Advanced_Filtering_And_Sorting_1_0is enabled.
datePaid	String	O	Date paid range Note This parameter is available only if Advanced_Search_1_0 and Advanced_Filtering_And_Sorting_1_0is enabled.
paymentAmount	String	O	Payment amount of remittance. Supports `le` (less than or equal to) and `ge` (greater than or equal) and `eq` (equal to). Note This parameter is available only if Advanced_Filtering_And_Sorting_1_0is enabled.
amountInvoiced	String	O	Invoiced amount of remittance. Supports `le` (less than or equal to) and `ge` (greater than or equal) and `eq` (equal to). Note This parameter is available only if Advanced_Search_1_0 is enabled.
insurerPaymentReference	String	O	Insurer payment reference Note This parameter is available only if Advanced_Search_1_0 and Advanced_Filtering_And_Sorting_1_0 is enabled.
hasShortFall	Boolean	O	Filter remittances which includes shortfall Note This parameter is available only if Advanced_Search_1_0 and Advanced_Filtering_And_Sorting_1_0 is enabled.
excludeExported	Boolean	O	Filter exported remittances Note This parameter is available only if Advanced_Filtering_And_Sorting_1_0 is enabled.
_sort	String	O	Sort results by created date. Use `_sort=createdOn` to sort results on created date in ascending order, or `_sort=-createdOn` 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 PaymentReconciliation 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": "PaymentReconciliation",
                "id": "RS69991",
                "contained": [
                    {
                        "resourceType": "Organization",
                        "id": "1",
                        "identifier": [
                            {
                                "system": "https://ref.api.healthcode.co.uk/providerIdentifier",
                                "value": "P162345"
                            }
                        ],
                        "name": "James Hospitals"
                    },
                    {
                        "resourceType": "Organization",
                        "id": "2",
                        "identifier": [
                            {
                                "system": "https://ref.api.healthcode.co.uk/insurerIdentifier",
                                "value": "slh"
                            }
                        ],
                        "name": "Vitality Health"
                    }
                ],
                "extension": [
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/totalInvoices",
                        "valueInteger": 5
                    },
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/isExported",
                        "valueBoolean": true
                    },
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/paymentMethod",
                        "valueString": "Cheque"
                    },
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/sortCode",
                        "valueString": "69991"
                    },
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/accountNumber",
                        "valueString": "699913210"
                    },
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/processedDate",
                        "valueDate": "2025-01-02"
                    },
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/amountDue",
                        "valueMoney": {
                            "value": 125.46
                        }
                    },
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/broughtForwarded",
                        "valueMoney": {
                            "value": 0
                        }
                    },
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/carriedForwarded",
                        "valueMoney": {
                            "value": 0
                        }
                    },
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/totalInvoiced",
                        "valueMoney": {
                            "value": 2096.73
                        }
                    },
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/totalShortfall",
                        "valueMoney": {
                            "value": 125.46
                        }
                    }
                ],
                "created": "2025-02-05T10:00:00+00:00",
                "requestor": {
                    "reference": "#1"
                },
                "paymentIssuer": {
                    "reference": "#2"
                },
                "paymentAmount": {
                    "value": 1971.27
                },
                "paymentDate": "2025-01-02T00:00:00+00:00",
                "paymentIdentifier": {
                    "system": "https://clearing.api.healthcode.co.uk/paymentReference",
                    "value": "PAY169991"
                }
            }
        }
    ]
}

Where,

Name	Type	Card.	Description	FHIR Field
Remittance Summary ID	Id	1-1	Remittance Summary ID	PaymentReconciliation.id
Provider	Reference (Organization)	1-1	Provider identifier and name	PaymentReconciliation.requestor
Insurer	Reference (Organization)	1-1	Insurer identifier and name	PaymentReconciliation.paymentIssuer
Payment Reference	Identifier	1-1	The reference of the payment as presented to the bank for a transfer, or the cheque number if the method of payment is cheque	PaymentReconciliation.paymentIdentifier
Date Created	DateTime	1-1	The date when the remittances was loaded into Healthcode system	PaymentReconciliation.created
Payment Date	Date	1-1	The date of the payment which for BACS payments represents the date that the payment is actually due to be credited to the recipient’s bank account	PaymentReconciliation.paymentDate
Amount Paid	Money	1-1	The actual amount credited to the provider’s bank account or forwarded as a cheque	PaymentReconciliation.paymentAmount
Payment Method	String	0-1	This indicates how the payment is made and the allowed values are Cheque or BACS	PaymentReconciliation.extension.valueString – paymentMethod
Sort Code	String	0-1	This is provider’s bank sort code and will be included if payment method is BACS	PaymentReconciliation.extension.valueString – sortCode
Account Number	String	0-1	This is provider’s bank account number and will be included if payment method is BACS	PaymentReconciliation.extension.valueString – accountNumber
Processed Date	Date	1-1	The processing date when the remittance was created on the insurer’s/payor’s system	PaymentReconciliation.extension.valueDate – processedDate
Amount Due	Money	0-1	The total due amount	PaymentReconciliation.extension.valueMoney – amountDue
Brought Forward	Money	0-1	It contains amount due to the provider or outstanding from the provider from the previous payment period	PaymentReconciliation.extension.valueMoney – broughtForward
Carried Forward	Money	0-1	The net total of the amount brought forward from the previous payment period, plus the amount due to be paid in this payment period less the amount actually being paid	PaymentReconciliation.extension.valueMoney – carriedForward
Total Invoiced	Money	1-1	Total invoiced	PaymentReconciliation.extension.valueMoney – totalInvoiced
Total Shortfall	Money	0-1	Total shortfall	PaymentReconciliation.extension.valueMoney – totalShortfall
Total Invoices	Integer	1-1	Total number of invoices	PaymentReconciliation.extension.valueInteger – totalInvoices
Is Exported	Boolean	1-1	Indicates weather the remittance was exported or not	PaymentReconciliation.extension.valueBoolean – isExported

Error handling

HTTP Code	Error Code	Description
400	MSG_MISSING_MANDATORY_PARAM	Missing mandatory parameter
422	MSG_PARAM_INVALID	Parameter content is invalid
400	MSG_PARAM_EMPTY	Parameter is null/empty
422	MSG_INVALID_FORMAT	Invalid format

Search Remittance Detail

The Search Remittance Detail – Advanced API provides enhanced search capabilities through advanced filtering and sorting options to retrieve detailed remittance information such as patient details, invoice details and payment details.

Endpoint

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

Request

curl --request POST
	--url '{search_remittance_detail_endpoint}/{remittance_summary_id}' 
	--header 'SU-SiteId: HC16190' 
	--header 'Content-Type: application/x-www-form-urlencoded' 
	--data-urlencode 'page=1' 
	--data-urlencode 'count=10' 
	--data-urlencode '_sort=invoiceTotal' 
	--data-urlencode 'invoiceNumber=INV069' 
	--data-urlencode 'patientName=Nelson' 
	--data-urlencode 'membershipNumber=REG004' 
	--data-urlencode 'invoiceDate=2024-11-01_2024-11-05' 
	--data-urlencode 'hospitalNumber=REF004' 
	--data-urlencode 'insurerBillNumber=PC004' 
	--data-urlencode 'invoiceTotal=ge200.00' 
	--data-urlencode 'hasShortFall=true'

Where,

Field	Type	Mandatory/ Optional	Description
remittanceSummaryId	String	M	Remittance Summary ID
invoiceNumber	String	O	Invoice number Note This parameter is available only if Advanced_Filtering_And_Sorting_1_0 is enabled.
patientName	String	O	Patient name Note This parameter is available only if Advanced_Filtering_And_Sorting_1_0 is enabled.
membershipNumber	String	O	Membership number Note This parameter is available only if Advanced_Filtering_And_Sorting_1_0 is enabled.
invoiceDate	String	O	Invoice date range Note This parameter is available only if Advanced_Filtering_And_Sorting_1_0 is enabled.
hospitalNumber	String	O	Hospital number Note This parameter is available only if Advanced_Filtering_And_Sorting_1_0 is enabled.
insurerBillNumber	String	O	Insurer bill number Note This parameter is available only if Advanced_Filtering_And_Sorting_1_0 is enabled.
invoiceTotal	String	O	Invoice total. Supports `le` (less than or equal to) and `ge` (greater than or equal) and `eq` (equal to). Note This parameter is available only if Advanced_Filtering_And_Sorting_1_0 is enabled.
hasShortFall	Boolean	O	Filter remittances which includes shortfall
_sort	String	O	Sort results by created date. Use `_sort=createdOn` to sort results on created date in ascending order, or `_sort=-createdOn` 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 ClaimResponse 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": "ClaimResponse",
                "id": "RD69994",
                "contained": [
                    {
                        "resourceType": "Patient",
                        "id": "1",
                        "identifier": [
                            {
                                "system": "https://clearing.api.healthcode.co.uk/membershipNumber",
                                "value": "REG004"
                            }
                        ],
                        "name": [
                            {
                                "family": "Nick",
                                "given": [
                                    "Nelson",
                                    "A"
                                ],
                                "prefix": [
                                    "Mr."
                                ]
                            }
                        ]
                    }
                ],
                "extension": [
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/invoiceNumber",
                        "valueString": "INV069"
                    },
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/invoiceDate",
                        "valueDate": "2024-11-04"
                    },
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/paidAmount",
                        "valueMoney": {
                            "value": 190.00
                        }
                    },
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/invoiceTotal",
                        "valueMoney": {
                            "value": 250.00
                        }
                    },
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/previousPaidAmount",
                        "valueMoney": {
                            "value": 0.00
                        }
                    },
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/shortAmount",
                        "valueMoney": {
                            "value": 60.00
                        }
                    },
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/collectionService",
                        "valueString": "None"
                    },
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/dateCompleted",
                        "valueDate": "2025-02-10"
                    },
                    {
                        "url": "https://clearing.api.healthcode.co.uk/extension/createdOn",
                        "valueDateTime": "2025-02-01T10:00:00+00:00"
                    }
                ],
                "identifier": [
                    {
                        "system": "https://clearing.api.healthcode.co.uk/insurerBillNumber",
                        "value": "PC004"
                    },
                    {
                        "system": "https://clearing.api.healthcode.co.uk/hospitalNumber",
                        "value": "REF004"
                    },
                    {
                        "system": "https://clearing.api.healthcode.co.uk/chClaimNo",
                        "value": "CH001"
                    }
                ],
                "patient": {
                    "reference": "#1"
                },
                "item": [
                    {
                        "adjudication": [
                            {
                                "extension": [
                                    {
                                        "url": "https://clearing.api.healthcode.co.uk/extension/liabilityType",
                                        "valueString": "Patient Liability"
                                    }
                                ],
                                "category": {
                                    "coding": [
                                        {
                                            "system": "https://clearing.api.healthcode.co.uk/adjudication",
                                            "code": "deductible"
                                        }
                                    ]
                                },
                                "reason": {
                                    "text": "Member Excess"
                                },
                                "amount": {
                                    "value": 30.00
                                }
                            }
                        ]
                    },
                    {
                        "adjudication": [
                            {
                                "extension": [
                                    {
                                        "url": "https://clearing.api.healthcode.co.uk/extension/liabilityType",
                                        "valueString": "Provider Liability"
                                    }
                                ],
                                "category": {
                                    "coding": [
                                        {
                                            "system": "https://clearing.api.healthcode.co.uk/adjudication",
                                            "code": "deductible"
                                        }
                                    ]
                                },
                                "reason": {
                                    "text": "Charge Exceeds Agreed Tariff"
                                },
                                "amount": {
                                    "value": 30.00
                                }
                            }
                        ]
                    }
                ]
            }
        }
    ]
}

Where,

Name	Type	Card.	Description	FHIR Field
Remittance Summary ID	Id	1-1	Remittance Summary ID	ClaimResponse.id
Membership Number	Identifier	1-1	Membership number	ClaimResponse.contained.Patient.identifier
Patient Name	HumanName	0-1	Patient name	ClaimResponse.contained.Patient.name
Invoice Number	String	1-1	The provider’s invoice number	ClaimResponse.extension.valueString – invoiceNumber
Invoice Date	Date	1-1	Invoice date	ClaimResponse.extension.valueDate – invoiceDate
Invoice Total	Money	1-1	Invoice total	ClaimResponse.extension.valueMoney – invoiceTotal
Paid Amount	Money	1-1	The amount actually remitted to the provider	ClaimResponse.extension.valueMoney – paidAmount
Previous Paid Amount	Money	0-1	The amount previously paid	ClaimResponse.extension.valueMoney – previousPaidAmount
Short Amount	Money	0-1	The short amount indicates the difference between the total value of the claim, any previously paid amount and the amount remitted	ClaimResponse.extension.valueMoney – shortAmount
Shortfall Reason	BackboneElement	0-*	The shortfall liability type, reason and amount details	ClaimResponse.item
Collection Service	String	0-1	Collection service	ClaimResponse.extension.valueString – collectionService
Date Completed	Date	1-1	Date completed	ClaimResponse.extension.valueDate – dateCompleted
Created On	DateTime	1-1	Created on	ClaimResponse.extension.valueDateTime – createdOn
Insurer Bill Number	String	1-1	Insurer bill number	ClaimResponse.extension.valueString – insurerBillNumber
Hospital Number	String	1-1	Hospital number	ClaimResponse.extension.valueString – hospitalNumber
CH Claim Number	String	0-1	The internal reference used at Healthcode to link a particular Remittance to the original Claim	ClaimResponse.extension.valueString – chClaimNo

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
422	MSG_INVALID_FORMAT	Invalid format