Shared Health Specification and Guide Version 5.0

 

This section provides details on the APIs that have been defined for the Shared Health domain and shown in the diagram below. The full list of APIs and a description is provided for completeness. PrescribeIT® domain APIs are included on the PrescribeIT® API Summary page.

The endpoints will vary by environment (e.g. Production, Pre-conformance) and may also be context specific. Implementers should make the endpoints' URLs configurable within their systems as these may be updated in future releases. Vendors should not be storing the organization/practitioner URLs; rather they should build it at runtime using configurable prefix's per environment and the identifier itself. The real URLs will be published to Vendors upon onboarding with PrescribeIT®.

API Overview diagram
API Initiated by Description Method

RequestOTP

PrescribeIT® Domain

EMR Request a OTP. Further information can be found here POST

Request Token

PrescribeIT® Domain

EMR Request a secure token. Further information can be found here POST

RouteMessageToInbox

Shared Health Domain

EMR and PMS

https://EnvironmentSpecificHost/EnvironmentSpecificPathInbox/Bundle

Post a 101, 201, 305, 401, 997, 998, 999 interaction

Further information can be found here

POST

GetMessageFromInbox

Shared Health Domain

EMR and PMS

https://EnvironmentSpecificHost/EnvironmentSpecificPathInbox/Bundle

This API is used to retrieve bundles containing 101, 201, 305, 901, 997, 998, and 999 interactions. Further information can be found here

This API is also used to GET Deferred Prescriptions. This is triggered when a patient arrives in the Pharmacy with an electronic receipt for a Deferred prescription.

Further information can be found here

GET

Formulary Operation

PrescribeIT® Domain

https://EnvironmentSpecificHost/EnvironmentSpecificPathInbox/$Formulary

This API is also used for Formulary Queries - triggered by EMR to obtain formulary information at time of prescribing. Further information can be found here

GET

AcknowledgeMessage

Shared Health Domain

EMR and PMS

https://EnvironmentSpecificHost/EnvironmentSpecificPathInbox

Acknowledge receipt of Bundles containing 101, 201, 305, 901, 997, 998, and 999 using the BatchClearMessageQueue Request

Deferred messages must also be acknowledged

Further information can be found here, here and here

POST

Attachment Upload

PrescribeIT® Domain

EMR and PMS

https://EnvironmentSpecificHost/EnvironmentSpecificPathInbox/Binary/${AttachmentId}

Supports 305 communication with attachments.

Triggered by the presence of an attachment URL within the 305 message.

Further information can be found here and here

PUT

Attachment Download

PrescribeIT® Domain
EMR and PMS

https://EnvironmentSpecificHost/EnvironmentSpecificPathInbox/Binary/${AttachmentId}

Supports 305 communication with attachments.

Triggered by the presence of an attachment URL within the 305 message.

Further information can be found here and here

GET

Get/Search Org

Shared Health Domain

EMR and PMS https://EnvironmentSpecificHost/EnvironmentAndContextSpecificPathRegistry/Organization

EMR or PMS will invoke this service to search or retrieve an Organization (clinic or Pharmacy) record.

May be used by EMR to retrieve their own Organization record

Further information can be found here and here

GET

Get/Search Practitioner

Shared Health Domain
EMR and PMS

https://EnvironmentSpecificHost/EnvironmentAndContextSpecificPathRegistry/Practitioner

PMS will invoke this service to search or retrieve a Practitioner record.

May be used by EMR to retrieve their own Practitioner record

Further information can be found here and here

GET

For PrescribeIT® there are HTTP headers that will be required in the Formulary, Deferred, and Provider Registry queries as well as when returning retrieved deferred bundles back to PrescribeIT®. The headers will be for a) Application Instance Identifier, b) Practitioner CPRID, and c) Organization CPRID.

These headers are required so that PrescribeIT® can determine the originator of the query. See the table below for conformance rules.

HTTP Request Header Conformance Rules Expected Format
X-SHAREDHEALTH-EXCHANGE-SENDING-APP-INSTANCE-ID Mandatory for Formulary Query (EMR), Deferred Query (PMS), and Return Retrieved Deferred Bundle request X-SHAREDHEALTH-EXCHANGE-SENDING-APP-INSTANCE-ID: urn:oid:1.2.0.9.9.4.0994
X-SHAREDHEALTH-EXCHANGE-SENDING-PRACTITIONER-ID

