Quick start guide

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:

/[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.

System automatically provisions communication services

As part of the account creation process, the following services are provisioned automatically — no additional API calls are required from your side:

Application settings loaded — The system loads the platform-wide default settings and uses them to pre-configure the new account's secure messaging email templates (subjects and bodies for both patient and practice notifications). The account inherits these defaults automatically — no additional configuration is required from your side.

Twilio subaccount created — A dedicated Twilio subaccount is set up for the new account to handle all SMS and voice communication features (appointment reminders, patient communications, etc.).

Account number generated — For non-MVE customers, a unique account number is generated by the system. This number is returned in the response and is used as part of the URL to access the ERP web interface.

SendGrid subuser created — A dedicated SendGrid subuser is created for the account to handle all outbound email communications (form notifications, appointment confirmations, etc.).

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

Hl7CDAs

Amendment Requests

EHR Clinical Exam

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:

Providers can log into the portal, navigate to the File sharing option and download the desired file from there.
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.

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.

Appointments — How It All Works

The appointment feature in Eye Reach Patients (ERP) is a two-way integration between your Practice Management System (PMS) and the patient portal. Your system pushes appointment data into ERP so that patients can see their appointments and receive reminders. ERP pushes information back to your system when patients take action — requesting a new appointment, requesting a cancellation, or responding to a reminder.

Important ordering rule: Before pushing an appointment (step 2), ERP must already have records for the related Account, Location, Doctor, Patient, and Appointment Status. If any of those are missing, the appointment POST will fail validation.

Step	Who does it	What happens	API call
1	Your system (once)	Push your appointment status codes to ERP so ERP understands the statuses you send with appointments (e.g. Scheduled, Cancelled).	POST api/AppointmentStatuses
2	Your system (ongoing)	Push appointments from your PMS to ERP. ERP uses this data to show the appointment to the patient, send reminders, and track changes.	POST api/Appointments
3a	Patient	Patient logs into the portal, picks a date and time, and submits a new appointment request.	Portal action — no API call required
3b	Your system	Read new online appointment requests. Each request includes the patient's details, preferred doctor, location, date/time, and insurance information.	GET api/appointmentrequests/search
3c	Your system	Book (or decline) the appointment in your PMS, then tell ERP the outcome. ERP emails the patient with the result.	POST api/AppointmentRequests
3d	Your system	Acknowledge that your system has processed the request so it no longer appears as unread.	POST api/AppointmentRequestsSent
4a	Patient	Patient clicks "Cancel" on an existing appointment in the portal and submits a cancellation request.	Portal action — no API call required
4b	Your system	Read pending cancellation requests.	GET api/appointmentcancelrequests/search
4c	Your system	Cancel (or keep) the appointment in your PMS, then tell ERP the outcome. ERP emails the patient.	POST api/AppointmentCancelRequests
4d	Your system	Acknowledge that your system has processed the cancellation request.	POST api/AppointmentCancelRequestsSent
5a	ERP (automated)	ERP sends an appointment reminder to the patient via SMS, email, or automated call.	ERP automated action
5b	Patient	Patient replies CANCEL, CONFIRM, or a similar keyword to the reminder message.	Patient action — no API call required
5c	Your system	Read appointment status changes driven by patient communication replies.	GET api/communicationupdatesappointments/search
5d	Your system	Update the appointment status in your PMS, then acknowledge receipt.	POST api/AppointmentUpdatesSent

Set Appointment Allowed Time In Advance

What it does:
Sets the time span (in days) beyond which future appointments cannot be scheduled for the account.

How it works:
Send the number of days in the request body. The system updates the account settings and returns the confirmed value.

Endpoint:
POST api/AppointmentAllowedTimeInAdvance

Description:
Updates and returns the allowed time in advance value as an AppointmentAllowedTimeInAdvanceModel.

Appointment Request Reasons

Search Appointment Request Reasons

What it does:
Returns a paginated list of appointment request reasons for the authenticated account.

How it works:
Use the changed filter to retrieve only reasons modified since your last sync. Use isDeleted to filter deleted reasons. Results are paginated.

Endpoint:
GET api/appointmentrequestreasons/search

Description:
Returns a paginated list of AppointmentRequestReasonModel.

Update an Appointment Request Reason

What it does:
Updates the slot duration of an existing appointment request reason.

How it works:
Send the InternalId of the reason and the new SlotDuration value. The InternalId must be a non-empty Guid. Only SlotDuration can be updated via the API.

Endpoint:
POST api/AppointmentRequestReasons

Description:
Updates and returns the appointment request reason as an AppointmentRequestReasonModel.

Appointment Request Reasons Sent

Mark an Appointment Request Reason as Sent

What it does:
Flags an appointment request reason as successfully received and processed by the integrating system.

How it works:
Send the InternalID and LastChanged timestamp of the reason you have processed. The system verifies the concurrency timestamp and marks the reason as sent. If the reason is logically deleted and has no linked appointment requests it will be permanently deleted from the database.

Endpoint:
POST api/AppointmentRequestReasonsSent

Description:
Returns an AppointmentRequestReasonReceivedModel with a Success flag and a ResultMessage. Always check Success even on a 200 response.

Appointment Requests Limited

Search Appointment Requests Limited

What it does:
Returns a paginated list of limited appointment requests grouped by patient, including patient data for new portal patients.

How it works:
Use alreadySent=false to retrieve only new unprocessed requests. Results are grouped by patient. Each entry includes an IsPortalPatient flag — if true, the patient registered on the portal and a full PortalPatient profile is included; if false, use the PatientExternalId to look up the patient in your system.

Endpoint:
GET api/appointmentrequestslimited/search

Description:
Returns a paginated list of PatientAppointmentRequestLimitedModel, each containing a list of AppointmentRequestLimitedModel.

Appointment Types

Search Appointment Types

What it does:
Returns a paginated list of appointment types for the authenticated account.

Endpoint:
GET api/appointmenttypes/search

Description:
Returns a paginated list of AppointmentTypeModel.

Get an Appointment Type

What it does:
Retrieves a single appointment type by its external ID.

Endpoint:
GET api/AppointmentTypes?externalId={externalId}

Description:
Returns an AppointmentTypeModel.

Create or Update an Appointment Type

What it does:
Creates a new appointment type or updates an existing one.

How it works:
Send an AppointmentTypeModel with the ExternalId from your system. If a record with that ExternalId already exists it will be updated; otherwise a new record will be created.

Endpoint:
POST api/AppointmentTypes

Description:
Creates or updates and returns an AppointmentTypeModel.

Delete an Appointment Type

What it does:
Permanently deletes an appointment type from Eye Reach Patients by its external ID.

Endpoint:
DELETE api/AppointmentTypes?externalId={externalId}

Description:
Deletes the appointment type identified by the supplied externalId.

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.

Amendment Requests

Amendment Requests allow patients to submit requests for corrections or additions to their health record. The practice reviews each request via the ERP portal or API and responds with an approval or denial.

Dependency: Secure Recipient

The notification workflow for Amendment Requests requires a Secure Recipient to be configured in both the ERP account and the EHR/PM partner system. When a patient submits an amendment request, the system checks for all of the following before sending any notifications:

A Secure Recipient linked to the CDA record associated with the request (SecureRecipientId is populated from the CDA).
Secure messaging is active for the account.
The amendment request notification setting is enabled.

When all conditions are met, the system automatically sends a secure message to the practice when a request is submitted, and a secure message to the patient when the status changes (Approved or Denied). If a Secure Recipient is not configured, no notifications are sent — amendment requests are still created and remain retrievable via the API.

Use the SecureRecipients endpoints to configure recipients in ERP. Ensure the recipient is also configured in your EHR/PM system.

Check for pending amendment requests

Before fetching the full list, you can call GET api/PortalNotifications with amendmentRequests=true to get a count of unprocessed requests without retrieving the full list. The response (PortalNotificationsModel) includes an AmendmentRequests field with the pending count.

Search amendment requests

Use GET api/amendmentrequests/search to get a paginated list of amendment requests. Set alreadySent=false to receive only records not yet acknowledged by your system. Results are paginated using the page and itemsPerPage parameters.

Each record (AmendmentRequestModel) includes the patient external ID, the reported missing or incorrect information, the current Status (Pending, Approved, or Denied), and any DoctorComments.

Acknowledge amendment requests as received

For the alreadySent filter to work, tell the portal that a record was received on your end. Call POST api/AmendmentRequestsSent once per record, sending a MarkAsReceivedModel with the InternalID (a Guid) of the amendment request. The next search call with alreadySent=false will exclude acknowledged records. Always check the Success flag in the response even on a 200 status.

Update amendment request status

Use POST api/AmendmentRequests to approve or deny a request. Send an AmendmentRequestPostModel with the AmendmentRequestId, the new Status (Pending, Approved, or Denied), and optional DoctorComments. When the status changes and a Secure Recipient is configured, the system automatically sends a secure message to the patient with the decision.

Medication Refill Requests via Secure Messages

What it does:
Medication refill requests are a specialized workflow within the Secure Messages system. When a patient requests a medication refill through the portal, the system automatically creates and sends a secure message to the patient's doctor (practice). When the doctor approves or denies the request, another message is automatically sent to the patient.

How it works:
This two-way secure messaging workflow is automatically triggered based on refill request status changes. The workflow requires:

Account-level secure messaging enabled (SecureMessagesActive = true)
Doctor must have an assigned SecureRecipientId
Account configured flags: SendRefillRequestSecureMessageToPractice and SendRefillRequestSecureMessageToPatient
Email templates configured: RefillRequestSecureMessageToPracticeSubject/Body and RefillRequestSecureMessageToPatientSubject/Body

Workflow diagram:

Step	Who does it	What happens	API call
1a	Patient	Patient logs into portal and requests medication refill (e.g., "refill my Lisinopril").	Portal action — no API call required
1b	ERP (automated)	System creates refill request and automatically sends secure message to doctor (practice). Message uses account's configured template and is tied to the refill request for tracking.	Automatic — triggered by patient action
2a	Your system / Doctor	Retrieve new medication refill requests or monitor via PortalNotifications endpoint.	GET api/medicationrefillrequests/search
2b	Your system	Get details of a specific refill request.	GET api/medicationrefillrequests/{id}
3a	Doctor / Your system	Doctor approves or denies the refill request (via ERP web interface or your system).	POST api/medicationrefillrequests
3b	ERP (automated)	System automatically sends secure message to patient with approval status and any doctor comments. Message uses account's configured template.	Automatic — triggered by status update
4	Your system	Acknowledge that your system has processed the refill request so it no longer appears as unread in the system.	POST api/MedicationRefillRequestsSent

Monitoring pending refills:
Use GET api/portalnotifications?medicationRefillRequests=true to get a count of pending medication refill requests that have not yet been processed by your system.

Message template configuration:
The subject and body of both messages (to practice and to patient) are configurable at the account level in the Accounts table. These settings are automatically configured during account creation from platform defaults, but can be customized by account administrators through the ERP web interface.

API Endpoint References:

GET api/medicationrefillrequests/search — Search and filter refill requests by patient, doctor, medication, status, dates, and more
GET api/medicationrefillrequests/{id} — Get specific refill request details
POST api/medicationrefillrequests — Approve/deny refill and automatically send message to patient
POST api/medicationrefillrequestssent — Acknowledge processing of refill request
DELETE api/medicationrefillrequests/{id} — Delete refill request

Forms

Search forms

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

Endpoint:
GET /api/forms/search

Description:
Returns list of forms

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.

EHR Clinical Exam

This section covers the API endpoints for pushing clinical exam data from the EHR or practice management system into Eye Reach Patients so patients can view their prescription records on the portal. Additional clinical exam endpoints will be added in future releases.

Glasses Prescriptions

Use these endpoints to create, retrieve, activate/deactivate, and delete glasses prescription records for patients. An optional PDF document can be attached to each prescription. Prescriptions are identified in the ERP system by the ExternalId supplied by the integrating system.

Create a glasses prescription

What it does:
Creates a new glasses prescription record for a patient. If a prescription with the supplied ExternalId already exists for the account, the request will be rejected — use PATCH api/GlassesPrescriptions to change the active status of an existing record.

How it works:
Send a GlassesPrescriptionModel with the patient's PatientExternalId and a unique ExternalId for this prescription. At least one of the following eye fields must be provided: LeftEyePrescriptionDetails, RightEyePrescriptionDetails, LeftEyeExpirationDate, RightEyeExpirationDate, LeftEyeComments, or RightEyeComments. To attach a PDF document, include both FileName (must end in .pdf) and FileContent (binary content of the file). The PortalCreated field is set by the system and should not be included in the request.

Endpoint:
POST api/GlassesPrescriptions

Description:
Returns the created GlassesPrescriptionModel with a 201 Created response. If the ExternalId already exists or required fields are missing, returns a 400 Bad Request with a validation message.

Get a glasses prescription

What it does:
Retrieves the full details of a single glasses prescription by its external ID, including any attached PDF document.

Endpoint:
GET api/GlassesPrescriptions?externalId={externalId}

Description:
Returns a GlassesPrescriptionModel. When a PDF was attached at creation, the FileName and FileContent fields are populated in the response.

Activate or deactivate a glasses prescription

What it does:
Sets the active status of an existing glasses prescription. Inactive prescriptions are hidden from the patient portal view.

How it works:
Send a GlassesPrescriptionPatchModel with the ExternalId and the desired Active value (true or false).

Endpoint:
PATCH api/GlassesPrescriptions

Description:
Returns the GlassesPrescriptionPatchModel on success. Returns 404 if the ExternalId is not found.

Delete a glasses prescription

What it does:
Permanently removes a glasses prescription from Eye Reach Patients by its external ID.

Endpoint:
DELETE api/GlassesPrescriptions?externalId={externalId}

Description:
Deletes the glasses prescription and its associated PDF document. This operation is permanent.

Contact Lens Prescriptions

Use these endpoints to create, retrieve, activate/deactivate, and delete contact lens prescription records for patients. An optional PDF document can be attached to each prescription. Prescriptions are identified in the ERP system by the ExternalId supplied by the integrating system.

Create a contact lens prescription

What it does:
Creates a new contact lens prescription record for a patient. If a prescription with the supplied ExternalId already exists for the account, the request will be rejected — use PATCH api/ContactLensPrescriptions to change the active status of an existing record.

How it works:
Send a ContactLensPrescriptionModel with the patient's PatientExternalId and a unique ExternalId for this prescription. Each eye follows an all-or-nothing rule: for any eye you include data for, all three fields must be provided — LensName, Prescription, and ExpirationDate. At least one eye must have complete data. To attach a PDF document, include both FileName (must end in .pdf) and FileContent (binary content of the file). The PortalCreated field is set by the system.

Endpoint:
POST api/ContactLensPrescriptions

Description:
Returns the created ContactLensPrescriptionModel. If the ExternalId already exists or required fields are missing, returns a 400 Bad Request with a validation message.

Get a contact lens prescription

What it does:
Retrieves the full details of a single contact lens prescription by its external ID, including any attached PDF document.

Endpoint:
GET api/ContactLensPrescriptions?externalId={externalId}

Description:
Returns a ContactLensPrescriptionModel. When a PDF was attached at creation, the FileName and FileContent fields are populated in the response.

Activate or deactivate a contact lens prescription

What it does:
Sets the active status of an existing contact lens prescription. Inactive prescriptions are hidden from the patient portal view.

How it works:
Send a ContactLensPrescriptionPatchModel with the ExternalId and the desired Active value (true or false).

Endpoint:
PATCH api/ContactLensPrescriptions

Description:
Returns the ContactLensPrescriptionPatchModel on success. Returns 404 if the ExternalId is not found.

Delete a contact lens prescription

What it does:
Permanently removes a contact lens prescription from Eye Reach Patients by its external ID.

Endpoint:
DELETE api/ContactLensPrescriptions?externalId={externalId}

Description:
Deletes the contact lens prescription and its associated PDF document. This operation is permanent.

Single Sign-On (SSO)

ERP's SSO implementation follows a token relay / validation pattern: a client obtains a Bearer token from an API, passes that token to the Web application via the Authorization header, and the Web application calls back to the appropriate API with the token to retrieve enriched identity data before establishing a session. Three distinct flows are supported depending on the context.

Internal (Trust-Based) SSO

What it does:
Creates an authenticated ERP session for a known user without validating credentials. Used in federation or trust scenarios where the calling system has already authenticated the user.

How it works:
The calling system supplies the AccountId, AccountNumber, AccountName, UserId, and an array of permissions. ERP builds a full ApplicationIdentity from these values — no database credential lookup is performed. The resulting identity carries the supplied permissions as claims and is treated as fully authenticated within the session.

Key constraint:
Because no credential validation occurs, this flow must only be used in trusted, server-to-server contexts. The calling system is fully responsible for authenticating the user before invoking this flow.

Library entry point:
ApplicationPrincipal.SingleSignOn(accountId, accountNumber, accountName, userId, permissions)

Returns AuthenticationResult.Successful when the identity is established.

This pattern is used internally by two flows: payments and patient file-sharing. Both follow the same token relay approach — a Bearer token is obtained from the Mobile API, passed to the Web application, and the Web application calls back to the appropriate API to exchange the token for identity data.

How Tokens Are Created

The Mobile API issues OAuth 2.0 Bearer tokens valid for one day.
Endpoint: POST /token
Credentials format: username@accountNumber:password
Handler: SimpleAuthorizationServerProvider.cs — authenticates via ApplicationPrincipal.MobilePatientLogin() and returns a signed Bearer token.

Payment Flow

Used when a mobile client initiates a payment session in the Web application.

Mobile client calls POST /token on the Mobile API and receives a Bearer token.
Client calls PaymentsController.MobileNew() on the Web app, passing Authorization: Bearer {token}.
The Web app calls GET /singlesignon on the Mobile API (using the same token). The Mobile API returns PatientId, Username, PortalPatient, and LoginFromKiosk.
ApplicationPrincipal.LoadPatient() is called to establish the patient session and set an HttpOnly secure cookie for the remainder of the payment session.

Key file: GlobalPortal.Web\Areas\Patients\Controllers\PaymentsController.cs
Configured via: PatientPaymentMobileUrl in ApplicationSettings.cs

Patient File-Sharing Flow

Used when an external user follows a tokenized link to download a patient-shared file.

External user arrives at PatientSharedFilesController.ExternalDownload(account, id) with Authorization: Bearer {token} in the request.
The Web app calls POST /singlesignon on the Main API, passing the account number and token. The Main API returns AccountId, AccountNumber, AccountName, and UserId.
UsersMembershipProvider.ValidateSingleSignOnUser() uses the SSO response to grant the scoped permission PatientSharedFile.CanGet — no full login is performed.
The file is downloaded.

Key file: GlobalPortal.Web\Controllers\PatientSharedFilesController.cs
Configured via: SingleSignOnUrl in ApplicationSettings.cs

Verify User Username

What it does:
Checks whether a username is already taken within the current account.

How it works:
Pass the username you want to check as a query string parameter. The system queries the Users table scoped to the current account and returns true if the username is already in use, or false if it is available.

Key constraint:
The uniqueness check is scoped to the current account — the same username can exist across different accounts.

Endpoint:
GET api/VerifyUserUsername?username={value}

Description:
Returns true if the username already exists in the account, false if it is available.