SHR Service APIs

Schemas

Payload that initiates a Shared Health Record consent request against the DHA Consent Management Platform. The same payload covers three cases. A **standard** request carries only the four required fields plus `practitioner_id`. An **emergency** request adds `emergency` and `incapacity_reason` for a patient who cannot consent at the point of care. A **dependant** request adds `representative_cr_id` and `representative_relationship`, which route the consent - and its one-time password - to the representative instead of the patient.

cr_id

string · required

Client Registry (CR) identifier of the patient whose records the consent covers. For a dependant request this stays the dependant's identifier; the representative is named separately.

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

emergency

integer · enum

Set to 1 for an emergency consent, where the patient is incapacitated and consent cannot be collected at the point of care. incapacity_reason is required alongside it. An emergency consent is approved immediately, so the response carries the visit id and consent token rather than an OTP record.

Enum values:

Example: 1

incapacity_reason

string

Why the patient cannot consent for themselves. Required for an emergency consent, and for a dependant request where patient_capable is 0 and the patient is an adult.

Example: Emergency patient

patient_capable

integer · enum

Set to 0 when the patient cannot consent for themselves, for example an incapacitated adult. Defaults to 1. When 0, representative_cr_id is required, and incapacity_reason is required as well unless the patient is a minor.

Enum values:

Example: 1

practitioner_id

string

Practitioner Unique Identifier (PUID) of the clinician requesting consent. Send this on every request - the Consent Management Platform expects it, even though the HIE does not reject a request without it.

Example: PUID-0000443-3

representative_cr_id

string

Client Registry identifier of the principal consenting on the patient's behalf. Provide it whenever cr_id refers to a dependant - a minor, or a patient with patient_capable set to 0. The consent request and its OTP are then routed to the representative, who becomes the record's principal.

Example: CR08244412193-5

representative_relationship

string · enum

How the representative relates to the patient. Required whenever representative_cr_id is provided.

Enum values:

Healthcare Proxy

Sibling

Principal

Other

Example: Healthcare Proxy

start_date

string · date

Date the visit starts, as YYYY-MM-DD. Defaults to the date the consent is created.

Example: 2026-07-18

Result of creating a consent request. On a standard request DHA dispatches a one-time password to the patient and returns the consent id used by the verify, status and resend-otp calls. An **emergency** request is approved on the spot instead: no password is sent, and the response carries `visit_id` and `consent_token` directly, so records can be read immediately.

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, or Approved for an emergency consent.

Example: Pending

consent_token

string

Per-visit token used to read patient records. Returned only for an emergency consent, which is approved without a password.

Example: eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIyNjYzOW

emergency

boolean

Whether this consent was granted through the emergency route.

Example: true

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. Absent on an emergency consent, which needs no password.

Example: d67p9lhxxx

status

string

Outcome status reported by DHA.

Example: success

visit_id

string

Identifier of the visit the consent opened. Returned only for an emergency consent; on a standard consent the visit id arrives with the verification.

Example: 47f7e19f-89f8-49a2-9b05-efa749793ce7

visit_type

string · enum

Type of visit the consent was requested for.

Enum values:

Example: IP

gitlab_slade360emr_com_sha-edi_hie-middleware_internal_dto.ErrorResponse

Standard error response format for all error conditions.

error

string

HTTP status text from the standard HTTP status codes.

Example: Bad Request

message

string

Detailed error message explaining what went wrong.

Example: consent_id path parameter is required

trace_id

string

Trace id for the request. Quote it when reporting an issue so the request can be located.

Example: 4bf92f3577b34da6a3ce929d0e0e4736

Payload that records the patient's consent decision. For the one-time password channel, send `otp_record` and `otp`. Add `consent_decision` to record a refusal - a consent that cannot be refused is not consent - together with `rejection_reason`. The same endpoint also completes an OTP-gated visit closure: send the `otp_record` returned by Close Visit with the password the performer received, and the visit closes without a new consent token being issued. No single field is mandatory on its own, because the combination depends on the channel. Sending an empty body is accepted by the HIE and rejected upstream.

agent

string

Identifier of the agent or channel performing the verification. Resolved from the request headers when omitted.

Example: DHABPxxxxx0

consent_decision

string · enum

The patient's decision. Accepts Approve or Reject, or their numeric forms 1 and 0. Treated as an approval when omitted.

Enum values:

Approve

Reject

Example: 1

geo_distance_km

number · float

Distance in kilometres between where consent was captured and the facility. Captured on the Afyayangu channel.

Example: 10

geo_lat

number · float

Latitude of the location where consent was captured. Captured on the Afyayangu channel.

Example: -1.2921

geo_lon

number · float

Longitude of the location where consent was captured. Captured on the Afyayangu channel.

Example: 36.8219

otp

string

One-time password the patient received from DHA. Required on the OTP channel.

Example: 14384

otp_record

string

OTP record reference. Use the value returned by the consent request to verify consent, or the value returned by Close Visit to complete an OTP-gated closure. Required on the OTP channel.

Example: d67p9lhxxx

rejection_reason

string

Why the patient refused consent. Required when consent_decision records a refusal.

Example: Patient denied consent

