Consent Services APIs

Authorizations

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

Endpoints for creating and retrieving patient consent authorizations via OTP or biometrics.

Create a new authorization (OTP or biometrics)

POST

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

/claims/authorize

Creates a new authorization by capturing patient consent via OTP or biometrics. Use the OTP strategy for standard outpatient and inpatient consent; use the biometrics strategy (eKYC or fingerprint) when the facility has a registered hardware agent. The same endpoint is used across claims creation and consent workflows.

Related documentation: Start Visit Workflow, Biometrics Integration

Create a new authorization (OTP or biometrics) › Request Body

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: patient_id, service_type, otp +1 more
	type = object · requires: agent_id, authorizing_device_os, ekyc_provider_id +9 more
	type = object · requires: interventions, is_biometrics_discharge_authorization, is_emergency +5 more

Properties for OTP Authorization:

Authorization request using a one-time password (OTP) sent to the patient's registered phone number. Use this strategy for outpatient or inpatient consent where OTP verification is available.

patient_id

string · required

The patient's Client Registry identifier. Dummy example — obtain a real value from the Patient Search API.

Example: CR2594484249725-2

service_type

string · enum · required

Type of service being authorized.

Enum values:

OUTPATIENT

INPATIENT

Example: OUTPATIENT

otp

string · required

One-time password delivered to the patient's registered phone number.

Example: 123456

interventions

string[] · required

List of intervention codes for the services being requested in this visit.

Example: ["SHA-18-005"]

Create a new authorization (OTP or biometrics) › Responses

Authorization created successfully

authCode

string

authorizationReason

string

authorizationType

string[]

authorizingDeviceOs

string

beneficiary

integer

beneficiaryCode

string

beneficiaryJoinDate

string

beneficiaryName

string

beneficiaryNumber

string

beneficiaryScheme

string

benefitType

string

biometricMatchLogId

string

created_by

string

dateAuthorized

string

ekycToken

string

endDate

string

expiry

string

guardian

integer

guid

string

id

integer

isBiometricsDischargeAuthorization

boolean

isComplete

boolean

isElective

boolean

isEmergency

boolean

isOpen

boolean

label

string

needsPreauth

boolean

notes

string

overallPreauthFinalised

boolean

parentAuthorization

integer

parentType

string

provider

integer

providerFid

string

providerName

string

requestedBy

string

sessionType

string

shaGuid

string

object

shaVerificationRequestId

string

status

string

token

string

updated_by

string

workStationId

string

POST/claims/authorize

curl --request POST \
  --url https://ilm-dev.dha.go.ke/uat-middleware/api/v1/claims/authorize \
  --header 'Content-Type: application/json' \
  --data '
{
  "patient_id": "CR2594484249725-2",
  "service_type": "OUTPATIENT",
  "otp": "123456",
  "interventions": [
    "string"
  ]
}
'

shell

Example Request Body

{
  "patient_id": "CR2594484249725-2",
  "service_type": "OUTPATIENT",
  "otp": "123456",
  "interventions": [
    "string"
  ]
}

json

Example Responses

{
  "authCode": "authCode",
  "authorizationReason": "authorizationReason",
  "authorizationType": [
    "string"
  ],
  "authorizingDeviceOs": "authorizingDeviceOs",
  "beneficiary": 0,
  "beneficiaryCode": "beneficiaryCode",
  "beneficiaryJoinDate": "beneficiaryJoinDate",
  "beneficiaryName": "beneficiaryName",
  "beneficiaryNumber": "beneficiaryNumber",
  "beneficiaryScheme": "beneficiaryScheme",
  "benefitType": "benefitType",
  "biometricMatchLogId": "biometricMatchLogId",
  "created_by": "created_by",
  "dateAuthorized": "dateAuthorized",
  "ekycToken": "ekycToken",
  "endDate": "endDate",
  "expiry": "expiry",
  "guardian": 0,
  "guid": "guid",
  "id": 0,
  "isBiometricsDischargeAuthorization": true,
  "isComplete": true,
  "isElective": true,
  "isEmergency": true,
  "isOpen": true,
  "label": "label",
  "needsPreauth": true,
  "notes": "notes",
  "overallPreauthFinalised": true,
  "parentAuthorization": 0,
  "parentType": "parentType",
  "provider": 0,
  "providerFid": "providerFid",
  "providerName": "providerName",
  "requestedBy": "requestedBy",
  "sessionType": "sessionType",
  "shaGuid": "shaGuid",
  "shaVerificationRequest": {
    "embedExpiry": 0,
    "embededToken": "embededToken",
    "requestId": "requestId",
    "requestUrl": "requestUrl"
  },
  "shaVerificationRequestId": "shaVerificationRequestId",
  "status": "status",
  "token": "token",
  "updated_by": "updated_by",
  "workStationId": "workStationId"
}