Not applicable for Deferred (PMS) or PMS-initiated Provider Registry queries

Optional for Formulary queries but can be provided if Practitioner is enrolled and known

X-SHAREDHEALTH-EXCHANGE-SENDING-PRACTITIONER-ID: http://sharedhealth.exchange/fhir/NamingSystem/registry-id-practitioner|190000074
X-SHAREDHEALTH-EXCHANGE-SENDING-ORGANIZATION-ID

Mandatory for Formulary Query (EMR), Deferred Query (PMS), Provider Registry queries, and Return Retrieved Deferred Bundle request

X-SHAREDHEALTH-EXCHANGE-SENDING-ORGANIZATION-ID: http://sharedhealth.exchange/fhir/NamingSystem/registry-id-organization|190001234
API Type REST
Verb POST
Request/Response Content Type application/xml+fhir
Required Request Headers

X-SHX-SDF-Developer-Key: <value>

NOTE: <value> for X-SHX-SDF-Developer-Key is unique for each caller location. It is a credential which is supplied along with the SDF certificate to each location during its on-boarding.

Accept: application/xml+fhir
Content-Type: application/xml+fhir

Description Service to route EMR/PMS transactions to central services
Production Endpoint URL https://api.sharedhealth.exchange/rest/v1/THP/mailbox_vs0/Bundle
Pre-Conformance Endpoint URL https://api.sharedhealth.exchange/rest/v1/preconf/THP/mailbox_vs1/Bundle
Response Schema OperationOutcome
Response Sample
<OperationOutcome xmlns="http://hl7.org/fhir">
	<id value="0b1f172e-572b-4d84-a35e-8065ef4d9a07"/>
	<issue>
		<extension url="http://sharedhealth.exchange/fhir/StructureDefinition/ext-operationoutcome-usertext">
			<valueString value="Please log into PrescribeIT again.  If issue persists, please call Technical Support Team and provide the Detail Code and Reference Number shown below. 
 Detail Code ISS142 - Reference # 72efc58a-1f1a-44d9-b964-1cebd10eb04f.">
				<extension url="http://hl7.org/fhir/StructureDefinition/iso21090-ST-translation">
					<valueString value="Veuillez vous reconnecter à PrescripTIon. Si le problème persiste, communiquez avec le soutien technique et fournissez-lui le code de détail et le numéro de référence indiqués ci-dessous. 
 Code de détail ISS142 - Numéro de référence 72efc58a-1f1a-44d9-b964-1cebd10eb04f.">
						<extension url="http://hl7.org/fhir/StructureDefinition/iso21090-ST-language">
							<valueCode value="fr-CA"/>
						</extension>
					</valueString>
				</extension>
			</valueString>
		</extension>
		<extension url="http://sharedhealth.exchange/fhir/StructureDefinition/ext-operationoutcome-referencenum">
			<valueString value="72efc58a-1f1a-44d9-b964-1cebd10eb04f"/>
		</extension>
		<severity value="error"/>
		<code value="security"/>
		<details>
			<coding>
				<code value="ISS142"/>
			</coding>
			<text value="Invalid SAML claim."/>
		</details>
	</issue>
</OperationOutcome>
Response Headers X-SHX-SDF-TraceId - unique identifier of this transaction generated by the server. In case of success, the value returned in this header also becomes the Bundle ID of the accepted message
Service Response HTTP Code header and Payload
  • HTTP 201 for success. Response payload is usually empty except in a couple scenarios where an operation outcome is returned with an information type of issue. This happens in the scenario of duplicate message or when a message is accepted but not delivered to its destination. In the scenario of a 401 Response the response payload contains an updated FHIR message containing additional bundle-level metadata (message key, last name and birth date tags)
  • HTTP 4xx or HTTP 5xx for any backend errors + payload. Payload format depends on whether the error is coming from the SDF (API gateway) or PrescribeIT® Central Service. In case of the SDF failure, the response is in custom XML format, in case of PrescribeIT® Central Service the response is an OperationOutcome object
