A virtual claim in the HIE ecosystem is the digital record of a patient encounter. It acts as the container for three distinct types of data:
Clinical Data: Diagnoses and Interventions (What happened?)
Financial Data: Invoices and Lines (What does it cost?)
Administrative Data: Patient IDs, Provider IDs, and Authorizations (Who is involved?)
The Two Views: Provider vs. Payer
It is critical to understand that a single claim exists in two forms depending what stage in the lifecycle it is in.
1. The Provider Claim (Your View)
This is the claim object as it exists in your HMIS. You have full control over this object while it is in DRAFT. And have no control when submitted.
This claim object is created by you via the Create virtual claim endpoint.
The primary use of this claim is to confirm that correct details have been added to the claim, tracking billing, submitting data, and correcting errors.
This provider claim contains the "Source of Truth" for clinical and billing data.
2. The Payer Claim (The Adjudicator's View)
This is the read-only version of the claim that is what the payer's system actually sees and interacts directly with in terms of feedback.
Some of the primary uses of this claim is it helps get feedback on your claim directly from the payer and why, it helps provide more understanding as to why a claim was rejected or returned for changes, checking payment amounts, and reading feedback notes.
Anatomy of a Claim
A claim is a hierarchical tree. Understanding this hierarchy is essential for proper managing of the claim, and error handling.
1. The Root Object (The Claim)
Contains the high-level metadata: claim_auth_status, workflow_state, patient_number, and the authorization_code (mostly referred to as the consent_token).
2. The Invoice Object
Every claim has an invoices array (currently limited to 1 invoice per claim). This holds the financial totals.
Invoice Lines: Nested inside the invoice. These are the specific line items (e.g., "Consultation - 500 KES").
3. The Intervention Object
These are the medical services linked to the claim.
Crucial Rule: Every Invoice Line must correspond to a valid Intervention Code. If you have a line item for "Surgery," you must have an active Surgical Intervention in this array.
Data Structure Examples
Provider Claim Payload (Simplified)
This is a simplified structure of a Provider Claim. Notice how invoices and interventions are logically linked. To see the full structure you can check the Create Virtual Claim endpoint documentation.
Code confirming claim authorization and consent (consent_token).
authorization_guid
GUID for the authorization.
beneficiary_id
Identifier for the beneficiary (beneficiary_cr_id).
beneficiary_guid
GUID for the beneficiary.
patient_name / patient_number
Name and identifier of the patient.
member_name / member_number
Details about the insured member.
provider_name / provider_slade_code
Name and code of the healthcare provider.
payer_name / payer_code / payer_slade_code
Details of the insurance payer.
scheme_name / scheme_code
Name and code of the SHA scheme.
total_claim_amount
The total monetary value being claimed.
total_claim_net_amount
Net amount after discounts and copays.
total_claim_copay
Total copay amount for the claim.
total_claim_discount
Total discount applied to the claim.
total_claim_splits
Amount split across payers or schemes.
invoices
Array of billing details. Only 1 invoice allowed per claim.
invoice_number / invoice_id
Invoice reference and identifier.
interventions
Lists the healthcare services or procedures.
claim_diagnoses
Diagnoses associated with the claim.
workflow_state
Current processing status of the claim (e.g., DRAFT, SUBMITTED).
resubmission_workflow_state
Status of the claim during resubmission.
service_type
Type of healthcare service (e.g., CAPITATION, INPATIENT).
visit_start / visit_end
Start and end timestamps for the patient visit.
admitted_on / discharged_on
Admission and discharge dates for inpatient claims.
discharge_reason
Reason for patient discharge.
emergency_visit_expiry
Expiry date for emergency visits.
has_reviewed_claim
Indicates if the claim has been reviewed by the provider.
is_resubmitted
Whether the claim has been resubmitted.
currency
Currency used for the claim (e.g., KES).
notes
Additional comments or notes about the claim.
Note: The document_types field is key for claim attachments: all required document types listed here must be uploaded for each intervention before the claim can be submitted. If any required document is missing, the claim submission will be blocked. For a complete structure, refer to the relevant API reference documentation and see the actual response payload.
Payer Claim Payload (Simplified)
This is a simplified structure of a Payer Claim. Notice how claimNotes and claimTransitions. This is data added by the Payer after automated or payer user reviews. To see the full structure you can check the Create Virtual Claim endpoint documentation.
| Field | Description |
| ------------------------------------------------------ | -------------------------------------------------- | --- |
| id | Unique identifier for the payer claim. |
| claim_number | The claim number assigned by the payer. |
| payer_claim_status | Current status of the claim in the payer's system. |
| payer_processing_notes | Notes or feedback from the payer's processing. |
| member_number | Identifier for the insured member. |
| patient_name / patient_number | Name and identifier of the patient. |
| provider_name | Name of the healthcare provider. |
| scheme_name / scheme_code | Name and code of the insurance scheme. |
| total_amount | The total amount of the claim. |
| net_amount | The net amount after adjustments. |
| copay_amount | Total copay amount. |
| discount_amount | Total discount amount. |
| interventions | Lists the healthcare services or procedures. |
| interventions[n].intervention_name / intervention_code | Name and code of the medical service. |
| interventions[n].intervention_overall_tariff | Overall tariff for the intervention. |
| invoices | Array of billing details and adjudicated lines. |
| invoices[n].lines | Specific line items within the invoice. |
| invoices[n].lines[n].item_name / item_code | Name and code of the line item. |
| invoices[n].lines[n].line_total_amount | Total amount for the specific line. |
| claim_diagnoses | Diagnoses associated with the claim. |
| claim_attachments | Supporting documents attached to the claim. |
| attachments_count | Total number of attachments. |
| diagnoses_count | Total number of diagnoses. |
| number_of_invoices | Total number of invoices. |
| estimated_processing_time | Estimated time for claim processing. |
| visit_start / visit_end | Start and end timestamps for the patient visit. | |
Note: This claim object contains more additional fields but has been simplified to cover the most commonly used and relevant fields for understanding and processing claims. For a complete structure, refer to the relevant API reference documentation and see the the actual response payload.