json

application/json

Retrieve an existing authorization

GET

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

/claims/authorizations

Retrieves existing authorizations. All query params are OPTIONAL and act as a one-of search: look up by token, by patient_id, or by guid. Supply whichever identifier you have.

Related documentation: Get Authorizations

Retrieve an existing authorization › query Parameters

token

string

Consent token for the authorization (one-of search)

Example: K5HLPJVDNV

patient_id

string

Beneficiary id (one-of search) Dummy example — obtain a real value from the Patient Search API.

Example: CR2594484249725-2

guid

string

Authorization GUID (one-of search)

Example: 3f2504e0-4f89-41d3-9a0c-0305e82c3301

Retrieve an existing authorization › 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

Retrieve an existing authorization › Responses

Authorizations retrieved successfully

object[]

authCode

string

authorizationReason

string

authorizationType

string[]

authorizingDeviceOs

string

beneficiary

integer

beneficiaryCode

string

beneficiaryJoinDate

string

beneficiaryName

string

beneficiaryNumber

string

beneficiaryScheme

string

benefitType

string

biometricMatchLogId

string

created_by

string

dateAuthorized

string

ekycToken

string

endDate

string

expiry

string

guardian

integer

guid

string

id

integer

isBiometricsDischargeAuthorization

boolean

isComplete

boolean

isElective

boolean

isEmergency

boolean

isOpen

boolean

label

string

needsPreauth

boolean

notes

string

overallPreauthFinalised

boolean

parentAuthorization

integer

parentType

string

provider

integer

providerFid

string

providerName

string

requestedBy

string

sessionType

string

shaGuid

string

object

shaVerificationRequestId

string

status

string

token

string

updated_by

string

workStationId

string

GET/claims/authorizations

curl --request GET \
  --url https://ilm-dev.dha.go.ke/uat-middleware/api/v1/claims/authorizations

shell

Example Responses

[
  {
    "authCode": "authCode",
    "authorizationReason": "authorizationReason",
    "authorizationType": [
      "string"
    ],
    "authorizingDeviceOs": "authorizingDeviceOs",
    "beneficiary": 0,
    "beneficiaryCode": "beneficiaryCode",
    "beneficiaryJoinDate": "beneficiaryJoinDate",
    "beneficiaryName": "beneficiaryName",
    "beneficiaryNumber": "beneficiaryNumber",
    "beneficiaryScheme": "beneficiaryScheme",
    "benefitType": "benefitType",
    "biometricMatchLogId": "biometricMatchLogId",
    "created_by": "created_by",
    "dateAuthorized": "dateAuthorized",
    "ekycToken": "ekycToken",
    "endDate": "endDate",
    "expiry": "expiry",
    "guardian": 0,
    "guid": "guid",
    "id": 0,
    "isBiometricsDischargeAuthorization": true,
    "isComplete": true,
    "isElective": true,
    "isEmergency": true,
    "isOpen": true,
    "label": "label",
    "needsPreauth": true,
    "notes": "notes",
    "overallPreauthFinalised": true,
    "parentAuthorization": 0,
    "parentType": "parentType",
    "provider": 0,
    "providerFid": "providerFid",
    "providerName": "providerName",
    "requestedBy": "requestedBy",
    "sessionType": "sessionType",
    "shaGuid": "shaGuid",
    "shaVerificationRequest": {
      "embedExpiry": 0,
      "embededToken": "embededToken",
      "requestId": "requestId",
      "requestUrl": "requestUrl"
    },
    "shaVerificationRequestId": "shaVerificationRequestId",
    "status": "status",
    "token": "token",
    "updated_by": "updated_by",
    "workStationId": "workStationId"
  }
]

json

application/json

Reject a pending biometrics authorization

POST

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

/claims/authorizations/{consent_token}/reject

