SHR Service APIs

SHR Consent

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

Endpoints for the SHR consent lifecycle: requesting patient consent, verifying it with an OTP, polling its status, resending the OTP, and refreshing or closing the visit it opened.

POST

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

/shr/consents

Initiates a consent request against the DHA Consent Management Platform. On success DHA dispatches an OTP to the patient and returns a consent_id used by the verify, status and resend-otp calls.

Related documentation: Introduction to the Shared Health Record

Payload that initiates a Shared Health Record consent request against the DHA Consent Management Platform.

cr_id

string · required

Client Registry (CR) identifier of the patient whose records the consent covers.

Example: CR99551207471367-7

facility_id

string · required

Facility Registry (FR) code of the facility requesting consent.

Example: FID-47-115307-8

requested_by

string · required

Name or role of the person requesting consent. Recorded on the consent audit trail.

Example: Registration Clerk

visit_type

string · enum · required

Type of visit the consent is being requested for. OP for outpatient, IP for inpatient.

Enum values:

Example: IP

Consent request created

Result of creating a consent request. DHA dispatches an OTP to the patient and returns the consent id used by the verify, status and resend-otp calls.

consent_id

string

Identifier of the consent request. Supply it on the verify, status and resend-otp calls.

Example: VCR-20260624-13698E26

consent_status

string

Current state of the consent request as reported by DHA, for example Pending while the patient has not yet entered the OTP.

Example: Pending

message

string

Human readable outcome message from DHA.

Example: Consent request created successfully

otp_record

string

OTP record reference. Send it back with the OTP when verifying the consent.

Example: d67p9lhxxx

status

string

Outcome status reported by DHA.

Example: success

visit_type

string · enum

Type of visit the consent was requested for.

Enum values:

Example: IP

POST/shr/consents

curl --request POST \
  --url https://ilm-dev.dha.go.ke/uat-middleware/api/v1/shr/consents \
  --header 'Content-Type: application/json' \
  --data '
{
  "cr_id": "CR99551207471367-7",
  "facility_id": "FID-47-115307-8",
  "requested_by": "Registration Clerk",
  "visit_type": "OP"
}
'

shell

Example Request Body

{
  "cr_id": "CR99551207471367-7",
  "facility_id": "FID-47-115307-8",
  "requested_by": "Registration Clerk",
  "visit_type": "OP"
}

json

Example Responses

{
  "consent_id": "VCR-20260624-13698E26",
  "consent_status": "Pending",
  "message": "Consent request created successfully",
  "otp_record": "d67p9lhxxx",
  "status": "success",
  "visit_type": "OP"
}

json

application/json

POST

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

/shr/consents/{consent_id}/verify

Verifies a pending consent request using the OTP the patient received. A successful verification opens a visit and returns the per-visit consent token used to read patient records.

Related documentation: Introduction to the Shared Health Record

consent_id

string · required

Consent id returned by the consent request.

Example: VCR-20260624-13698E26

Payload that verifies a pending consent request with the one-time password the patient received.

otp

string · required

One-time password the patient received from DHA.

Example: 14384

otp_record

string · required

OTP record reference returned by the consent request. It ties the OTP back to the consent it was issued for.

Example: d67p9lhxxx

Consent verified

Result of verifying consent with an OTP. It carries the consent token used to read patient records and the visit the consent opened.

consent_token

string

Per-visit consent token. Send it in the X-Consent-Token header when fetching patient records.

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

message

string

Human readable outcome message from DHA.

Example: Consent verified successfully

status

string

Outcome status reported by DHA.

Example: success

visit_id

string

Identifier of the visit opened by the verified consent. Use it to refresh consent or to close the visit.

Example: f5c2fd92-1847-407f-97b7-a9d277699c22

POST/shr/consents/{consent_id}/verify

curl --request POST \
  --url https://ilm-dev.dha.go.ke/uat-middleware/api/v1/shr/consents/:consent_id/verify \
  --header 'Content-Type: application/json' \
  --data '
{
  "otp": "14384",
  "otp_record": "d67p9lhxxx"
}
'

shell

Example Request Body

{
  "otp": "14384",
  "otp_record": "d67p9lhxxx"
}

json

Example Responses

{
  "consent_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
  "message": "Consent verified successfully",
  "status": "success",
  "visit_id": "f5c2fd92-1847-407f-97b7-a9d277699c22"
}

json

application/json

GET

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

/shr/consents/{consent_id}/status

