Building a Custom Portal

All of the API endpoints that are used in Tellescope's portal are publicly documented available for use. These endpoints encompass Enduser (patient) authentication and data read/write. We also offer open-source React components, the same code we use in our own portal, for authenticating, managing state, and leveraging the API. 

You have free reign to design the UI and UX of your portal exactly how you want, but please be mindful of the following constraint:

URL Pathing

The primary constraint in building your portal has to do with URL paths. Messages sent from Tellescope, e.g. a link to book an appointment in the portal, go to specific URLs. You should evaluate the types of messaging sent in your Tellescope configuration and ensure that your portal handles them appropriately. If you don't want to customize a specific page, you can always use an iframe to embed the corresponding page hosted at Tellescope's portal. Passing embedded=true in the URL will remove our navigation elements and fit better within a custom portal.

Source-code Licensing

One of the easiest ways to build your own Portal is to start with Tellescope's source code. Authentication and pathing are built-in, which simplifies your build. You can deeply customize the UI/UX of this portal code to meet your own needs from there. Access to our portal source code currently requires a license, so please reach out to sales if you're interested in exploring this option.

Elements of Your Custom Portal

Authentication

User Authentication (API Key)

When making requests to the API, it's typical to use an API key. This authenticates as your User account, and if your user account is an Admin, this gives you access to full API capabilities. You would include the API key in an authorization header:

Authorization: API_KEY {api_key_here}

Enduser (patient) Authentication

Via Tellescope's API, Endusers (patients) can login by providing a username/password, by accessing a magic link via email/SMS, or by OTP code. 

If you're making an authenticated request with an API key, you can also generate an authToken for an Enduser directly by using /generate-enduser-auth-token. This allows you to use a separate authentication system upstream of Tellescope while still leveraging our Enduser authentication later.

Endusers are authenticated by including a Bearer token in an Authorization Header

Authorization: Bearer {enduser_auth_token_here}

Portal Authentication

For a couple of reasons, it's recommended to use Enduser Authentication for all requests made to Tellescope's API from your custom Portal front-end

1. You do not need to create your own "proxy" API endpoints to handle a request from your patient, load data from the Tellescope API via your backend, and then return it to your front-end.
2. Requests by an Enduser session are automatically restricted to return only their own data. This limits the complexity of API requests (no need to add filtering) and ensures that you don't accidentally share one patient's data with another.

API Basics

Different data types associated with a particular patient often have a field called "enduserId", which stores the Enduser.id value of an Enduser. When a request is made by an authenticated Enduser, only their records are returned. Each model in the API has a consistent URL structure for accessing data via GET requests. Example models used in our portal are listed below, but many more are available for inclusion in your custom portal:

• FormResponse
• File
• Purchase
• EnduserOrder
• CalendarEvent (filtered by attendees.id)
• ChatRoom (filtered by enduserIds)
• ChatMessage (filtered by roomId)

Handling Authenticated Links

As mentioned earlier, you should make sure that your custom portal has the same pathing as our off-the-shelf portal -- particularly for authenticated links which are commonly sent as part of Tellescope messages.

Each authenticated link will include a "token" parameter in the URL. You should first verify if this Enduser authToken is valid. If not, you will need to redirect the Enduser to your login flow. If the token is valid, you should use the /refresh-enduser-session endpoint to generate a new token and expire the old one. This ensures that active tokens do not persist in any browser history and improves the security of your app.