HL7 FHIR eReferral API Implementation Guidance


We're Looking Forward to Connecting With You!

The purpose of this article is to accelerate your HL7 FHIR eReferral implementation activities by sharing guidance and considerations collected from other Ocean HL7 FHIR eReferral implementations.  It is divided into the following sections:  
    • Authentication Documentation - related to Ocean’s OAuth2 implementation
    • API Documentation - related to Ocean’s implementation of the Ontario HL7 FHIR eReferral implementation guide
    • Data Mapping - guidance on the intent and usage of various FHIR resource fields in the context of the Ocean implementation
    • Technical Considerations - things to consider when developing your APIs
    • Implementation and Testing - tips for assessing the integration behaviour within Ocean 

This will be a 'living' support article as additional guidance is collected. It is suggested that you ‘follow’ it in order to receive a notification when it is updated.   Updated content since the previous published version will be preceded by *** 


Definitions Used In This Article

Requestor - the individual (provider or patient) that is submitting a referral request.

Service Provider - the clinical or community-based service/organization/provider that is receiving a referral request to deliver a service to the patient

RMS Target - the system(s) downstream from Ocean that is receiving and acting upon an eReferral.

Service Request ID - this corresponds in the FHIR messages to Ocean’s referral identifier

SiteID - Ocean’s identifier for the site set up by the service provider within Ocean to send and/or receive (and manage) eReferrals


Authentication Documentation

  • In order to set the OAuth2 Credentials in the Ocean Portal, you must have the site’s Shared Encryption Key (SEK) (see Step 2 here).  If you do not already have it, the Ocean site administrator can provide this you or it can be retrieved from Cloud Connect.   See here for other options
  • ***The URL for the OAuth2 bearer token request within Ocean's test environment is https://test.cognisantmd.com/svc/oauth2/token  (the OAuth 2.0 Authorization Server documentation refers to the production environment).
  • Ocean returns the standard 401/403 response error codes for authorization-related errors around accessing our secured endpoints through OAuth2.
  • If you become locked out of the OAuth2 token exchange, this can be reset by the site administrator.  They can access the Site Admin > Site Credentials > OAuth credentials page and click on the padlock icon.


API Documentation

  • *** Ocean's eReferral FHIR APIs comply with v0.10.0 of the Ontario eReferral Implementation Guide. There is a more recent version (v0.10.1) that introduces 'breaking changes' (i.e. not backwards compatible) in the MessageEventCode value set that are not supported by Ocean at this time.  
  • The Ontario eReferral Implementation guide has a Profiles and Operations section that includes links to specific profiling documentation for each FHIR resource used in the specification. Each of these profiles lists for each field whether that field is required (the big red S), the required cardinality of the field, the accepted enum values if that field is an enum, any specific invariants that the field is associated with, and any other relevant information associated with it.  For example, the telecom field on the Patient Resource  has been profiled such that it is required, and the system, value and use sub-fields are required but not the rank or period sub-fields.
  • Ocean’s response/error handling follows the guidance included in the Ontario eReferral HL7 FHIR Implementation Guide and the general FHIR messaging documentation:
  • Successful messages will return a 200 response code.  The body is immaterial, as a 200 code means Ocean successfully received and processed the referral.
  • Messages that Ocean cannot process for any reason (bad data, missing data, unparseable JSON, etc) will return a 40X/50X response code with a FHIR OperationOutcome Resource as the body that will have a description of the error.  It includes an ‘issues' section where the server will present some human-readable debugging information to assist in determining the reason the error was issued. That information can be anything from JSON parse errors, specification validation errors (missing required fields or using the wrong datatypes), business logic errors (e.g. trying to update a referral that doesn’t exist) and internal processing exceptions on our end (usually bugs). With this information and the error response, there’s usually enough to go on to try and find the underlying issue efficiently. 
  • Ocean does not send a Task resource in any of its messages.   The Task resource is only sent by the RMS Target system to indicate how the original ServiceRequest has been acted upon by RMS Target.  The API documentation includes examples of the Task resource in the inbound message events sent to Ocean by the RMS Target.
  • Ocean will ignore any empty demographic fields sent in the Update-Service-Request message from the RMS Target (rather than overwriting/deleting the existing value).
  • The OAuth2 token sent by the RMS Target provides Ocean with the information that is necessary to derive which site the message belongs to (since every token pattern is site-specific).    This is why the Ocean site ID does not need to be conveyed in the payload.
  • The RefID is used by Ocean to determine which specific eReferral the payload refers to within the Ocean site. 
  • If the RMS Target sends Ocean two FHIR Patient addresses, Ocean will store both but will only display the first one in the payload.   If more than two addresses are sent, Ocean will ignore all but the first two in the structure. 
  • The bundle will contain two PractitionerRole resources.  One is the describing the requestor and the other is describing the service provider.  There are links in the ServiceRequest/MessageHeader that establish which resource is connected to each practitioner.
  • The referrer ID is not guaranteed to be unique.  This is because the referrer may have created the referral without signing into an Ocean user account (e.g. directly from the Ocean Healthmap), so Ocean may not be able to assign a unique ID.
  • Every ServiceRequest bundle will include a DocumentReference to retrieve a PDF copy of the Ocean eReferral.   If the requestor includes attachments in the eReferral, these will be added to the bundle as distinct DocumentReference resources.   In this case, the PDF eReferral copy will always be the first DocumentResource resource included in the bundle.
  • *** According to the HL7 FHIR eReferral specification, it is not mandatory to specify the content/MIME type of an attachment to the eReferral.   Ocean will provide if it’s known, but receiving systems should not assume it will always be available or that it will be a specific content type (e.g. PDF), since requestors may include other attachments (e.g. images).