Returns the current status of a consent request identified by its consent id. Poll this endpoint while the patient completes the OTP step. Once consent is approved the response also carries the visit_id.

Related documentation: Introduction to the Shared Health Record

consent_id

string · required

Consent id returned by the consent request.

Example: VCR-20260624-13698E26

Consent status

Current status of a consent request. Once the patient has approved, the response also carries the visit id opened for the consent.

consent_id

string

Identifier of the consent request being polled.

Example: VCR-20260624-13698E26

consent_status

string

Current state of the consent request as reported by DHA, for example Pending or Approved.

Example: Approved

message

string

Human readable outcome message from DHA.

Example: Consent status retrieved successfully

status

string

Outcome status reported by DHA.

Example: success

visit_id

string

Identifier of the visit opened against the approved consent. Use it to refresh consent or to close the visit.

Example: f5c2fd92-1847-407f-97b7-a9d277699c22

GET/shr/consents/{consent_id}/status

curl --request GET \
  --url https://ilm-dev.dha.go.ke/uat-middleware/api/v1/shr/consents/:consent_id/status

shell

Example Responses

{
  "consent_id": "VCR-20260624-13698E26",
  "consent_status": "Approved",
  "message": "Consent status retrieved successfully",
  "status": "success",
  "visit_id": "f5c2fd92-1847-407f-97b7-a9d277699c22"
}

json

application/json

POST

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

/shr/consents/{consent_id}/resend-otp

Asks DHA to resend the OTP for a pending consent request. The response carries a fresh otp_record - verify the consent with that value, not the one from the original consent request.

Related documentation: Introduction to the Shared Health Record

consent_id

string · required

Consent id returned by the consent request.

Example: VCR-20260624-13698E26

OTP resent

Result of asking DHA to resend the consent OTP. It echoes the consent the OTP belongs to and carries a fresh OTP record reference.

consent_id

string

Identifier of the consent request the OTP was resent for.

Example: VCR-20260624-13698E26

consent_status

string

Current state of the consent request as reported by DHA.

Example: Pending

message

string

Human readable outcome message from DHA.

Example: OTP resent successfully

otp_record

string

OTP record reference for the newly issued OTP. Use this value, not the earlier one, when verifying the consent.

Example: d67p9lhxxx

status

string

Outcome status reported by DHA.

Example: success

visit_type

string · enum

Type of visit the consent was requested for.

Enum values:

Example: IP

POST/shr/consents/{consent_id}/resend-otp

curl --request POST \
  --url https://ilm-dev.dha.go.ke/uat-middleware/api/v1/shr/consents/:consent_id/resend-otp

shell

Example Responses

{
  "consent_id": "VCR-20260624-13698E26",
  "consent_status": "Pending",
  "message": "OTP resent successfully",
  "otp_record": "d67p9lhxxx",
  "status": "success",
  "visit_type": "OP"
}

json

application/json

POST

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

/shr/visits/{visit_id}/refresh

Refreshes patient consent for an open visit and returns a fresh consent token. Use it when the token issued at verification has expired but the visit is still open.

Related documentation: Introduction to the Shared Health Record

visit_id

string · required

Visit id of the open visit.

Example: f5c2fd92-1847-407f-97b7-a9d277699c22

Consent refreshed

Result of refreshing patient consent for an open visit. It carries a fresh consent token for reading patient records.

consent_token

string

Refreshed per-visit consent token. Replace the token you were using and send this one in the X-Consent-Token header.

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

message

string

Human readable outcome message from DHA.

Example: Patient consent refreshed successfully

status

string

Outcome status reported by DHA.

Example: success

POST/shr/visits/{visit_id}/refresh

curl --request POST \
  --url https://ilm-dev.dha.go.ke/uat-middleware/api/v1/shr/visits/:visit_id/refresh

shell

Example Responses

{
  "consent_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
  "message": "Patient consent refreshed successfully",
  "status": "success"
}

json

application/json

Close an SHR visit

POST

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

/shr/visits/{visit_id}/close

Closes the visit identified by its visit id. Close the visit once the encounter is complete - the consent token can no longer be refreshed afterwards.

Related documentation: Introduction to the Shared Health Record

Close an SHR visit › path Parameters

visit_id

string · required

Visit id to close.

Example: f5c2fd92-1847-407f-97b7-a9d277699c22

Close an SHR visit › Responses

Visit closed

Result of closing an SHR visit. Once closed, the visit's consent token can no longer be refreshed.