API Type REST
Verb GET
Request Content Type N/A
Response Content Type application/xml
Required Request Headers

X-SHX-SDF-Developer-Key: <value>

NOTE: <value> for X-SHX-SDF-Developer-Key is unique for each caller location. It is a credential which is supplied along with the SDF certificate to each location during its on-boarding.

Accept: application/xml+fhir

Description Service to get messages from inbox
Production Endpoint URL https://api.sharedhealth.exchange/rest/v1/THP/mailbox_vs0/Bundle
Pre-Conformance Endpoint URL https://api.sharedhealth.exchange/rest/v1/preconf/THP/mailbox_vs1/Bundle
Response Headers X-SHX-SDF-TraceId - unique identifier of this transaction generated by the server
Service Response HTTP Code header and Payload
  • HTTP 200 for success + payload as FHIR bundle
  • HTTP 4xx or HTTP 5xx for any backend errors + payload. Payload format depends on whether the error is coming from the SDF (API gateway) or PrescribeIT® Central Service. In case of the SDF failure, the response is in custom XML format, in case of PrescribeIT® Central Service the response is an OperationOutcome object
Response Sample See Multi-page poll response for physician tasks.
API Type REST
Verb POST
Request/Response Content Type application/xml
Required Request Headers

X-SHX-SDF-Developer-Key: <value>

NOTE: <value> for X-SHX-SDF-Developer-Key is unique for each caller location. It is a credential which is supplied along with the SDF certificate to each location during its on-boarding.

Accept: application/xml+fhir
Content-Type: application/xml

Description Service to acknowledge messages
Production Endpoint URL https://api.sharedhealth.exchange/rest/v1/THP/mailbox_vs0
Pre-Conformance Endpoint URL https://api.sharedhealth.exchange/rest/v1/preconf/THP/mailbox_vs1
Response Headers X-SHX-SDF-TraceId - unique identifier of this transaction generated by the server
Service Response HTTP Code header and Payload
  • HTTP 200 for success + payload as FHIR bundle. NOTE: any failure(s) encountered during the acknowledgment of the individual message(s) will be reported in the response payload, in this case HTTP 200 will still be returned from the API call
  • HTTP 4xx or HTTP 5xx for any backend errors + payload. Payload format depends on whether the error is coming from the SDF (API gateway) or PrescribeIT® Central Service. In case of the SDF failure, the response is in custom XML format, in case of PrescribeIT® Central Service the response is an OperationOutcome object
Request Sample
<Bundle xmlns="http://hl7.org/fhir">
	<id value="message-clear-queue-request"/>
	<meta>
		<profile value="http://sharedhealth.exchange/fhir/StructureDefinition/interaction-bundle-clear-queue-request/"/>
	</meta>
	<type value="batch"/>
	<entry>
		<request>
			<method value="DELETE"/>
			<url value="https://SDF.Telus.com/mailbox/v1/Bundle/54a05d42-5da2-4c8c-8e14-876441d71b70"/>
		</request>
	</entry>
	<entry>
		<request>
			<method value="DELETE"/>
			<url value="https://SDF.Telus.com/mailbox/v1/Bundle/1377f0f6-243a-4c07-964b-8a46143f3cc4"/>
		</request>
	</entry>
</Bundle>
          
Sample Response
<Bundle xmlns="http://hl7.org/fhir">
   <id value="3079b918-8fcc-45cf-b64b-a1629337f889"/>
   <meta>
      <profile value="http://sharedhealth.exchange/fhir/StructureDefinition/interaction-bundle-clear-queue-response"/>
   </meta>
   <type value="batch-response"/>
   <entry>
      <response>
         <status value="202 Accepted"/>
      </response>
   </entry>
   <entry>
      <response>
         <status value="202 Accepted"/>
      </response>
   </entry>
</Bundle>

API Type REST
Verb POST
Request/Response Content Type application/xml
Required Request Headers

X-SHX-SDF-Developer-Key: <value>

NOTE: <value> for X-SHX-SDF-Developer-Key is unique for each caller location. It is a credential which is supplied along with the SDF certificate to each location during its on-boarding.