Data Mapping

  • Ocean sends the following core patient and provider demographics for every eReferral:




  • ***The following demographics are mandatory in order to submit an eReferral in Ocean and shall be present in the Patient resource:  First Name, Last Name (Surname), Date of Birth (DOB), Gender,  Address (street field), City, and at least one telephone-based contact field (mobile, fax, or business).  All other fields are optional.
  • ***Ocean does not send a 'null value' when field has not been populated.
  • Ocean is only capable of sending(Male, Female, Other) for the gender field and does not support gender identity or sex as a core demographic field.  Service providers may include these in the body of the eReferral form. 
  • Ocean checks if the HN-province field is populated with a standard two-letter provincial alpha code (e.g ON, PE).  If it is, the JHN identifier will have a Naming System like https://fhir.infoway-inforoute.ca/NamingSystem/ca-XX-patient-hcn where XX is the two-letter alpha code and the usage field on the identifier will be set to OFFICIAL.   
  • Users are instructed to enter the name of the identifier system into the province field when they are submitting an identifying number other than a provincial health insurance number.  For instance, they will enter "Military ID" into the HN-province field and the ID number into the health number field.  Ocean will provide the value entered in the HN-province field as a secondary health identifier and will set the JHN identifier usage field with SECONDARY.
  • Ocean does not validate that the submitted identifying number belongs to the identifying system (e.g. it does not perform a checksum on provincial health insurance numbers).
  • The body of the referral form (e.g. Allergies, Medical History, and any questions that the clinical service provider adds to their Ocean referral form) will be sent in the QuestionnaireResponse resource as a key name-value pair.  Ocean does not control or constrain the key names created by the service provider.  Therefore, if you intend to map the responses of specific referral form fields into RMS Target fields, you will need to coordinate with the service provider on the key names.   (This is set in the question’s Caption field, which is described in the General tab of this article.) 
  • The table below illustrates the eReferral lifecycle states that can be communicated by the RMS Target to Ocean and the corresponding Ocean internal eReferral state.  The status is communicated by Ocean in the ServiceRequest resource Status field and is updated by the RMS Target in the Task resource’s Status field . 



Technical Considerations

  • Ocean supports both IPv4 and IPv6
  • Ocean will send the entire ServiceRequest bundle/resources each time there is an update to any of the referral fields.  The change list is provided in the MessageHeader.reason which can serve as ‘hints’ for the RMS Target to assess what has changed.   It is up to the RMS Target to decide which updates require an internal update and/or notification to the service provider.
  • *** Update events are tracked in our audit log and will trigger an 'update' notification.  It is safe to ignore notifications with the MessageHeader.reason  = EVENT_LOGGED.
  • There does not need to be a synchronous response to the transmission for the inbound ServiceRequest message other than a 200 HTTP response to indicate the message was successfully received. The next asynchronous status update change sent to Ocean can provide a more specific status for the referral when it is acted upon by the RMS Target. 
  • If you will be using a single endpoint to receive ServiceRequest bundles for multiple Ocean sites, you can identify who the intended recipient is by examining the ServiceRequest / Performer / PractitionerRole / Identifier, which will contain the Site ID.  
  • The ServiceRequest ID must be populated in the meta->profile section of the MessageHeader.  This is required so that Ocean can identify the incoming messages as conforming to the Ontario HL7 FHIR eReferral Specification v0.10.0 so that they can be processed accordingly. 


  • Because the APIs are RESTful, Ocean does not have the ability to replay a sent message in the event that it is not received (e.g. RMS Target is ‘down’).  It is recommended that RMS Targets have in place a strategy for mitigating API endpoint downtime.  
  • Similarly, when the RMS Target goes ‘live’ with the integration, any pre-existing eReferrals that exist within the Ocean site will not be sent to the RMS Target until they are updated (which will trigger Ocean to send a webhook notification). 
  • Ocean does maintain a log of all message sends which can be used to determine which messages have been missed.   They can be manually ‘forced’ to be resent to the RMS Target by making an update to the referral within the Ocean portal.

Implementation & Testing

  • As a referral is updated in Ocean, it will move between various 'folders' in the eReferral dashboard.  This is one way to see that the status update sent to Ocean has been processed. 
  • The event log for each referral can be accessed by opening the referral record and selecting 'View Event Log' from the top right 'Action' menu.  This can assist in determining if the referral is being updated as intended.
  • When the Ocean APIs detect a call error rate of more than 5% in the first 20 attempts, it will automatically disable the API.  It can be re-enabled by going back into Admin > Integrations, opening the relevant integration setup and then saving it.
  • ***Ocean referral sites may offer patients a self-referral website form along with the the eReferral listing within the Ocean Healthmap.   If this is enabled, these self-referrals will trigger an webhook notification with a ServiceRequest bundle.   They can be distinguished from service provider-initiated referrals because ServiceRequest.requester will reference a Patient resource rather than a PractitionerRole resource.   You should confirm with the sites's business stakeholders whether they want patient self-referrals to be processed in the same way as service provider-initiated referrals (e.g. can they create a new referral in the RMS Target/POS or should they only once they have been 'accepted' within the Ocean Portal).
Have more questions? Submit a request