consent_id

string

Identifier of the consent request the closed visit belonged to.

Example: VCR-20260624-13698E26

end_date

string

Timestamp at which the visit was closed.

Example: 2026-06-24T14:32:11Z

message

string

Human readable outcome message from DHA.

Example: Visit closed successfully

status

string

Outcome status reported by DHA.

Example: success

visit_id

string

Identifier of the visit that was closed.

Example: f5c2fd92-1847-407f-97b7-a9d277699c22

POST/shr/visits/{visit_id}/close

curl --request POST \
  --url https://ilm-dev.dha.go.ke/uat-middleware/api/v1/shr/visits/:visit_id/close

shell

Example Responses

{
  "consent_id": "VCR-20260624-13698E26",
  "end_date": "2026-06-24T14:32:11Z",
  "message": "Visit closed successfully",
  "status": "success",
  "visit_id": "f5c2fd92-1847-407f-97b7-a9d277699c22"
}

json

application/json

SHR Records

Request patient consent for an SHR visit

POST

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

/shr/consents

Initiates a consent request against the DHA Consent Management Platform. On success DHA dispatches an OTP to the patient and returns a consent_id used by the verify, status and resend-otp calls.

Related documentation: Introduction to the Shared Health Record

Payload that initiates a Shared Health Record consent request against the DHA Consent Management Platform.

cr_id

string · required

Client Registry (CR) identifier of the patient whose records the consent covers.

Example: CR99551207471367-7

facility_id

string · required

Facility Registry (FR) code of the facility requesting consent.

Example: FID-47-115307-8

requested_by

string · required

Name or role of the person requesting consent. Recorded on the consent audit trail.

Example: Registration Clerk

visit_type

string · enum · required

Type of visit the consent is being requested for. OP for outpatient, IP for inpatient.

Enum values:

Example: IP

Consent request created

Result of creating a consent request. DHA dispatches an OTP to the patient and returns the consent id used by the verify, status and resend-otp calls.

consent_id

string

Identifier of the consent request. Supply it on the verify, status and resend-otp calls.

Example: VCR-20260624-13698E26

consent_status

string

Current state of the consent request as reported by DHA, for example Pending while the patient has not yet entered the OTP.

Example: Pending

message

string

Human readable outcome message from DHA.

Example: Consent request created successfully

otp_record

string

OTP record reference. Send it back with the OTP when verifying the consent.

Example: d67p9lhxxx

status

string

Outcome status reported by DHA.

Example: success

visit_type

string · enum

Type of visit the consent was requested for.

Enum values:

Example: IP

Verify patient consent with an OTP

POST

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

/shr/consents/{consent_id}/verify

Verifies a pending consent request using the OTP the patient received. A successful verification opens a visit and returns the per-visit consent token used to read patient records.

Related documentation: Introduction to the Shared Health Record

consent_id

string · required

Consent id returned by the consent request.

Example: VCR-20260624-13698E26

Payload that verifies a pending consent request with the one-time password the patient received.

otp

string · required

One-time password the patient received from DHA.

Example: 14384

otp_record

string · required

OTP record reference returned by the consent request. It ties the OTP back to the consent it was issued for.

Example: d67p9lhxxx

Consent verified

Result of verifying consent with an OTP. It carries the consent token used to read patient records and the visit the consent opened.

consent_token

string

Per-visit consent token. Send it in the X-Consent-Token header when fetching patient records.

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

message

string

Human readable outcome message from DHA.

Example: Consent verified successfully

status

string

Outcome status reported by DHA.

Example: success

visit_id

string

Identifier of the visit opened by the verified consent. Use it to refresh consent or to close the visit.

Example: f5c2fd92-1847-407f-97b7-a9d277699c22

Poll the status of a consent request

GET

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

/shr/consents/{consent_id}/status

Related documentation: Introduction to the Shared Health Record

consent_id

string · required

Consent id returned by the consent request.

Example: VCR-20260624-13698E26

Consent status

Current status of a consent request. Once the patient has approved, the response also carries the visit id opened for the consent.

consent_id

string

Identifier of the consent request being polled.

Example: VCR-20260624-13698E26

consent_status

string

Current state of the consent request as reported by DHA, for example Pending or Approved.

Example: Approved

message

string

Human readable outcome message from DHA.

Example: Consent status retrieved successfully

status

string

Outcome status reported by DHA.

Example: success

visit_id

string

