Open eReferral API Implementation Guidance

Ocean's Open APIs enable third-party systems to integrate with Ocean so that providers can process referrals within their preferred system or app.  In addition to the Open API documentation, we have assembled the following implementation guidance to accelerate your integration implementation.

 

eReferral Integration Sequence

The sequence diagram below illustrates the interaction sequence between Ocean and a third-party system after a referral has been created in Ocean.   

 

 

Webhook Validation

• The webhook requires the URL to respond to a challenge in order for it to work properly.   Testing with a webhook that is not ready to provide the challenge token in the response will fail validation.  This is indicated by a yellow exclamation mark symbol beside the URL. 

• The validation check does not require the ocean specific headers (sitenum, sitekey) in the response, although they will not cause any errors if they are included.  For additional information, please see our API Docs

 

Payload Encryption

• The encryption code in the Ocean API documentation is an example that illustrates the correct encryption flow and highlights the encryption library (CryptoJS) we use and recommend when working in Javascript.  But the encryption scheme is just standard AES encryption so you will absolutely be able to encrypt/decrypt this data in other languages. For instance, For Ruby, you can use the OpenSSL module in the standard library to run the AES ciphers to encrypt and decrypt the data.  There are also likely other external AES/cryptography gems you can use if you have a preference.
• ***When retrieving a referral, it is recommended to use the oneTimeKeyEncryptedWithSitePublicKey": field (rather than the oneTimeKeyEncryptedWithTargetPublicKey" field) so that your system can also decrypt referrals that are sent by your clients' Ocean sites (and not just those that are received by it).  See the "API Behaviour" section of this article for more information about receiving a copy of sent referrals. 

 

Data Mapping

• The file at the bottom of this article lists the data elements that are available within the Open API payloads.   
• if the site allows multiple appointment dates for a single referral, the referral listing should have multiple labels configured. By default, Ocean only enables a single label for each listing named “Appointment”.  Each referral listing (Site Admin > Directory Listing > Service Details section) can be configured by the Site Admin to accept add additional labels from the following values: appointment 1 - 5, consultation date, follow-up date, initial visit date, procedure date, surgery date.  

• If an API call is sent with appointment data without a label, then Ocean will assign the first appointment label that has not been used in that referral for that appointment. If a second appointment is sent without a label and there all of the appointment labels have already been assigned for that referral, the API will return an error.   Alternatively, the appointment data can be sent with an appointment label, but it must correspond to one of the labels configured for that site.
• The POST Update a Referral API accepts the following referral status values in the status field:  Accepted, Declined, Confirmed, Canceled, Completed, Printed, Incomplete, Sent. The field is optional and should only be populated by the Third-Party System when the referral status value is different than the previous update sent to Ocean.  Ocean will return an error of "Referral is already in the requested status” if two updates are sent with the same status value.   As such, if the Third-Party System's internal set of referral statuses are more granular than Ocean's, referral updates should contain the relevant updated information without a status value unless it will change the Ocean referral status. 
• The referral is updated to a "Booked" status internally by Ocean once it receives appointment data from the Third-Party System.
• Once a referral is in the "Completed" or "Canceled" referral status, it cannot revert to another referral status via the API.
• Ocean will flag place a referral into the 'Needs Review' folder when a recipient has a new message sent to them (e.g. referral recipient sends a message within the referral to the sender with patient care instructions).   When a message is sent using the 'Add a Message' endpoint (URL below), the TargetSiteNum must be populated with the site number of the provider that should review the message in order for it to be 'flagged' for inclusion in the Needs Review folder.