eClaims and Preauth APIs

Interventions

Endpointhttps://ilm-dev.dha.go.ke/uat-middleware/api/v1

Endpoints for managing interventions and their combinations.

Add an intervention to a claim

POST

https://ilm-dev.dha.go.ke/uat-middleware/api/v1

/claims/interventions

Adds a new intervention to an existing authorized claim, creating it in the active state. Identify the claim by its consent token.

Add an intervention to a claim › Headers

X-Facility-Id

string

Facility Registry (FR) code identifying the facility. Required when authenticating with a service-account token.

Example: FID-47-115307-8

X-Facility-Id-Type

string

Type of identifier supplied in X-Facility-Id. Currently only fr-code is supported.

Example: fr-code

Add an intervention to a claim › Request Body

consent_token

string · required

Beneficiary consent token authorizing the intervention to be added.

Example: K5HLPJVDNV

intervention_code

string · required

SHA intervention (benefit package) code being added to the claim or preauthorization.

Example: SHA-18-005

Add an intervention to a claim › Responses

Intervention added successfully

accrued_per_diem_amount

number

accrued_per_diem_days

integer

active_for_uhc

boolean

applicable_document_types

string[]

bill_from

string

bill_to

string

id

intervention_code

string

intervention_fund

string

intervention_name

string

intervention_overall_tariff

number

intervention_payment_mechanism

string

is_switched_intervention

boolean

keph_level_tarrif

number

needs_preauth

boolean

optional_document_type

string[]

optional_preauth_document_types

string[]

preauth_exist

boolean

required_preauth_document_types

string[]

requires_oncology_preauth

boolean

requires_optical_preauth

boolean

requires_radiology_preauth

boolean

requires_renal_preauth

boolean

requires_surgical_preauth

boolean

sub_benefit_code

string

supported_scheme

string

switched_intervention_id

integer

switched_lines_retained

boolean

workflow_state

string

POST/claims/interventions

curl --request POST \
  --url https://ilm-dev.dha.go.ke/uat-middleware/api/v1/claims/interventions \
  --header 'Content-Type: application/json' \
  --data '
{
  "consent_token": "K5HLPJVDNV",
  "intervention_code": "SHA-18-005"
}
'

shell

Example Request Body

{
  "consent_token": "K5HLPJVDNV",
  "intervention_code": "SHA-18-005"
}

json

Example Responses

{
  "accrued_per_diem_amount": 0,
  "accrued_per_diem_days": 0,
  "active_for_uhc": true,
  "applicable_document_types": [
    "string"
  ],
  "bill_from": "bill_from",
  "bill_to": "bill_to",
  "id": {},
  "intervention_code": "intervention_code",
  "intervention_fund": "intervention_fund",
  "intervention_name": "intervention_name",
  "intervention_overall_tariff": 0,
  "intervention_payment_mechanism": "intervention_payment_mechanism",
  "is_switched_intervention": true,
  "keph_level_tarrif": 0,
  "needs_preauth": true,
  "optional_document_type": [
    "string"
  ],
  "optional_preauth_document_types": [
    "string"
  ],
  "preauth_exist": true,
  "required_preauth_document_types": [
    "string"
  ],
  "requires_oncology_preauth": true,
  "requires_optical_preauth": true,
  "requires_radiology_preauth": true,
  "requires_renal_preauth": true,
  "requires_surgical_preauth": true,
  "sub_benefit_code": "sub_benefit_code",
  "supported_scheme": "supported_scheme",
  "switched_intervention_id": 0,
  "switched_lines_retained": true,
  "workflow_state": "workflow_state"
}

json

application/json

Restore a claim intervention

POST

https://ilm-dev.dha.go.ke/uat-middleware/api/v1

/claims/interventions/restore

Restores a previously retired intervention on a claim, transitioning it from inactive back to active.

Related documentation: Restore Intervention, SHA Combination Rules

Restore a claim intervention › Headers

X-Facility-Id

string

Facility Registry (FR) code identifying the facility. Required when authenticating with a service-account token.

Example: FID-47-115307-8

X-Facility-Id-Type

string

Type of identifier supplied in X-Facility-Id. Currently only fr-code is supported.

Example: fr-code

Restore a claim intervention › Request Body