Identifier of the visit opened against the approved consent. Use it to refresh consent or to close the visit.

Example: f5c2fd92-1847-407f-97b7-a9d277699c22

Resend the consent OTP

POST

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

/shr/consents/{consent_id}/resend-otp

Asks DHA to resend the OTP for a pending consent request. The response carries a fresh otp_record - verify the consent with that value, not the one from the original consent request.

Related documentation: Introduction to the Shared Health Record

consent_id

string · required

Consent id returned by the consent request.

Example: VCR-20260624-13698E26

OTP resent

Result of asking DHA to resend the consent OTP. It echoes the consent the OTP belongs to and carries a fresh OTP record reference.

consent_id

string

Identifier of the consent request the OTP was resent for.

Example: VCR-20260624-13698E26

consent_status

string

Current state of the consent request as reported by DHA.

Example: Pending

message

string

Human readable outcome message from DHA.

Example: OTP resent successfully

otp_record

string

OTP record reference for the newly issued OTP. Use this value, not the earlier one, when verifying the consent.

Example: d67p9lhxxx

status

string

Outcome status reported by DHA.

Example: success

visit_type

string · enum

Type of visit the consent was requested for.

Enum values:

Example: IP

Refresh patient consent for an open visit

POST

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

/shr/visits/{visit_id}/refresh

Refreshes patient consent for an open visit and returns a fresh consent token. Use it when the token issued at verification has expired but the visit is still open.

Related documentation: Introduction to the Shared Health Record

visit_id

string · required

Visit id of the open visit.

Example: f5c2fd92-1847-407f-97b7-a9d277699c22

Consent refreshed

Result of refreshing patient consent for an open visit. It carries a fresh consent token for reading patient records.

consent_token

string

Refreshed per-visit consent token. Replace the token you were using and send this one in the X-Consent-Token header.

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

message

string

Human readable outcome message from DHA.

Example: Patient consent refreshed successfully

status

string

Outcome status reported by DHA.

Example: success

Close an SHR visit

POST

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

/shr/visits/{visit_id}/close

Closes the visit identified by its visit id. Close the visit once the encounter is complete - the consent token can no longer be refreshed afterwards.

Related documentation: Introduction to the Shared Health Record

Close an SHR visit › path Parameters

visit_id

string · required

Visit id to close.

Example: f5c2fd92-1847-407f-97b7-a9d277699c22

Close an SHR visit › Responses

Visit closed

Result of closing an SHR visit. Once closed, the visit's consent token can no longer be refreshed.

consent_id

string

Identifier of the consent request the closed visit belonged to.

Example: VCR-20260624-13698E26

end_date

string

Timestamp at which the visit was closed.

Example: 2026-06-24T14:32:11Z

message

string

Human readable outcome message from DHA.

Example: Visit closed successfully

status

string

Outcome status reported by DHA.

Example: success

visit_id

string

Identifier of the visit that was closed.

Example: f5c2fd92-1847-407f-97b7-a9d277699c22

SHR Consent

Request patient consent for an SHR visit

Request patient consent for an SHR visit › Request Body

Request patient consent for an SHR visit › Responses

Verify patient consent with an OTP

Verify patient consent with an OTP › path Parameters

Verify patient consent with an OTP › Request Body

Verify patient consent with an OTP › Responses

Poll the status of a consent request

Poll the status of a consent request › path Parameters

Poll the status of a consent request › Responses

Resend the consent OTP

Resend the consent OTP › path Parameters

Resend the consent OTP › Responses

Refresh patient consent for an open visit

Refresh patient consent for an open visit › path Parameters

Refresh patient consent for an open visit › Responses

Close an SHR visit

Close an SHR visit › path Parameters

Close an SHR visit › Responses

SHR Consent

Request patient consent for an SHR visit

Request patient consent for an SHR visit › Request Body

Request patient consent for an SHR visit › Responses

Verify patient consent with an OTP

Verify patient consent with an OTP › path Parameters

Verify patient consent with an OTP › Request Body

Verify patient consent with an OTP › Responses

Poll the status of a consent request

Poll the status of a consent request › path Parameters

Poll the status of a consent request › Responses

Resend the consent OTP

Resend the consent OTP › path Parameters

Resend the consent OTP › Responses

Refresh patient consent for an open visit

Refresh patient consent for an open visit › path Parameters

Refresh patient consent for an open visit › Responses

Close an SHR visit

Close an SHR visit › path Parameters

Close an SHR visit › Responses