QUICK START GUIDE

In this guide you will find an explanation of the initial steps of the integration process and a list of all the methods of the API grouped by functionality.

How Eye Reach Patients works?

Eye Reach Patients (from now on ERP) enhances your application with multiple features like Online Appointments, Patient Forms, Secure Messages and Patient Communications.

For all those features to work, ERP needs up to date information from a partner application (your software). The partner application will also receive information from ERP, e. g. appointment confirmations, online appointment requests, etc.

What are the steps of the integration?

  1. The first step is the creation of an account. Each of your customers will need to create an account with ERP. Accounts can only be created through the API, there is no way to create an account using the web interface. You will find more information about this process below in the section Creating an account.
  2. With the account created your application will start the initial synchronization of the information that ERP needs to work. The information needed depends of the features you want to use. More information below in the section API methods by functionality module.
  3. Finally your application needs to periodically send to ERP any changes made in the data. For example: patients modified, new appointments, etc. Your application also needs to receive the data generated in ERP: appointment confirmations or cancellations, online appointment requests, etc.

Please note: The information sent to ERP must follow a specific order. For instance to send appointment information you must send first the information of the related patient. In the section API methods by functionality module below the list of method is presented in the order in which the information must be synchronized.

Once the integration is completed and working properly, your customers will be able to use the ERP web interface to plan how they want to communicate with their patients. To get more information about that process, please visit the ERP documentation pages.

How to use the Eye Reach Patients API?

The API can be called directly making http requests to the URL of the desired method. The base URL for all methods is:

/[method name]

This is a temporary URL available just for development and testing purposes, we will update this document with the final URL in the near future.

You can also use a helper library that can be downloaded from /help. Both the source code and the compiled files of the library are available for download.

To use the helper library from your solution in Visual Studio, simply add a reference to GlobalPortal.Api.Client.dll from your project. Then use the objects in the library to create an account and to synchronize information between your system and ERP.

Creating an account.

The first operation that needs to be executed by your program is the creation of an account. One account must be created for each of your customers using Eye Reach Patients.

When calling to the account creation API you must supply a Partner Key. That value will provided by us and it will identify your software as a partner in the ERP integration.

As part of the account creation process two special users are added to the account. One is called the account owner and the other one is the synchronization user.

Account owner

The account owner is the equivalent to a “super administrator” for the account and can be used to access the web interface of ERP. This user will always have all the privileges granted and it will always have access to all the locations of the account. Your program needs to supply the properties of the account owner (name, username and password, etc.) as parameters of the account creation call.

Synchronization user

You will receive the username and password of the synchronization user as a result of the account creation process. Your program will need to use those credentials from that point on when making calls to the ERP API.

You can store the synchronization user credentials in whatever place is convenient to your application (database, a config file, etc). It is your responsibility to keep those credentials secure.

Finally, once the account creation is completed, you will also receive an account number. That number will uniquely identify each of your accounts in ERP. For more details about the account creation API visit the reference page.

After the account is created.

Your application now can synchronize information with ERP using the API. The information needed depends of the ERP modules that you want to use.

After the initial synchronization is completed, your application will continue using the same API methods to updated information that changed or to retrieve data generated by ERP.

In the next section you will find a list of the methods classified by modules in the application. Some information is used in multiple modules and for that reason the corresponding method will appear in multiple sections.

API methods by functionality module

General

This information is used by all the modules of Eye Reach Patients:

Patient communications

Online appointments

Forms

Hl7CDAs

Patient shared files

Patients will be able to upload files to the portal to be later downloaded by providers. Below you will find the related API methods.

Get a list of files uploaded by patients

Use GET api/patientSharedFiles/search to get a list of files uploaded by patients. The list can be filtered by patient, upload date or any of the properties of the file (name, comments, etc.).

This list does not contain the actual file uploaded by the patient, just information about the file, including URLs to view or get the content of the file. Read the section Get the uploaded file below for more information.

If you plan to store the information in the list for later use, set the filter alreadySent to False. By doing that, you will receive only new records, for files added after the last call you made to get the list.

For the alreadySent filter to work, you need to tell the portal that the information about a file was already received successfully in your end. Call POST api/PatientSharedFilesSent with the ID of the file that you already received. The next time you call GET api/patientSharedFiles/search, you will not get the records previously received.

Get information about a specific file

Use GET api/PatientSharedFiles to receive information about one file. The information about the file returned here is the same returned by the list.

Update the status of a file

Each file has a Status property that can take the values New or Processed. The purpose of this status is to help providers differentiate files that they already processed from new files. This property is not related with the alreadySent filter explained above.

