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?
- 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.
- 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.
- 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:
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 http://api.mveportal.com. 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.
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.
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
This information is used by all the modules of Eye Reach Patients:
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
False. By doing that, you will receive only new records, for files added after the last call you made to get the list.
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
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.
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 three ways to get the uploaded file:
Providers can log into the portal, navigate to the File sharing option and download the desired file from there.
Each record returned by the list GET api/patientSharedFiles/search will contain two properties:
ApiUrl. You can navigate to the value in
DownloadUrlto download the file. Calls to the
DownloadUrlmust bring an
Authorizationheader with the word "Bearer" followed by a space and a valid token from the ERP API.
You can download the source code of a sample Windows application, made in C#, to test the navigation to a
DownloadUrlusing an authentication token. Follow these steps to use it:
Download, build and run the application.
Use Postman to make a call to the
tokenendpoint of the API and get a valid authentication token.
In the sample application, paste a
DownloadUrlof a file and the token. Click the button Go. The sample application will request to save a copy of the file.
Finally making a call to GET api/PatientSharedFilesBinary, which is the value of the property
ApiUrlmentioned above, will return the binary content of the file.
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.