Result of recording a consent decision. On an approval through the one-time password channel, the response carries the visit id and the per-visit consent token used to read patient records. On a refusal, or an approval captured off the password channel, it reports the consent id and its resulting status instead of a token. When the verification completed an OTP-gated visit closure, it carries the date the visit closed.

consent_id

string

Identifier of the consent that was decided. Returned on refusals and on approvals captured off the one-time password channel.

Example: VCR-20260624-13698E26

consent_status

string

State the consent settled into, for example Approved or Rejected. Returned alongside consent_id.

Example: Approved

consent_token

string

Per-visit token used to read patient records. Send it in the X-Consent-Token header. Issued on an approval through the one-time password channel; a closure verification does not issue one.

Example: eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmOTI3OWM3OC1lNTVlLTQ1MDAtYTBlNS1hOGRlMTQxMzM3YjciLCJzdWIiOiJDUjA4MjQ0NDEyMTkzMjktNSJ9

end_date

string · date

Date the visit closed. Returned only when this verification completed an OTP-gated visit closure.

Example: 2026-07-15

message

string

Human readable outcome message from DHA.

Example: Consent has been approved. Please use the token provided to access patient records.

status

string

Outcome status reported by DHA.

Example: success

visit_id

string

Identifier of the visit the approved consent opened.

Example: 8e7559bf-a509-468b-9be4-74150b978e9e

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

internal_domain_shr.ResendOTPResponse

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

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

gitlab_slade360emr_com_sha-edi_hie-middleware_internal_dto.CloseVisitInput

Optional body for closing a visit. Send it only when the patient cannot consent to the closure themselves; omit it entirely for a normal closure. The visit is identified by the path, so no identifier is carried here.

incapacity_reason

string

Why the patient cannot consent to the closure. Required when patient_incapable is 1.

Example: Unconscious

patient_incapable

integer · enum

Set to 1 when the patient cannot consent to closing the visit - for example unconscious or deceased. The visit then closes immediately, with no one-time password sent or required.

Enum values:

Example: 1

internal_domain_shr.CloseVisitResponse

Result of closing an SHR visit. An immediate closure carries the end date and the visit is already closed. An OTP-gated closure carries `otp_record` instead: the visit stays open until that password is verified through Verify Consent OTP. 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 · date

Date the visit was closed. Returned on an immediate closure.

Example: 2026-07-15

message

string

Human readable outcome message from DHA.

Example: Consent closure initiated.

otp_record

string

OTP record reference for a closure awaiting verification. Send it, with the password the performer received, to Verify Consent OTP to complete the closure.

Example: 9fh38gd21k

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

internal_domain_shr.OpenVisit

A visit that still holds an open patient consent.

visit_id

string

Identifier of the open visit. Use it to refresh the consent token for the visit or to close it.

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

internal_domain_shr.OpenVisitsResponse

The visits that still hold an open patient consent for a patient at a facility.

message

string

Human readable outcome message from DHA.

Example: Open consent visits retrieved successfully

status

string

Outcome status reported by DHA.

Example: success

object[]

Visits with an open consent. An empty array means the patient has no open visit at this facility, so a fresh consent request is needed.

internal_domain_shr.SubmitBundleResponse

Acknowledgement that a FHIR bundle was accepted and queued by the Shared Health Record. Processing is asynchronous, so this confirms receipt rather than persistence.

mediator_id

string

The id of the bundle you submitted, echoed back so you can correlate this acknowledgement with the submission. Quote it when following up.

Example: 07c06203-d3a0-4126-a4a1-4f24c97158de

message

string

Human readable outcome message from DHA.

Example: Bundle submitted successfully

status

string

Outcome status reported by DHA.

Example: success

Schemas

gitlab_slade360emr_com_sha-edi_hie-middleware_internal_dto.ConsentRequestInput

internal_domain_shr.ConsentRequestResponse

gitlab_slade360emr_com_sha-edi_hie-middleware_internal_dto.ErrorResponse

gitlab_slade360emr_com_sha-edi_hie-middleware_internal_dto.ConsentVerifyInput

internal_domain_shr.VerifyConsentResponse

internal_domain_shr.ConsentStatusResponse

internal_domain_shr.ResendOTPResponse

internal_domain_shr.RefreshConsentResponse

gitlab_slade360emr_com_sha-edi_hie-middleware_internal_dto.CloseVisitInput

internal_domain_shr.CloseVisitResponse

internal_domain_shr.OpenVisit

internal_domain_shr.OpenVisitsResponse

internal_domain_shr.SubmitBundleResponse

Schemas

gitlab_slade360emr_com_sha-edi_hie-middleware_internal_dto.ConsentRequestInput

internal_domain_shr.ConsentRequestResponse

gitlab_slade360emr_com_sha-edi_hie-middleware_internal_dto.ErrorResponse

gitlab_slade360emr_com_sha-edi_hie-middleware_internal_dto.ConsentVerifyInput

internal_domain_shr.VerifyConsentResponse

internal_domain_shr.ConsentStatusResponse

internal_domain_shr.ResendOTPResponse

internal_domain_shr.RefreshConsentResponse

gitlab_slade360emr_com_sha-edi_hie-middleware_internal_dto.CloseVisitInput

internal_domain_shr.CloseVisitResponse

internal_domain_shr.OpenVisit

internal_domain_shr.OpenVisitsResponse

internal_domain_shr.SubmitBundleResponse