Accept: application/xml+fhir
Content-Type: application/xml

Description Service to return (cancel) retreived messages
Production Endpoint URL https://api.sharedhealth.exchange/rest/v1/THP/mailbox_vs0
Pre-Conformance Endpoint URL https://api.sharedhealth.exchange/rest/v1/preconf/THP/mailbox_vs1
Response Headers X-SHX-SDF-TraceId - unique identifier of this transaction generated by the server
Service Response HTTP Code header and Payload
  • HTTP 200 for success + payload as FHIR bundle. NOTE: any failure(s) encountered during the cancel retrieval of the individual message(s) will be reported in the response payload, in this case HTTP 200 will still be returned from the API call
  • HTTP 4xx or HTTP 5xx for any backend errors + payload. Payload format depends on whether the error is coming from the SDF (API gateway) or PrescribeIT® Central Service. In case of the SDF failure, the response is in custom XML format, in case of PrescribeIT® Central Service the response is an OperationOutcome object
Request Sample
<Bundle xmlns="http://hl7.org/fhir">
	<id value="message-clear-queue-request"/>
	<meta>
		<profile value="http://sharedhealth.exchange/fhir/StructureDefinition/interaction-bundle-clear-queue-request/"/>
	</meta>
	<type value="batch"/>
	<entry>
		<request>
			<method value="PUT">
				<extension url="http://sharedhealth.exchange/fhir/StructureDefinition/ext-bundle-cancel-retrieval-reason">
					<valueCodeableConcept>
						<coding>
							<system value="http://terminology.hl7.org/CodeSystem/v3-ActReason"/>
							<code value="PATDEC"/>
							<display value="patient changed mind"/>
						</coding>
					</valueCodeableConcept>
				</extension>
			</method>
			<url value="https://SDF.Telus.com/mailbox/v1/Bundle/54a05d42-5da2-4c8c-8e14-876441d71b70"/>
		</request>
	</entry>
</Bundle>
          
Sample Response The response below is an Error example. See Acknowledge Message sample response above for a 202 Accepted example.
<Bundle xmlns="http://hl7.org/fhir">
   <id value="3079b918-8fcc-45cf-b64b-a1629337f889"/>
   <meta>
		<profile value="http://sharedhealth.exchange/fhir/StructureDefinition/interaction-bundle-clear-queue-response"/>
		<tag>
			<system value="https://fhir.infoway-inforoute.ca/CodeSystem/sharedspecificationversion"/>
			<code value="Shared5.0"/>
		</tag>
	</meta>
	<type value="batch-response"/>
	<entry>
		<response>
			<status value="ISS580 We are unable to process this request (clear-message-queue).  When the method of PUT is used, a 'cancel reason' must be provided.  Please provide a 'cancel reason' and resubmit.">
				<extension url="http://hl7.org/fhir/StructureDefinition/iso21090-ST-translation">
					<valueString value="ISS580 Il est impossible de traiter cette demande d’effacer la file d’attente des messages (clear-message-queue). Il est obligatoire de fournir un motif de l’annulation lorsque l’action PUT (placez) est utilisée. Veuillez fournir un motif d’annulation et soumettre la demande à nouveau">
						<extension url="http://hl7.org/fhir/StructureDefinition/iso21090-ST-language">
							<valueCode value="fr"/>
						</extension>
					</valueString>
				</extension>
			</status>
		</response>
	</entry>
</Bundle>

API Type REST
Verb GET
Required Request Headers

X-SHX-SDF-Developer-Key: <value>

NOTE: <value> for X-SHX-SDF-Developer-Key is unique for each caller location. It is a credential which is supplied along with the SDF certificate to each location during its on-boarding.

Accept: application/xml+fhir