consent_token

string · required

Consent token authorising the action on the beneficiary's preauthorisation.

Example: K5HLPJVDNV

intervention_code

string · required

SHA intervention code to restore.

Example: SHA-18-005

Restore a claim intervention › Responses

Intervention restored successfully

Standard success response format for all successful operations.

object

@Description Response data payload containing operation details @Example {"status": "success"}

message

string

@Description Success message describing the operation result @Example "Visit has been successfully started"

POST/claims/interventions/restore

curl --request POST \
  --url https://ilm-dev.dha.go.ke/uat-middleware/api/v1/claims/interventions/restore \
  --header 'Content-Type: application/json' \
  --data '
{
  "consent_token": "K5HLPJVDNV",
  "intervention_code": "SHA-18-005"
}
'

shell

Example Request Body

{
  "consent_token": "K5HLPJVDNV",
  "intervention_code": "SHA-18-005"
}

json

Example Responses

{
  "data": {},
  "message": "message"
}

json

application/json

Retire a claim intervention

POST

https://ilm-dev.dha.go.ke/uat-middleware/api/v1

/claims/interventions/retire

Retires an intervention on an existing authorized claim, transitioning it from active to inactive. A retired intervention can later be restored.

Related documentation: Retire Intervention, SHA Combination Rules

Retire a claim intervention › Headers

X-Facility-Id

string

Facility Registry (FR) code identifying the facility. Required when authenticating with a service-account token.

Example: FID-47-115307-8

X-Facility-Id-Type

string

Type of identifier supplied in X-Facility-Id. Currently only fr-code is supported.

Example: fr-code

Retire a claim intervention › Request Body

consent_token

string · required

Consent token authorising the action on the beneficiary's preauthorisation.

Example: K5HLPJVDNV

intervention_code

string · required

SHA intervention code to retire.

Example: SHA-18-005

Retire a claim intervention › Responses

Intervention retired successfully

Standard success response format for all successful operations.

object

@Description Response data payload containing operation details @Example {"status": "success"}

message

string

@Description Success message describing the operation result @Example "Visit has been successfully started"

POST/claims/interventions/retire

curl --request POST \
  --url https://ilm-dev.dha.go.ke/uat-middleware/api/v1/claims/interventions/retire \
  --header 'Content-Type: application/json' \
  --data '
{
  "consent_token": "K5HLPJVDNV",
  "intervention_code": "SHA-18-005"
}
'

shell

Example Request Body

{
  "consent_token": "K5HLPJVDNV",
  "intervention_code": "SHA-18-005"
}

json

Example Responses

{
  "data": {},
  "message": "message"
}

json

application/json

Switch a claim intervention

POST

https://ilm-dev.dha.go.ke/uat-middleware/api/v1

/claims/interventions/switch

Swaps one intervention on a claim for another, optionally retaining the existing bill items, using a valid consent token.

Switch a claim intervention › Headers

X-Facility-Id

string

Facility Registry (FR) code identifying the facility. Required when authenticating with a service-account token.

Example: FID-47-115307-8

X-Facility-Id-Type

string

Type of identifier supplied in X-Facility-Id. Currently only fr-code is supported.

Example: fr-code

Switch a claim intervention › Request Body

consent_token

string · required

Consent token authorising the intervention switch.

Example: K5HLPJVDNV

existing_intervention_code

string · required

SHA intervention code currently in use, to be switched from.

Example: SHA-18-005

new_intervention_code

string · required

SHA intervention code to switch to.

Example: SHA-18-006

retain_bill_items

boolean · required

Whether to keep the existing bill items on the new intervention.

Example: true

bill_from

string · date-time

Start of the billing period for the switched intervention, as an ISO 8601 date-time.

Example: 2026-04-23T13:30:00+03:00

bill_to

string · date-time

End of the billing period for the switched intervention, as an ISO 8601 date-time.

Example: 2026-04-23T13:30:00+03:00

Switch a claim intervention › Responses

Intervention switched successfully

Standard success response format for all successful operations.

object

@Description Response data payload containing operation details @Example {"status": "success"}

message

string

@Description Success message describing the operation result @Example "Visit has been successfully started"

POST/claims/interventions/switch