Use POST api/PatientSharedFiles to modify the status of a shared file. Send a PatientSharedFileUpdateStatusModel with the ID of the file and the new status.

Delete a file

Use DELETE api/PatientSharedFiles to delete a file. The delete operation will be permanent. It will remove the information about the file and the file itself. An entry in the audit log will be added to record the operation.

Get the uploaded file

There are two ways to get the uploaded file:

  1. Providers can log into the portal, navigate to the File sharing option and download the desired file from there.

  2. Finally making a call to GET api/PatientSharedFilesBinary, which is the value of the property ApiUrl mentioned above, will return the binary content of the file.

    3. Patient Generated Health Data (PGHD)

    This feature will allow the integrating system to collect health information generated by the patient.

    The first step of the process is to show to the patient the health information currently in the EHR (demographic data, insurance information, medications, etc.). The EHR will need to implement the following methods:

    Also, new fields were added to the patient record to show demographic data to the patient. Please review the new properties in PatientModel and update the process to send patient data from the EHR to the portal.

    During the second step of the process, the patient will be able to provide new information or to request modifications to the current information. Once the patient submits the update request, the EHR will have access to the data by implementing a call to this list: GET api/pghdupdaterequests/search.

    The list can be filtered by patient, date of the operation and whether to get all records or just the new ones (more about that below). The results will be paginated. Each call will return an object (ListModelOfPghdUpdateRequestModel) with information about the records in the current page, total records, etc. and a collection of objects (PghdUpdateRequestModel), one for each patient, with information about the update request. This information will contain other objects, one for each section of the PGHD modules available in the portal.

    To get only new records when calling the list several times, the EHR will need to let the portal know what records were successfully received. To do that, call: PghdUpdateRequestsSent, sending the ID of each of the PGHD records already received.


Secure Messages

The Secure Messages API covers two message flows: incoming (patients sending messages to the practice) and outgoing (the practice sending messages to patients). Each flow has two controllers — one for managing messages and one for acknowledging them as processed by your integrating system.

Incoming secure messages

Use GET api/incomingSecureMessages/search to get a list of messages sent to your practice by patients. The list can be filtered by priority, read status, patient ID, date ranges, and more.

If you plan to store the information for later use, set the filter alreadySent to False. By doing that, you will receive only new messages not yet acknowledged by your system.

For the alreadySent filter to work, you need to tell the portal that a message was already received successfully on your end. Call POST api/IncomingSecureMessagesSent once per message, passing the single InternalID (a Guid) of the message you have processed. The next time you call the search, that message will not be returned.

You can also retrieve the full details of a single message using GET api/IncomingSecureMessages/{id}, mark a message as read or unread using POST api/IncomingSecureMessages/{id}?read={true|false}, or delete a message using DELETE api/IncomingSecureMessages/{id}.

Outgoing secure messages

Use POST api/OutgoingSecureMessages to compose and send a message from the practice to one or more patients. Each message must include a unique ExternalId from your system. If a message with that ExternalId already exists it will be updated, otherwise a new message will be created.

Set the Status field to Draft to save the message without sending it, or to Sent to dispatch it immediately to the listed patients.

If you plan to store outgoing message records for later use, set the filter alreadySent to False when calling GET api/outgoingSecureMessages/search. By doing that, you will receive only new records not yet acknowledged by your system.

For the alreadySent filter to work, call POST api/OutgoingSecureMessagesSent with the InternalID of each outgoing message record you have already received. The next time you call the search, those records will not be returned.


Forms

Search forms

What it does:
Get a list of forms by search criteria.

Endpoint:
GET /api/forms/search

Description:
Returns list of froms

View an Open Form

What it does:
Look up an open form using its internal ID and see its current details.

How it works:
Provide the form’s internal ID, and the system will return the latest available information.

Endpoint:
GET api/OpenForms?internalId={internalId}

Description:
Returns information about an active (open) form.

Close an Open Form

What it does:
Closes an open form and moves it to closed forms.

How it works:
Send a request with the form’s internal ID. The system will mark the form as completed. Once closed, it will no longer appear in open forms.

Endpoint:
POST api/OpenForms

Description:
Marks an open form as completed and moves it to closed forms.

Closed Forms

This section lets you view forms that have already been completed.

What it does:
Look up a closed form by its internal ID and see its final details.

How it works:
Provide the form’s internal ID, and the system will return stored information for that completed form.

Endpoint:
GET api/ClosedForms?internalId={internalId}

Description:
Returns information about a completed (closed) form.