Rejects an existing pending biometrics authorization. The consent_token supplied in the path is the token returned on the created authorization object. No request body is required.

This exists chiefly to recover from an expired biometric capture. When the capture iframe's timer runs out before a fingerprint is captured, the authorization is left in PENDING - and in that state prints can neither be matched nor a fresh authorization created for the same context. Rejecting the stuck authorization is what unblocks creating a new one.

Related documentation: Reject Authorization, Biometrics Integration Guide

Reject a pending biometrics authorization › path Parameters

consent_token

string · required

Token returned on the created authorization

Example: K5HLPJVDNV

Reject a pending biometrics authorization › 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

Reject a pending biometrics authorization › Responses

Authorization rejected

message

string

POST/claims/authorizations/{consent_token}/reject

curl --request POST \
  --url https://ilm-dev.dha.go.ke/uat-middleware/api/v1/claims/authorizations/:consent_token/reject

shell

Example Responses

{
  "message": "message"
}

json

application/json

Status Callbacks

Create a new authorization (OTP or biometrics)

POST

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

/claims/authorize

Related documentation: Start Visit Workflow, Biometrics Integration

Create a new authorization (OTP or biometrics) › Request Body

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: patient_id, service_type, otp +1 more
	type = object · requires: agent_id, authorizing_device_os, ekyc_provider_id +9 more
	type = object · requires: interventions, is_biometrics_discharge_authorization, is_emergency +5 more

Properties for OTP Authorization:

Authorization request using a one-time password (OTP) sent to the patient's registered phone number. Use this strategy for outpatient or inpatient consent where OTP verification is available.

patient_id

string · required

The patient's Client Registry identifier. Dummy example — obtain a real value from the Patient Search API.

Example: CR2594484249725-2

service_type

string · enum · required

Type of service being authorized.

Enum values:

OUTPATIENT

INPATIENT

Example: OUTPATIENT

otp

string · required

One-time password delivered to the patient's registered phone number.

Example: 123456

interventions

string[] · required

List of intervention codes for the services being requested in this visit.

Example: ["SHA-18-005"]

Create a new authorization (OTP or biometrics) › Responses

Authorization created successfully

authCode

string

authorizationReason

string

authorizationType

string[]

authorizingDeviceOs

string

beneficiary

integer

beneficiaryCode

string

beneficiaryJoinDate

string

beneficiaryName

string

beneficiaryNumber

string

beneficiaryScheme

string

benefitType

string

biometricMatchLogId

string

created_by

string

dateAuthorized

string

ekycToken

string

endDate

string

expiry

string

guardian

integer

guid

string

id

integer

isBiometricsDischargeAuthorization

boolean

isComplete

boolean

isElective

boolean

isEmergency

boolean

isOpen

boolean

label

string

needsPreauth

boolean

notes

string

overallPreauthFinalised

boolean

parentAuthorization

integer

parentType

string

provider

integer

providerFid

string

providerName

string

requestedBy

string

sessionType

string

shaGuid

string

object

shaVerificationRequestId

string

status

string

token

string

updated_by

string

workStationId

string

curl --request POST \ --url https://ilm-dev.dha.go.ke/uat-middleware/api/v1/claims/authorize \ --header 'Content-Type: application/json' \ --data ' { "patient_id": "CR2594484249725-2", "service_type": "OUTPATIENT", "otp": "123456", "interventions": [ "string" ] } '

{ "authCode": "authCode", "authorizationReason": "authorizationReason", "authorizationType": [ "string" ], "authorizingDeviceOs": "authorizingDeviceOs", "beneficiary": 0, "beneficiaryCode": "beneficiaryCode", "beneficiaryJoinDate": "beneficiaryJoinDate", "beneficiaryName": "beneficiaryName", "beneficiaryNumber": "beneficiaryNumber", "beneficiaryScheme": "beneficiaryScheme", "benefitType": "benefitType", "biometricMatchLogId": "biometricMatchLogId", "created_by": "created_by", "dateAuthorized": "dateAuthorized", "ekycToken": "ekycToken", "endDate": "endDate", "expiry": "expiry", "guardian": 0, "guid": "guid", "id": 0, "isBiometricsDischargeAuthorization": true, "isComplete": true, "isElective": true, "isEmergency": true, "isOpen": true, "label": "label", "needsPreauth": true, "notes": "notes", "overallPreauthFinalised": true, "parentAuthorization": 0, "parentType": "parentType", "provider": 0, "providerFid": "providerFid", "providerName": "providerName", "requestedBy": "requestedBy", "sessionType": "sessionType", "shaGuid": "shaGuid", "shaVerificationRequest": { "embedExpiry": 0, "embededToken": "embededToken", "requestId": "requestId", "requestUrl": "requestUrl" }, "shaVerificationRequestId": "shaVerificationRequestId", "status": "status", "token": "token", "updated_by": "updated_by", "workStationId": "workStationId" }