curl --request POST \
  --url https://ilm-dev.dha.go.ke/uat-middleware/api/v1/claims/interventions/switch \
  --header 'Content-Type: application/json' \
  --data '
{
  "bill_from": "2024-08-25T15:00:00Z",
  "bill_to": "2024-08-25T15:00:00Z",
  "consent_token": "K5HLPJVDNV",
  "existing_intervention_code": "SHA-18-005",
  "new_intervention_code": "SHA-18-006",
  "retain_bill_items": true
}
'

shell

Example Request Body

{
  "bill_from": "2024-08-25T15:00:00Z",
  "bill_to": "2024-08-25T15:00:00Z",
  "consent_token": "K5HLPJVDNV",
  "existing_intervention_code": "SHA-18-005",
  "new_intervention_code": "SHA-18-006",
  "retain_bill_items": true
}

json

Example Responses

{
  "data": {},
  "message": "message"
}

json

application/json

Start Visit Consent Preauths

Add an intervention to a claim

POST

https://ilm-dev.dha.go.ke/uat-middleware/api/v1

/claims/interventions

Adds a new intervention to an existing authorized claim, creating it in the active state. Identify the claim by its consent token.

Add an intervention to a claim › Headers

X-Facility-Id

string

Facility Registry (FR) code identifying the facility. Required when authenticating with a service-account token.

Example: FID-47-115307-8

X-Facility-Id-Type

string

Type of identifier supplied in X-Facility-Id. Currently only fr-code is supported.

Example: fr-code

Add an intervention to a claim › Request Body

consent_token

string · required

Beneficiary consent token authorizing the intervention to be added.

Example: K5HLPJVDNV

intervention_code

string · required

SHA intervention (benefit package) code being added to the claim or preauthorization.

Example: SHA-18-005

Add an intervention to a claim › Responses

Intervention added successfully

accrued_per_diem_amount

number

accrued_per_diem_days

integer

active_for_uhc

boolean

applicable_document_types

string[]

bill_from

string

bill_to

string

id

intervention_code

string

intervention_fund

string

intervention_name

string

intervention_overall_tariff

number

intervention_payment_mechanism

string

is_switched_intervention

boolean

keph_level_tarrif

number

needs_preauth

boolean

optional_document_type

string[]

optional_preauth_document_types

string[]

preauth_exist

boolean

required_preauth_document_types

string[]

requires_oncology_preauth

boolean

requires_optical_preauth

boolean

requires_radiology_preauth

boolean

requires_renal_preauth

boolean

requires_surgical_preauth

boolean

sub_benefit_code

string

supported_scheme

string

switched_intervention_id

integer

switched_lines_retained

boolean

workflow_state

string

curl --request POST \ --url https://ilm-dev.dha.go.ke/uat-middleware/api/v1/claims/interventions \ --header 'Content-Type: application/json' \ --data ' { "consent_token": "K5HLPJVDNV", "intervention_code": "SHA-18-005" } '

{ "accrued_per_diem_amount": 0, "accrued_per_diem_days": 0, "active_for_uhc": true, "applicable_document_types": [ "string" ], "bill_from": "bill_from", "bill_to": "bill_to", "id": {}, "intervention_code": "intervention_code", "intervention_fund": "intervention_fund", "intervention_name": "intervention_name", "intervention_overall_tariff": 0, "intervention_payment_mechanism": "intervention_payment_mechanism", "is_switched_intervention": true, "keph_level_tarrif": 0, "needs_preauth": true, "optional_document_type": [ "string" ], "optional_preauth_document_types": [ "string" ], "preauth_exist": true, "required_preauth_document_types": [ "string" ], "requires_oncology_preauth": true, "requires_optical_preauth": true, "requires_radiology_preauth": true, "requires_renal_preauth": true, "requires_surgical_preauth": true, "sub_benefit_code": "sub_benefit_code", "supported_scheme": "supported_scheme", "switched_intervention_id": 0, "switched_lines_retained": true, "workflow_state": "workflow_state" }

Restore a claim intervention

POST

https://ilm-dev.dha.go.ke/uat-middleware/api/v1

/claims/interventions/restore

Restores a previously retired intervention on a claim, transitioning it from inactive back to active.

