Shared Health Specification and Guide Version 2.0 Revision F

 

5.1 Shared Health API Summary

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 URL's; 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

5.1 HTTP Request Headers

For PrescribeIT™ there will be three new HTTP headers that will be required in the Formulary, Deferred, and Provider Registry queries. The headers will be for a) Application Instance Identifier, b) CPR ID - Provider, and c) CPR ID - Organization.

These headers are required so that PrescribeIT™ can determine the originator of the query when an application instance is using a hub/routing application. See the table below for conformance rules.

The Application Instance is Mandatory for all queries and will be populated with the sending application instance OID.

HTTP Request Header Conformance Rules Expected Format
X-SHAREDHEALTH-EXCHANGE-SENDING-APP-INSTANCE-ID Mandatory for Formulary (EMR), Deferred (PMS), and Provider Registry queries X-SHAREDHEALTH-EXCHANGE-SENDING-APP-INSTANCE-ID: urn:oid:1.2.0.9.9.4.0994
X-SHAREDHEALTH-EXCHANGE-SENDING-ORGANIZATION-ID

Mandatory for Formulary (EMR) and Deferred (PMS) queries

Must be present when known for Provider Registry queries

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

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

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

Must be present for EMR-initiated Provider Registry queries if value is known.

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

5.2 RouteMessageToInbox

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

X-TELUS-SDF-Developer-Key: <values:>

Note: <value> for X-TELUS-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
Endpoint URL https://EnvironmentSpecificHost/EnvironmentSpecificPathInbox/Bundle
Response Schema OperationOutcome (FHIR doc type http://hl7.org/fhir/operationoutcome.html)
Response Sample 
<OperationOutcome xmlns="http://hl7.org/fhir">
  <id value="101"/>
  <text>
    <status value="additional"/>
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p>W is not a recognized code for Gender.</p>
    </div>
  </text>
  <issue>
    <severity value="error"/>
    <code value="code-invalid"/>
    <details>
      <text value="The code "W" is not known and not legal in this context"/>    
    </details>
    <diagnostics value="Acme.Interop.FHIRProcessors.Patient.processGender line 2453"/>
    <location value="/f:Person/f:gender"/>
  </issue>
</OperationOutcome>
Response Headers Location: $serviceLocation
Service Response HTTP Code header and Payload
  • HTTP 201 for success + payload as (OperationOutcome and an information level issue)
  • HTTP 500 for any backend errors+ payload as (OperationOutcome with error level issue)

5.3 GetMessageFromInbox

API Type REST
Verb GET
Request Content Type N/A
Response Content Type application/xml+fhir
Required Request Headers

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

Note: <value> for X-TELUS-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
Endpoint URL https://EnvironmentSpecificHost/EnvironmentSpecificPathInbox/Bundle
Service Response HTTP Code header and Payload
  • HTTP 200 for success + payload as FHIR bundle
  • HTTP 500 for any backend errors + payload as OperationOutcome with error level issue

5.4 Acknowledge Message

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

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

Note: <value> for X-TELUS-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 acknowledge Messages
Endpoint URL https://EnvironmentSpecificHost/EnvironmentSpecificPath/mailbox_vs0
Service Response HTTP Code header and Payload
  • HTTP 200 for success+ payload as FHIR bundle
  • HTTP 500 for any backend errors + payload as OperationOutcome with error level issue
Request Sample 
<Bundle xmlns="http://hl7.org/fhir">
  <id value="example-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:/EnvironmentSpecificHost/EnvironmentSpecificPathInbox/Bundle/72b23b14-4de1-4139-b644-3a24d01edc79"/>
    </request>
  </entry>
</Bundle>

5.5 PR Get

API Type REST
Verb GET
Required Request Headers

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

Note: <value> for X-TELUS-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
Endpoint URL https://EnvironmentSpecificHost/EnvironmentSpecificPathRegistry/Organization/${CPRID}
https://EnvironmentSpecificHost/EnvironmentSpecificPathRegistry/Practitioner/${CPRID}
Service Response HTTP Code header and Payload
  • HTTP 200 for success
  • HTTP 500 for any backend errors+ Operation Outcome with errors details

5.6 PR Search

API Type REST
Verb GET
Resource URI https://EnvironmentSpecificHost/EnvironmentSpecificPathRegistry/Organization?${OrganizationSearchParameters}
https://EnvironmentSpecificHost/EnvironmentSpecificPathRegistry/Practitioner?${PractitionerSearchParameters}
Search Parameter details
  • FHIR-PR only search for organization/Practitioner with RxExchange contract.
  • FHIR-PR only search for active practitioner
  • FHIR-PR only search for Registered Organization
  • FHIR-PR only search for active contract
  • FHIR-PR not allowed wild cards in parameters value
Required Request Headers

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

Note: <value> for X-TELUS-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
Application Name PrescribeIT™ Provider Registry services Component
Endpoint URL https://EnvironmentSpecificHost/EnvironmentSpecificPathRegistry
Service Response HTTP Code header and Payload
  • HTTP 200 for success
  • HTTP 500 for any backend errors+ Operation Outcome with errors details