Retrieve an existing authorization

GET

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

/claims/authorizations

Retrieves existing authorizations. All query params are OPTIONAL and act as a one-of search: look up by token, by patient_id, or by guid. Supply whichever identifier you have.

Related documentation: Get Authorizations

Retrieve an existing authorization › query Parameters

token

string

Consent token for the authorization (one-of search)

Example: K5HLPJVDNV

patient_id

string

Beneficiary id (one-of search) Dummy example — obtain a real value from the Patient Search API.

Example: CR2594484249725-2

guid

string

Authorization GUID (one-of search)

Example: 3f2504e0-4f89-41d3-9a0c-0305e82c3301

Retrieve an existing authorization › 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

Retrieve an existing authorization › Responses

Authorizations retrieved successfully

object[]

authCode

string

authorizationReason

string

authorizationType

string[]

authorizingDeviceOs

string

beneficiary

integer

beneficiaryCode

string

beneficiaryJoinDate

string

beneficiaryName

string

beneficiaryNumber

string

beneficiaryScheme

string

benefitType

string

biometricMatchLogId

string

created_by

string

dateAuthorized

string

ekycToken

string

endDate

string

expiry

string

guardian

integer

guid

string

id

integer

isBiometricsDischargeAuthorization

boolean

isComplete

boolean

isElective

boolean

isEmergency

boolean

isOpen

boolean

label

string

needsPreauth

boolean

notes

string

overallPreauthFinalised

boolean

parentAuthorization

integer

parentType

string

provider

integer

providerFid

string

providerName

string

requestedBy

string

sessionType

string

shaGuid

string

object

shaVerificationRequestId

string

status

string

token

string

updated_by

string

workStationId

string

[ { "authCode": "authCode", "authorizationReason": "authorizationReason", "authorizationType": [ "string" ], "authorizingDeviceOs": "authorizingDeviceOs", "beneficiary": 0, "beneficiaryCode": "beneficiaryCode", "beneficiaryJoinDate": "beneficiaryJoinDate", "beneficiaryName": "beneficiaryName", "beneficiaryNumber": "beneficiaryNumber", "beneficiaryScheme": "beneficiaryScheme", "benefitType": "benefitType", "biometricMatchLogId": "biometricMatchLogId", "created_by": "created_by", "dateAuthorized": "dateAuthorized", "ekycToken": "ekycToken", "endDate": "endDate", "expiry": "expiry", "guardian": 0, "guid": "guid", "id": 0, "isBiometricsDischargeAuthorization": true, "isComplete": true, "isElective": true, "isEmergency": true, "isOpen": true, "label": "label", "needsPreauth": true, "notes": "notes", "overallPreauthFinalised": true, "parentAuthorization": 0, "parentType": "parentType", "provider": 0, "providerFid": "providerFid", "providerName": "providerName", "requestedBy": "requestedBy", "sessionType": "sessionType", "shaGuid": "shaGuid", "shaVerificationRequest": { "embedExpiry": 0, "embededToken": "embededToken", "requestId": "requestId", "requestUrl": "requestUrl" }, "shaVerificationRequestId": "shaVerificationRequestId", "status": "status", "token": "token", "updated_by": "updated_by", "workStationId": "workStationId" } ]

Reject a pending biometrics authorization

POST

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

/claims/authorizations/{consent_token}/reject

Rejects an existing pending biometrics authorization. The consent_token supplied in the path is the token returned on the created authorization object. No request body is required.

Related documentation: Reject Authorization, Biometrics Integration Guide

Reject a pending biometrics authorization › path Parameters

consent_token

string · required

Token returned on the created authorization

Example: K5HLPJVDNV

Reject a pending biometrics authorization › 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

Reject a pending biometrics authorization › Responses

Authorization rejected

message

string