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.
Request patient consent for an SHR visit
Initiates a consent request against the DHA Consent Management Platform. On success DHA dispatches a one-time password to the patient and returns a consent_id used by the verify, status and resend-otp calls.
Three kinds of request share this endpoint. A standard request asks the patient directly. An emergency request, for a patient who cannot consent at the point of care, is approved immediately and returns the visit id and consent token in place of a password. A dependant request names a representative - a parent for a minor, or a proxy for an incapacitated adult - and routes the consent to them instead.
Check the List visits with an open consent endpoint first: a patient who already has an open visit at the facility cannot start another.
Related documentation: Introduction to the Shared Health Record
Request patient consent for an SHR visit › Request Body
cr_idClient 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.
facility_idFacility Registry (FR) code of the facility requesting consent.
requested_byName or role of the person requesting consent. Recorded on the consent audit trail.
visit_typeType of visit the consent is being requested for. OP for outpatient, IP for inpatient.
emergencySet 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.
incapacity_reasonWhy 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.
patient_capableSet 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.
practitioner_idPractitioner 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.
representative_cr_idClient 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.
representative_relationshipHow the representative relates to the patient. Required whenever representative_cr_id is provided.
start_dateDate the visit starts, as YYYY-MM-DD. Defaults to the date the consent is created.
Request patient consent for an SHR visit › Responses
Consent request created
consent_idIdentifier of the consent request. Supply it on the verify, status and resend-otp calls.
consent_statusCurrent 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.
consent_tokenPer-visit token used to read patient records. Returned only for an emergency consent, which is approved without a password.
emergencyWhether this consent was granted through the emergency route.
messageHuman readable outcome message from DHA.
otp_recordOTP record reference. Send it back with the OTP when verifying the consent. Absent on an emergency consent, which needs no password.
statusOutcome status reported by DHA.
visit_idIdentifier of the visit the consent opened. Returned only for an emergency consent; on a standard consent the visit id arrives with the verification.
visit_typeType of visit the consent was requested for.
Verify patient consent with an OTP
Records the patient's consent decision. Verifying with the one-time password the patient received opens a visit and returns the per-visit consent token used to read patient records.
The same endpoint records a refusal: send consent_decision as Reject with a rejection_reason, and no token is issued.
It also completes an OTP-gated visit closure. Send the otp_record returned by the Close an SHR visit endpoint together with the password the performer received; the response carries the date the visit closed rather than a consent token.
Related documentation: Introduction to the Shared Health Record
path Parameters
consent_idConsent id returned by the consent request.
Verify patient consent with an OTP › Request Body
agentIdentifier of the agent or channel performing the verification. Resolved from the request headers when omitted.
consent_decisionThe patient's decision. Accepts Approve or Reject, or their numeric forms 1 and 0. Treated as an approval when omitted.
geo_distance_kmDistance in kilometres between where consent was captured and the facility. Captured on the Afyayangu channel.
geo_latLatitude of the location where consent was captured. Captured on the Afyayangu channel.
geo_lonLongitude of the location where consent was captured. Captured on the Afyayangu channel.
otpOne-time password the patient received from DHA. Required on the OTP channel.
otp_recordOTP 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.
rejection_reasonWhy the patient refused consent. Required when consent_decision records a refusal.
Verify patient consent with an OTP › Responses
Consent verified
consent_idIdentifier of the consent that was decided. Returned on refusals and on approvals captured off the one-time password channel.
consent_statusState the consent settled into, for example Approved or Rejected. Returned alongside consent_id.
consent_tokenPer-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.
end_dateDate the visit closed. Returned only when this verification completed an OTP-gated visit closure.
messageHuman readable outcome message from DHA.
statusOutcome status reported by DHA.
visit_idIdentifier of the visit the approved consent opened.
Poll the status of a consent request
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
path Parameters
consent_idConsent id returned by the consent request.
Poll the status of a consent request › Responses
Consent status
consent_idIdentifier of the consent request being polled.
consent_statusCurrent state of the consent request as reported by DHA, for example Pending or Approved.
messageHuman readable outcome message from DHA.
statusOutcome status reported by DHA.
visit_idIdentifier of the visit opened against the approved consent. Use it to refresh consent or to close the visit.
Resend the consent 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
path Parameters
consent_idConsent id returned by the consent request.
Resend the consent OTP › Responses
OTP resent
consent_idIdentifier of the consent request the OTP was resent for.
consent_statusCurrent state of the consent request as reported by DHA.
messageHuman readable outcome message from DHA.
otp_recordOTP record reference for the newly issued OTP. Use this value, not the earlier one, when verifying the consent.
statusOutcome status reported by DHA.
visit_typeType of visit the consent was requested for.
Refresh patient consent for an open visit
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
path Parameters
visit_idVisit id of the open visit.
Refresh patient consent for an open visit › Responses
Consent refreshed
consent_tokenRefreshed per-visit consent token. Replace the token you were using and send this one in the X-Consent-Token header.
messageHuman readable outcome message from DHA.
statusOutcome status reported by DHA.
Close an SHR visit
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.
Closure is normally gated by a one-time password sent to whoever gave consent: the response carries an otp_record, and the visit closes only once that password is verified through the Verify patient consent with an OTP endpoint. Where the deployment has OTP-gated closure switched off, or consent was given by a healthcare proxy, the visit closes immediately and the response carries the end date instead.
To close a visit for a patient who cannot consent to the closure - unconscious or deceased - send the optional body with patient_incapable set to 1. The visit then closes immediately, with no password sent or required.
Related documentation: Introduction to the Shared Health Record
path Parameters
visit_idVisit id to close.
Close an SHR visit › Request Body optional
incapacity_reasonWhy the patient cannot consent to the closure. Required when patient_incapable is 1.
patient_incapableSet 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.
Close an SHR visit › Responses
Visit closed, or a closure one-time password dispatched
consent_idIdentifier of the consent request the closed visit belonged to.
end_dateDate the visit was closed. Returned on an immediate closure.
messageHuman readable outcome message from DHA.
otp_recordOTP record reference for a closure awaiting verification. Send it, with the password the performer received, to Verify Consent OTP to complete the closure.
statusOutcome status reported by DHA.
visit_idIdentifier of the visit that was closed.
List visits with an open consent
Lists the visits at a facility that still hold an open patient consent. Call it before starting a fresh consent request: if the patient already has an open visit at your facility you can keep using it - refresh its consent token with POST /shr/visits/{visit_id}/refresh - instead of putting the patient through another OTP.
The response carries the visit ids only. Anything else you need about the visit comes from the consent status or refresh calls.
Related documentation: Introduction to the Shared Health Record
query Parameters
patient_idClient Registry (CR) identifier of the patient whose open visits are being listed. Sent upstream as the patient's Client Registry id.
facility_idFacility Registry (FR) code of the facility the visits belong to.
List visits with an open consent › Responses
Open consent visits
messageHuman readable outcome message from DHA.
statusOutcome status reported by DHA.
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.