Related documentation: Restore Intervention, SHA Combination Rules

Restore a claim intervention › Headers

X-Facility-Id

string

Facility Registry (FR) code identifying the facility. Required when authenticating with a service-account token.

Example: FID-47-115307-8

X-Facility-Id-Type

string

Type of identifier supplied in X-Facility-Id. Currently only fr-code is supported.

Example: fr-code

Restore a claim intervention › Request Body

consent_token

string · required

Consent token authorising the action on the beneficiary's preauthorisation.

Example: K5HLPJVDNV

intervention_code

string · required

SHA intervention code to restore.

Example: SHA-18-005

Restore a claim intervention › Responses

Intervention restored successfully

Standard success response format for all successful operations.

object

@Description Response data payload containing operation details @Example {"status": "success"}

message

string

@Description Success message describing the operation result @Example "Visit has been successfully started"

Retire a claim intervention

POST

https://ilm-dev.dha.go.ke/uat-middleware/api/v1

/claims/interventions/retire

Retires an intervention on an existing authorized claim, transitioning it from active to inactive. A retired intervention can later be restored.

Related documentation: Retire Intervention, SHA Combination Rules

Retire a claim intervention › Headers

X-Facility-Id

string

Facility Registry (FR) code identifying the facility. Required when authenticating with a service-account token.

Example: FID-47-115307-8

X-Facility-Id-Type

string

Type of identifier supplied in X-Facility-Id. Currently only fr-code is supported.

Example: fr-code

Retire a claim intervention › Request Body

consent_token

string · required

Consent token authorising the action on the beneficiary's preauthorisation.

Example: K5HLPJVDNV

intervention_code

string · required

SHA intervention code to retire.

Example: SHA-18-005

Retire a claim intervention › Responses

Intervention retired successfully

Standard success response format for all successful operations.

object

@Description Response data payload containing operation details @Example {"status": "success"}

message

string

@Description Success message describing the operation result @Example "Visit has been successfully started"

Switch a claim intervention

POST

https://ilm-dev.dha.go.ke/uat-middleware/api/v1

/claims/interventions/switch

Swaps one intervention on a claim for another, optionally retaining the existing bill items, using a valid consent token.

Switch a claim intervention › Headers

X-Facility-Id

string

Facility Registry (FR) code identifying the facility. Required when authenticating with a service-account token.

Example: FID-47-115307-8

X-Facility-Id-Type

string

Type of identifier supplied in X-Facility-Id. Currently only fr-code is supported.

Example: fr-code

Switch a claim intervention › Request Body

consent_token

string · required

Consent token authorising the intervention switch.

Example: K5HLPJVDNV

existing_intervention_code

string · required

SHA intervention code currently in use, to be switched from.

Example: SHA-18-005

new_intervention_code

string · required

SHA intervention code to switch to.

Example: SHA-18-006

retain_bill_items

boolean · required

Whether to keep the existing bill items on the new intervention.

Example: true

bill_from

string · date-time

Start of the billing period for the switched intervention, as an ISO 8601 date-time.

Example: 2026-04-23T13:30:00+03:00

bill_to

string · date-time

End of the billing period for the switched intervention, as an ISO 8601 date-time.

Example: 2026-04-23T13:30:00+03:00

Switch a claim intervention › Responses

Intervention switched successfully

Standard success response format for all successful operations.

object

@Description Response data payload containing operation details @Example {"status": "success"}

message

string

@Description Success message describing the operation result @Example "Visit has been successfully started"

curl --request POST \ --url https://ilm-dev.dha.go.ke/uat-middleware/api/v1/claims/interventions/switch \ --header 'Content-Type: application/json' \ --data ' { "bill_from": "2024-08-25T15:00:00Z", "bill_to": "2024-08-25T15:00:00Z", "consent_token": "K5HLPJVDNV", "existing_intervention_code": "SHA-18-005", "new_intervention_code": "SHA-18-006", "retain_bill_items": true } '

{ "bill_from": "2024-08-25T15:00:00Z", "bill_to": "2024-08-25T15:00:00Z", "consent_token": "K5HLPJVDNV", "existing_intervention_code": "SHA-18-005", "new_intervention_code": "SHA-18-006", "retain_bill_items": true }