Response Content Type application/xml+fhir
Description Service to get organization or practitioner FHIR bundle by ID
Production Endpoint URL https://api.sharedhealth.exchange/rest/v1/THP/TPR_vs0/Organization/${CPRID}
https://api.sharedhealth.exchange/rest/v1/THP/TPR_vs0/Practitioner/${CPRID}
Pre-Conformance Endpoint URL https://api.sharedhealth.exchange/rest/v1/preconf/THP/TPR_vs1/Organization/${CPRID}
https://api.sharedhealth.exchange/rest/v1/preconf/THP/TPR_vs1/Practitioner/${CPRID}
Response Headers X-SHX-SDF-TraceId - unique identifier of this transaction generated by the server
Service Response HTTP Code header and Payload
  • HTTP 200 for success, response payload is Organization or Practitioner object in FHIR format
  • HTTP 4xx or HTTP 5xx for any backend errors + payload. Payload format depends on whether the error is coming from the SDF (API gateway) or PrescribeIT® Central Service. In case of the SDF failure, the response is in custom XML format, in case of PrescribeIT® Central Service the response is an OperationOutcome object

API Type REST
Verb GET
Production Endpoint URL

https://api.sharedhealth.exchange/rest/v1/THP/TPR_vs0/Organization?${OrganizationSearchParameters}
https://api.sharedhealth.exchange/rest/v1/THP/TPR_vs0/Practitioner?${PractitionerSearchParameters}

Pre-Conformance Endpoint URL

https://api.sharedhealth.exchange/rest/v1/preconf/THP/TPR_vs1/Organization?${OrganizationSearchParameters}
https://api.sharedhealth.exchange/rest/v1/preconf/THP/TPR_vs1/Practitioner?${PractitionerSearchParameters}

Search Parameter details
  • Search returns only organizations/practitioners with active PrescribeIT® and/or Clinician Communication contracts
  • Wildcards in parameter values are not allowed
Required Request Headers

X-SHX-SDF-Developer-Key: <value>

NOTE: <value> for X-SHX-SDF-Developer-Key is unique for each caller location. It is a credential which is supplied along with the SDF certificate to each location during its on-boarding.

Accept: application/xml+fhir

Response Content Type application/xml+fhir
Description Service to search organization or practitioner by search parameters
Response Headers X-SHX-SDF-TraceId - unique identifier of this transaction generated by the server
Service Response HTTP Code header and Payload
  • HTTP 200 for success, response payload contains search results in FHIR format
  • HTTP 4xx or HTTP 5xx for any backend errors + payload. Payload format depends on whether the error is coming from the SDF (API gateway) or PrescribeIT® Central Service. In case of the SDF failure, the response is in custom XML format, in case of PrescribeIT® Central Service the response is an OperationOutcome object

API Type REST
Verb POST
Production Endpoint URL https://api.sharedhealth.exchange/rest/v1/THP/TPR_vs0/Organization/_search?_query=bulkSync
Pre-Conformance Endpoint URL https://api.sharedhealth.exchange/rest/v1/preconf/THP/TPR_vs1/Organization/_search?_query=bulkSync
Search Parameter details

As per the FHIR Search this is a POST using the standard application/x-www-form-urlencoded.

This endpoint will support two use cases as described in Group No 4 Bulk TPR Queries:

Periodic Sync of Matched Records

Supported parameters are:

  • role=OUTPHARM (required, 1..1)
  • identifier (required, 1..*)
  • _lastUpdated (optional, 0..1) "gt" is mandatory as this is the only supported date prefix. Example (non-encoded): &_lastUpdated=gt2020-10-01T10:00:00

Bulk Update of unmatched Records

Supported parameters are:

  • role=OUTPHARM (required, 1..1)
  • telecom-fax:exact (required, 1..*)
Required Request Headers

X-SHX-SDF-Developer-Key: <value>

NOTE: <value> for X-SHX-SDF-Developer-Key is unique for each caller location. It is a credential which is supplied along with the SDF certificate to each location during its on-boarding.

Accept: application/xml+fhir

Content-Type: application/x-www-form-urlencoded

Example Query Request

POST https://api.sharedhealth.exchange/rest/v1/THP/TPR_vs0/Organization/_search?_query=bulkSync

Body:

role=OUTPHARM&telecom-fax:exact=5555551212,905673435,4162004566

Response Content Type application/xml+fhir
Description

Service to search organizations to support bulk registry queries.

Response will be a searchset bundle using the TPR Organization query response

HTTP 200 for success

HTTP 500 for any backend errors+ Operation Outcome with errors details.

Response Headers X-SHX-SDF-TraceId - unique identifier of this transaction generated by the server