TytoCare API

Date issued:
05-Dec-20
SUBJECT: TytoCare API
Doc. No.: Revision: 5.0 Page 1 of 73
TytoCare API
Change History:
Rev. Change Description Date

46 Remove external properties 5-Dec-20
45 Add account identifiers to view patient API 29-Dec-20
44 Add a util API for QR generation 29-Oct-20
43 Add address fields in account creation 19-Oct-20
42 Add an option specify a patient identifier in account creation 7-Oct-20
41 Add device Mac Address and Device serial number to accounts, clinicians and stations 22-Sep-20
40 Deeplink API is supported 22-Sep-20
39 10.2.2.1 Notes update 11-Jul-20
38 10.2.2.1 7-Jul-20
37 Support updating clinician’s location 25-Mar-20
36 Add an option to filter offline visits that were not completed yet 21-Mar-20
35 Add an option to associate a non-account patient to an account 10-Mar-20
34 Add an option to disconnect a patient from an account 10-Mar-20
33 Deeplink section – mark as not applicable 9 -Mar-20
32 Add a patient review url 21-Jan-20
31 Add a device indication for active visits and a static link to the visit 21-Jan-20
30 Epic encryption/decryption tool 21-Jan-20
29 Create a review session for accounts 20-Jan-20
28 Added indication for device online status for accounts, stations, and clinicians 20-Jan-20
27 Convert patient to account 11-Sep-19
26 QR generation for non-English SSID 26-Aug-19
25 Added a clarification regarding session storage access when hosting tyto in an iframe 15-Aug-19
24 Added a new device pairing status to accounts and stations 27-Mar-19
23 Added a new method for fetching integration terms of use document 24-Mar-19
22 Add iframe spec 21-Jan-19
21 Added deeplinks support – both as a standalone call, and as part of visit creation 15-Dec-18
Page 1 of 73
Tyto Care Ltd. Proprietary and Confidential
Date issued:
05-Dec-20
20 Add API for utils/documentation 1-Nov-18

19 Added location identifier to major entities
8-Oct-18
Added phone mac address to API that generate sessions (for increased security)
18 Added TOTP option for better server-to-server security 17-Aug-18
17 Make stationRemoteAddress not mandatory and add a new flag on device status upon visit
14-Aug-18
creation
16 Fix wrong QR format 30-Jul-18
14 Add new API to add results to an active visit 3-Apr-18
13 New set of APIs for station management, new APIs for device pairing requests, along with
1-Apr-18
updated QR format for initial pairing
12 Add isPaired indicator for account and clinician (acknowledging the user has paired at least
20-Mar-18
one device)
11 Add reviewer identifier to online visit 15-Mar-18
10 Added external properties collection 9-Oct-17
9 Added support for Notification Messages 2-Oct-17
8 Create deeplink for SSO in mobile integration 2-Oct-17
7 Support Basic authentication 2-Oct-17
6 Added Registration codes API 16-Aug-17
5 Changed length of identifiers (to enable dashes within GUIDs)
9-Aug-17
Added information regarding patient and clinician being online in view visit details
4 Changed error message on visit status update (Complete visit / Cancel visit / start visit)
16-Jul-17
Enable creating visits without a clinician. In this scenario clinicians can be assigned to visits as
long as the visit didn’t start.
Changing a visit status to active requires either providing a clinician at the same call, or having
an assigned clinician before (at creation).
3 Sections changed are:
12-Jul-17
Create visit
Update visit
Complete visit / Cancel visit / start visit
An additional change has been with the QR code that needs to be generated. See QR Format
2 Request assisting clinician for visits in which accounts is not provided 1-Jun-17
Date format didn’t include seconds
New api to get the latest user manuals/tutorials
Remove group identifier (not needed)
1 25-May-17
Show first name and last name on the device
Show visit id/patient name on the web view
Page 2 of 73
Date issued:
05-Dec-20
TABLE OF CONTENTS
1. INTRODUCTION ...................................................................................................................................... 5
2. PURPOSE ................................................................................................................................................ 5
3. DEFINITIONS & ABBREVIATION .............................................................................................................. 5
4. APPLICABLE DOCUMENTS ....................................................................................................................... 5
5. INTEGRATION FLOWS ............................................................................................................................. 6
5.1 TYTO EXAM-AND-FORWARD INTEGRATION WITH TELEHEALTH SYSTEM..................................................................... 6
5.2 TYTO ONLINE EXAMINATION INTEGRATION WITH TELEHEALTH SYSTEM .................................................................... 6
5.3 VISIT OUTCOMES INTEGRATION WITH EHR SYSTEM .............................................................................................. 6
6. ENTITIES MAPPING ................................................................................................................................. 7
6.1 GENERAL ..................................................................................................................................................... 7
6.2 TYTOCARE ENTITIES ....................................................................................................................................... 7
6.3 MAPPING .................................................................................................................................................... 7
6.4 MANAGEMENT ............................................................................................................................................. 8
6.5 MANUAL DATA ENTRY .................................................................................................................................... 8
7. INTEGRATION POINTS ............................................................................................................................ 8
7.1 CLINICIAN .................................................................................................................................................... 8
7.1.1 General ........................................................................................................................................... 8
7.1.1 Online integration flow ................................................................................................................... 9
7.1.2 Offline review .................................................................................................................................. 9
7.1.3 Online integration vs Offline review ............................................................................................. 10
7.1.1 TytoCare clinician application dashboard ..................................................................................... 10
7.2 POINT OF CARE (POC) ................................................................................................................................. 11
7.2.1 General ......................................................................................................................................... 11
7.2.1 Internet access .............................................................................................................................. 11
7.2.2 Joining a visit................................................................................................................................. 11
7.3 SERVER ..................................................................................................................................................... 12
7.3.1 General ......................................................................................................................................... 12
7.3.2 API Concept ................................................................................................................................... 13
7.3.3 Security considerations ................................................................................................................. 14
7.3.4 Deployment ................................................................................................................................... 15
7.3.5 Notification messages ................................................................................................................... 16
8. WEB INTERFACE – DETAILS ................................................................................................................... 16
8.1 Web View ........................................................................................................................................... 16
9. POC INTERFACE – DETAILS .................................................................................................................... 17
9.1 Internet access ................................................................................................................................... 17
9.2 QR Format – updated version ............................................................................................................ 17
10. SERVER INTERFACE - DETAILS ............................................................................................................... 19
10.1 Accounts........................................................................................................................................ 19
10.1.1 Overview .................................................................................................................................. 19
Page 3 of 73
Date issued:
05-Dec-20
10.1.2 API List ...................................................................................................................................... 19

10.2 PATIENTS .............................................................................................................................................. 32
10.2.1 Overview .................................................................................................................................. 32
10.2.2 API List ...................................................................................................................................... 32
10.3 CLINICIANS ............................................................................................................................................ 37
10.3.1 Overview .................................................................................................................................. 37
10.3.2 API List ...................................................................................................................................... 37
10.4 STATIONS .............................................................................................................................................. 42
10.4.1 Overview .................................................................................................................................. 42
10.4.2 API List ...................................................................................................................................... 42
10.5 VISITS................................................................................................................................................... 48
10.5.1 Overview .................................................................................................................................. 48
10.5.2 API List ...................................................................................................................................... 48
10.6 USER SETTINGS ...................................................................................................................................... 60
10.6.1 Overview .................................................................................................................................. 60
10.6.2 API List ...................................................................................................................................... 60
10.7 DEEPLINKS ............................................................................................................................................ 63
10.7.1 Overview .................................................................................................................................. 63
10.7.2 API List ...................................................................................................................................... 63
10.8 REGISTRATION CODES .............................................................................................................................. 65
10.8.1 Overview .................................................................................................................................. 65
10.8.2 API List ...................................................................................................................................... 65
10.9 UTILS ................................................................................................................................................... 65
10.9.1 Overview .................................................................................................................................. 65
10.9.2 API List ...................................................................................................................................... 65
11. OUTGOING MESSAGES ......................................................................................................................... 70
11.1 OVERVIEW ............................................................................................................................................ 70
11.2 SECURITY CONSIDERATION ........................................................................................................................ 70
11.3 GENERAL BEHAVIOR ................................................................................................................................ 71
11.4 ENDPOINTS DESCRIPTION ......................................................................................................................... 71
11.4.1 Visit details ............................................................................................................................... 71
11.4.2 Sample outbound message (only fields containing values are included) ................................. 72
Page 4 of 73
Date issued:
05-Dec-20
1. INTRODUCTION
TytoCare solution can be integrated with EHR & Telehealth systems in a few ways, to support
various flows and business cases.
Integration points include the Tyto device (at the point-of-care), The clinician web application
and server.
For the server integration, which is required for all type of integrations, TytoCare offers its
customers a set of APIs to enable, automate and improve inter-system connectivity. A major
part of this integration is done via server-to-server communication, via a restful API. The
document details the server exposed API.
The device and web application integration is minimal to reduce dependencies and easily
maintain compatibility between versions and products.
2. PURPOSE
The document explains both the high-level concepts for the integration and provides the
details required to design, code and test the integration.
3. DEFINITIONS & ABBREVIATION

Visit – an encounter in which a clinician reviews patient’s finding.
Account/Consumer – A user that owns a device that can initiate visits with clinicians
Patient – either a family member of the account, or a non-user that participates in visits
Professional user – a user that collects findings from multiple patients
Clinician – a user that reviews patient findings
Exam – a session in which medical data is collected from a patient using the Tyto Device
Records/findings – artifacts (video/audio/images/metrics) provided by the Tyto device
EHR System – Manages patients’ demographics and medical history
Telehealth System – Manages remote visits between a clinician and a patient
Tyto’s Partner – A vendor providing access to Tyto device and findings
Admin Portal – A web application used to control and manage users, patients etc.
4. APPLICABLE DOCUMENTS
{Reference documents including internal documentation, standards, and guidance}
Page 5 of 73
Date issued:
05-Dec-20
5. INTEGRATION FLOWS
5.1 Tyto Exam-and-forward integration with Telehealth System
In this flow, Tyto users perform full examination using their Tyto device and the mobile
application. The user can decide to send the examination to the Tyto’s Partner Telehealth
system.
The integration contains the following capabilities:
1. Add the Tyto’s Partner to the provider list in the exam and forward flow in the Tyto
mobile application
2. Display a link to the Tyto’s Partner mobile application
3. Get the account consent to send the examination to the Tyto’ s Partner
4. Enable mapping between Tyto users and Tyto’s partner users
5. Review the exam by a clinician - implicitly creating an offline visit - and update the
diagnosis & procedures of that visit
5.2 Tyto Online Examination integration with Telehealth System

In online integration, the clinician remotely examines the patient – using the Telehealth
system which includes a video conference capability. The integration enables showing the
real-time stream and results captured by the device on the patient side – to a web application
in the remote clinician side.
Within this flow, the Telehealth system is responsible to:
• Create the visit
• Assign a clinician to the visit
• Enable Tyto device & Tyto web application to join that visit
• Complete the visit
• Update the diagnosis & procedures of the visit
After the visit is completed, its details are available for further integration.
5.3 Visit outcomes integration with EHR system

Once an offline visit was sent to a clinician, or upon an online visit completion, the EHR system
can retrieve and display the visit details.
The EHR system will be able to:
• Display a list of such examinations in the patient’s record
• Display the details of the findings (captured media and results) via a web application
Page 6 of 73
Date issued:
05-Dec-20
6. ENTITIES MAPPING
6.1 General
The integration flows mentioned above mainly relate to the TytoCare findings captured either
during an online visit by a clinician or while working offline by the consumer or by a
professional user.
To enable those integrations, a mapping of the main entities in the TytoCare system and the
Tyto’s partner system is required. The main entities for mapping are accounts, patients,
clinicians, exams and visits.
6.2 TytoCare Entities
Exam Findings
Patient Visit
Account Clinician
Comments:
• An exam can contain multiple findings
• A visit contains at least one exam
• A visit can refer to a single clinician. Clinicians can refer to multiple visits.
• Patients can exist with or without an account (user)
6.3 Mapping
Entities within TytoCare solution that can be controlled by an EHR or Telehealth systems
include a unique identifier field. This field enables the mapping of the TytoCare entity to the
external system in the entire entity lifecycle.
Entities that are created by TytoCare expose an alternative identifier (commonly named Tyto
Identifier).
Page 7 of 73
Date issued:
05-Dec-20
6.4 Management
Management of the main entities can be done via the admin portal (clinicians, patients and
accounts). The usage of mapping enables automation of this management via the server API.
The common administrative operations include:
• Account management (e.g. add, update, disable, approve)
• Patient management (e.g. add, update, link, delete, approve)
• Clinician management (e.g. add, update, disable)
6.5 Manual data entry

The mapping process supports an additional mechanism to enable accounts to manually enter
their, and their family members’ identifiers (assuming they know it) via Tyto mobile
application. The entered identifiers cannot be used for integration unless approved by the
Tyto’s partner system. Those accounts will be able to perform offline and online visits within
the TytoCare system (without being exposed via API), until the approval process takes place.
7. INTEGRATION POINTS
7.1 Clinician
7.1.1 General
The clinician web application can be launched from an EHR or telehealth systems for an online
visit or for review of a completed visit.
When operating in a standalone mode, running the web application requires an
authentication process, that generates a session token sent over as an http header in each
server request initiated by the browser.
When operating in an integrated mode, TytoCare web application is launched without explicit
authentication (single sign-on). The process is as follows:
• The external system client application sends a request to the external system server
application with a visit identifier
• The external system server application sends a request to TytoCare server with the
clinician mapping and visit identifier
• TytoCare server generates a session for the clinician and returns a URL containing the
session token and the Tyto visit id.
• The external system server application returns the URL to its client
• The external system client application launches the URL in a new window (or an
IFrame)
• The TytoCare client application communicates directly with its server
Page 8 of 73
Date issued:
05-Dec-20
While the clinician is working with the TytoCare web application, the session is maintained.
After a predefined time of inactivity has elapsed, the session expires.
7.1.1 Online integration flow
Server Side Clinician
TytoCare TeleHealth TytoCare Telehealth

Server Server Web Client Web Application
Join Visit
Create/Join Visit Conference
(Visit details, Clinician details)
Clinician URL (session token, Tyto
Visit id)
Launch (session token, Tyto

Visit id)
Join Visit (session token, Tyto Visit id)
7.1.2 Offline review
Page 9 of 73
Date issued:
05-Dec-20
Server Side Clinician
TytoCare TeleHealth TytoCare Telehealth

Server Server Web Client Web Application
Get Tyto Visit (visit id, clinician

details)
Tyto Visit/Exam URL (Tyto visit id,
session token)
Launch (session token, Tyto

Visit id)
Get Tyto Visit (session token, Tyto Visit id)
Tyto Visit (Clinician and patients details, Visit meta data)
7.1.3 Online integration vs Offline review

The process described above is the same for both online integration and offline review. The
differences are:
• The online visit web application enables clinician to control the visit flow (decide on
checkup, display real-time stream sent by the Tyto Device, capture media, etc.). The
offline review application enables only viewing of captured media and results.
• An online visit can run only in Chrome browser, due to the WebRTC support. An Offline
review cannot run on Internet Explorer since it does not support WAV files
• In an online flow, the control over the visit initiation and completion is of the Tyto
partner (via server integration).
7.1.1 TytoCare clinician application dashboard

The TytoCare clinician dashboard enables its users to review offline exams and attend online
visits in a standalone application.
The online visit sub-module includes both the video conference between the patient and the
clinician along with Tyto device communication (remote control, state, and media stream).
This application can be launched by the clinician using the single-sign-on mechanism.
Page 10 of 73
Date issued:
05-Dec-20
7.2 Point of care (POC)
7.2.1 General
POC integration is required only for online visits flow.
In the point of care, the user – whether it’s a consumer or a professional user, will use a
telehealth client application running to initiate or attend an online visit. The user will not need
to install the TytoCare mobile application and will not need to re-enter his credentials to join
a Tyto visit.
The integration at the POC is performed by QR scanning (there is no network-based
communication between the telehealth mobile application and the Tyto device).
7.2.1 Internet access

The Tyto device uses Wi-Fi to get an internet connection and communicate with the Tyto
Server. The device reads the Wi-Fi definitions in the following process:
• The user is asked to connect the Tyto device within the telehealth client application
• The user enters the network SSID and password in the telehealth client application
• (optionally) the telehealth client application registers the user on the TytoCare Server
and receives pairing additional data.
• The telehealth application generates a QR code containing the above details
• The user scans the QR code
The SSID and password are stored hashed on the device, so this process should take place
only once (per network).
7.2.2 Joining a visit

Online visits are conducted in the telehealth system. Once the Tyto’s device is used to “join”
the visit, the following procedure takes place on the POC:
• The telehealth client application initiates a request to its server with the visit identifier
• The telehealth server generates a request to TytoCare server with the user identifier
and visit identifier
• TytoCare server authenticates on behalf of the user, creates a session (or uses an open
one) and returns a URL that includes Tyto web server, the session token and Tyto visit
id.
• If the Tyto device was last associated to the user/station performing the visit in the
POC the device will enter the visit automatically. This behavior is subject to security
considerations (e.g. Checking POC IP address)
• If not, the following flow takes place:
o The POC visit URL is being returned to the telehealth client application
Page 11 of 73
Date issued:
05-Dec-20
o The telehealth client application opens a web view with the provided URL
o Tyto web server generates a QR code
o The user scans the QR code with the Tyto device
o Tyto device uses the provided session token and visit id to join the visit
During the online visit, the session is maintained (and does not expire, if the Tyto device is
used).
The online visit remains active even if the user has closed the mobile application or aborted
the visit, until a request to complete the visit is sent to TytoCare server (usually per the
clinician side request)
Server Side Point of Care
Telehealth
TytoCare TeleHealth TytoCare
Mobile
Server Server Device
Application
Create/Join Visit
Create/Join Visit (Visit details,
POC user)
Patient URL (session token, Tyto
Visit id)
Patient URL (session token,
Tyto Visit id)
Visit QR Code (webview) (session token, Tyto Visit id)

Scan Visit QR
Join Visit (session token, Tyto Visit id)

Visit details (Patients details, Visit meta data)
7.3 Server
7.3.1 General
Server to server integration is required to support all integration flows. The Server integration
relies on a restful API approach that enables fast development and an easily readable code.
TytoCare server is hosted in the Cloud and does not initiate calls to Tyto’s partner’s servers –
enabling them to remain on premise without being exposed.
Page 12 of 73
Date issued:
05-Dec-20
Unlike the client-to-server mechanism mentioned before – the server-to-server

communication is session less.
As part of the integration, it is possible to receive notifications messages from TytoCare

server.
7.3.2 API Concept

The APIs were designed and built according to common restful guidelines, specifically:
7.3.2.1 URL signatures

• URLs are used to represent the resource at subject (e.g. /patients/123 represent
patient 123).
• All URLs start with a version number, to keep compatibility during future versions
release.
• Links between resources can be inferred from URLs (e.g. DELETE on
/accounts/123/patient/456 means that patient 456 should not be related to account
123
7.3.2.2 Request Methods

Methods applied on resource comply with HTTP methods
• GET – view resource details
• POST – create a resource
• PUT – update a resource
• DELETE – delete a resource
• Other HTTP methods are not supported
7.3.2.3 Response status codes

Methods operations status are represented by HTTP status
Status Description
code
200 the request was completed successfully
201 same as 200, when the call generates a new entity
400 bad request - the message format is wrong, some of the arguments are missing
401 authentication issue – invalid IP, wrong password etc.
403 permission denied exception was raised
404 at least one of the entities referred to in the request is missing
Page 13 of 73
Date issued:
05-Dec-20
409 conflict - an application error has occurred due to a conflict (object already
found etc.)
422 an invalid parameter was used
When error occurs an additional “code” member on the response is provided (e.g.
{code: ‘ERROR_USER_IS_DISABLED’})
In testing environments, the response also includes a friendly error message with some details
on the error ((e.g. {code: ‘ERROR_INVALID_ARGUMENT, message: ’date of birth cannot be in
the future’})
Note: most of response errors listed above are not request specific.
7.3.2.4 Content type (&accept header)

Resources are represented in JSON (so API methods consume and produce JSON as well)
7.3.2.5 Dates
Date time fields comply with ISO 8601 (e.g.1970-01-01T00:00:00Z)
7.3.2.6 Notations
Camel case notation for variable names and resource names (e.g. userId).
Constants are written in upper case (words are separated by underscore, e.g.
INVALID_ARGUMENT).
7.3.3 Security considerations

API calls authentication and authorization are evaluated per request. Additional security
mechanisms are used to ensure data protection.
Calling Tyto Server from a Tyto’s partner client application is not supported.
7.3.3.1 Protocol
APIs are available over HTTPS only.
7.3.3.2 Authentication
A Basic authentication mechanism is used for the APIs, requiring an access key and a secret
key for each request.
The access key and secret key will be provided by TytoCare but can be generated by an admin
as well (within the admin portal, under the API users tab).
Page 14 of 73
Date issued:
05-Dec-20
The secret key is stored hashed and cannot be retrieved once generated, so it’s available only
in the time of the creation.
It is advised to work with 2 access key – secret key pairs, so they can be switched without
down time.
Note:
The old mode in which the http header “X-Partner-Identity” is added to each call is still
supported.
7.3.3.3 IP restriction
API requests remote address is verified against a pre-defined list of ip ranges.
Each access key – secret key pair must be associated with at least one ip range.
7.3.3.4 TOTP
API requests can be better secured by using TOTP (Time-based One-Time Password).
To use it, the following steps are required:
• Receiving a shared “secret” phrase from TytoCare
• Storing the secret with a config file
• Using a library to generate a TOTP using the stored secret (example code can be found
here: https://tools.ietf.org/html/rfc6238
• Passing the result of the library call as an additional header named “totpCode” within
each call (values can be checked using Google Authenticator)
7.3.3.5 WAF
APIs are protected with a web application firewall.
Consecutive failed attempts (accessing resources that don’t exist, invalid credentials etc.)
might block the API or even the IP for a few minutes.
7.3.3.6 Logging
API calls are logged and monitored – mainly for suspicious activity detection.
7.3.4 Deployment
TytoCare maintains 2 environments for integration:
Name URL Purpose Comments

Production https://app- Should be used only Changes made by
cloud.tytocare.com/api for real patients, real API calls cannot be
visits etc. reverted
Page 15 of 73
Date issued:
05-Dec-20
Staging https://app- To be used prior to A stable

stage1.tytocare.com/api new releases environment – will
usually hold the
latest version when
no new version is
about to be
released
7.3.5 Notification messages

It is possible to receive a message from TytoCare server regarding visits that were completed
within Tyto. To receive such messages, it is required to provide a rest-full service and Basic
authentication credentials.
8. WEB INTERFACE – DETAILS
8.1 Web View

TytoCare provides a simple web view for online sessions, that enables the following:
• Controlling the device checkups
• Capturing audio and video from the device and playing it
The web view must run within Chrome as iframe with the following attributes:
sandbox="allow-same-origin allow-popups allow-forms allow-scripts allow-top-
navigation" allow="autoplay; fullscreen; animations" frameBorder="0" width=”600”
height=”600”
Do note: the web view size must be 600 pixels width and 600 pixels height and is not
responsive:
Since the web view utilizes the browser’s session storage, the hosting web application
should verify that the browser does not block third party cookies and site data.
Additional information can be found here:
• https://whatismybrowser.com/detect/are-third-party-cookies-enabled
• https://github.com/mindmup/3rdpartycookiecheck
When using CSP (content security policy) tytocare’s domain should be whitelisted under the
“default-src” attribute.
Page 16 of 73
Date issued:
05-Dec-20
9. POC INTERFACE – DETAILS
9.1 Internet access

The only integration required in the POC relates to the Wi-Fi settings.
Within this process, the user enters the SSID and passkey and generates a QR code that the
device can scan.
9.2 QR Format – updated version
Parameter Description Value

A
Version of QrCode V4
B
SSID Password length
C
Internal use
D
Internal use 0
E
Internal use
F
Internal use
G
Internal use
H The length refers to the number of
ssid length
bytes (in UTF-8), and not to the
number of characters
I
ssid+password
J Epoch time
UTC time
K
ssid encoded base 64
length
L ssid encoded base 64
M
Pairing details (as received from Tyto Server)
N Internal use vExternal
Page 17 of 73
Date issued:
05-Dec-20
The format is:

:A:B:C:D:E,F,G,H,I,J,K,L,M,N
For example, if the ssid is “MyNetwork” (not hotspot), the password is “MyPassword”, the
pairing details are {“key1”:”value1”,”key2:”value2”}, and the time is 2017-04-
26T09:06:26+00:00 in ISO 8601, the string will be:
:V4:10::0:,,,9,MyNetworkMyPassword,1493197586,12,TXlOZXR3b3Jr,
{“key1”:”value1”,”key2:”value2”},vExternal
Please make sure no new line (e.g. \n) characters are included in the QR
Page 18 of 73
Date issued:
05-Dec-20
10. SERVER INTERFACE - DETAILS
10.1 Accounts
10.1.1 Overview
Accounts APIs enable the management of patients and family members.
Patients that cannot access the system independently are not relevant for this API – see
section Patients.
10.1.2 API List
10.1.2.1 Add Account
10.1.2.1.1 Request
POST /v1/integration/accounts
10.1.2.1.2 Request parameters

Name Data Mand Validation Length Comments
type atory
firstName String Yes ^[0-9a-zA-Z' ]*$ 20
lastName String Yes ^[0-9a-zA-Z' ]*$ 30
dateOfBirth Date Yes Account user’s age
must be more than
18
sex String Yes F or M are accepted 1
email String Yes Email pattern is 70 This email will be
used used to
communicate
with the account
user
phone String No A 10 digits’ string is 10 Country code is
expected not needed
identifier String Yes ^[A-Za-z0-9\.:_\-@ 40 This field will be
]*$ used to identify
In addition, this the account via
field must be API requests
unique
Page 19 of 73
Date issued:
05-Dec-20
username String No ^[a-zA-Z0-9@\.]*$ 70 If no username is

provided, a
random
username will be
created
role String No The name is The name of the
compared to the role created in
names created via the admin portal.
the admin portal If no role
provided, a
default one will
be used
locationIdentifier String No The identifier of
the location
entity within Tyto
convertToAccount Boolean No When marked as
true, this method
will convert
existing patients
to accounts
disconnectFromOt Boolean No When converting
herAccounts patients to
accounts, use
this flag to
keep/disconnect
formal links
between the
patient to its
accounts
patientIdentifier String No Use in case the
default patient
identifier and the
account
identifier are
different
telehealthIdentifie String No Used for AmWell
r integration
state String No The state code
city String No
zipCode String No
address1 String No
Page 20 of 73
Date issued:
05-Dec-20
address2 String No
10.1.2.1.3 Exceptions
Http Code Comments

Status
409 ERROR_ACCOUNT_EXTERNAL_IDENTIFIER_ALREADY_EXISTS An account with
the same
identifier already
exists
409 ERROR_USERNAME_ALREADY_EXISTS A user with the
same username
already exists
404 ERROR_ROLE_NOT_FOUND Role name
doesn’t exist
10.1.2.1.4 Notes
Creating an account also automatically creates a patient with the same details. It is assumed
that the primary patient created for the account will have the same identifier as the account
10.1.2.2 Update Account
10.1.2.2.1 Request
PUT /v1/integration/accounts/{identifier}

Name Data Mandatory Validation Length Comments
type
firstName String No ^[0-9a-zA-Z' ]*$ 20
lastName String No ^[0-9a-zA-Z' ]*$ 30
dateOfBirth Date No Account user’s
age must be
more than 18
sex String No F or M are 1
accepted
email String No Email pattern is 70 This email will
used be used to
communicate
Page 21 of 73
Date issued:
05-Dec-20
with the
account user
phone String No A 10 digits’ 10 Country code is
string is not needed
expected
the location
entity within
Tyto
Http Code Comments
Status
404 ERROR_ACCOUNT_NOT_FOUND An account with this identifier doesn’t
exist (or exists but disabled)
10.1.2.2.4 Notes
• A message with only the relevant fields will be acceptable
• A message with an empty content (e.g. {phone:’’} will nullify the field content (as
opposed to sending the field at all – which will not result with an entity modification.
10.1.2.3 View account
10.1.2.3.1 Request
GET /v1/integration/accounts/{identifier}
10.1.2.3.2 Response
The response will include a map with the following fields
Name Data Comments
type
firstName String
lastName String
sex String
dateOfBirth Date
username String
email String
phone String
isActive Boolean
Page 22 of 73
Date issued:
05-Dec-20
isPaired Boolean Deprecated – use

devicePairingStatus
instead
approvalStatus String
locationIdentifier String
devicePairingStatus String Valid values are
PAIRED
PREVIOUSLY_PAIRED
NOT_PAIRED
isDeviceOnline Booolean Indicates if the

account’s last device
was recently active
(communicated with
the server in the last
5 minutes)
deviceMacAddress String The device mac
address in case the
devicePairingStatus
is PAIRED
deviceSerialNumber String The device serial
number in case the
devicePairingStatus
is PAIRED
Http Code Comments

Status
404 ERROR_ACCOUNT_NOT_FOUND The account identifier could not be found
10.1.2.3.4 Notes
Empty fields will not be returned
This method should not be polled to get an updated device status – it shuod be used once
and based on user interaction.
10.1.2.4 Add account patient
10.1.2.4.1 Request
Page 23 of 73
Date issued:
05-Dec-20
POST /v1/integration/accounts/{account identifier}/patients

Name Data Mandator Validatio Lengt Comments
type y n h
firstName String Yes ^[0-9a- 20
zA-Z' ]*$
lastName String Yes ^[0-9a- 30
zA-Z' ]*$
dateOfBirth Date Yes
sex String Yes F or M 1
are
accepted
identifier String Yes ^[A-Za- 40 This field will
z0-9\.:_\- be used to
@ ]*$ identify the
In patient via API
addition, requests
this field
must be
unique
(for all
patients)
disconnectFromOtherAccou Boolea No Use this flag to
nts n keep/disconne
ct formal links
between the
patient to its
accounts
Http Code Comments

Stat
us
409 ERROR_PATIENT_EXTERNAL_IDENTIFIER_ALREADY_EXI A patient with the same
STS identifier already exists
409 ERROR_PATIENT_NAME_ALREADY_EXISTS_FOR_THE_A A patient with the same

CCOUNT first name already exists
Page 24 of 73
Date issued:
05-Dec-20
404 ERROR_ACOUNT_NOT_FOUND The account identifier

does not exist (or exists
but disabled)
409 ERROR_MAX_NUMBER_OF_USERS_PER_PATIENT_EXCE The patient was already
EDED associated to (too many)
accounts
10.1.2.4.4 Notes
In addition to the patient association with the account, the patient details will be updated
10.1.2.5 Update account patient
10.1.2.5.1 Request
PUT /v1/integration/patients/{patient identifier}
OR
PUT /v1/integration/patients/{patient identifier}?qa=true

type
dateOfBirth Date No For account
primary patient -
age must be
more than 18
accepted
Identifier String No Can be used to
replace the
current
identifier. Can
be used in
conjunction
with setting
isExternal to
false when
Page 25 of 73
Date issued:
05-Dec-20
using a tyto
identifier
Http Code Comments
Status
404 ERROR_PATIENT_NOT_FOUND A user with this identifier doesn’t exist (or
exists but disabled)
10.1.2.5.4 Notes
A message with only the relevant fields will be acceptable.
The request URL does not include the account identifier since this operation is applicable
without it.
10.1.2.1 Remove account patient
10.1.2.1.1 Request
DELETE /v1/integration/accounts/{account identifier}/patients/{patient identifier}

Name Data type Mandatory Validation Length Comments
disconnectOnly Boolean No When set to rue,
the account
patient will only
disconnect from
the account
Http Code Comments
Status
404 ERROR_PATIENT_NOT_FOUND A patient with this identifier
doesn’t exist (or exists but
disabled), or is not associated
with the account
404 ERROR_ACCOUNT_NOT_FOUND An account with this identifier

doesn’t exist (or exists but
disabled)
Page 26 of 73
Date issued:
05-Dec-20
409 ERROR_CANNOT_DELETE_PRIMARY_PATIENT The call attempts to remove

the account primary patient
10.1.2.1.4 Notes
If the patient is associated only the account specified – he will be deactivated.
Otherwise, just the account-patient relation will be deleted.
10.1.2.2 Enable/Disable account
10.1.2.2.1 Request
PUT /v1/integration/accounts/{identifier}/status

Name Data Mandat Validation Length Comments
type ory
isActive Boolean Yes
Http Code Comments
Status
doesn’t exist
10.1.2.2.4 Notes
The account will not be able to login once disabled.
If the patient is associated with another account – only the linkage to the account in the URL
will be removed, and the patient details will remain unchanged.
However, if the patient is not associated with another account – it will be marked as inactive.
10.1.2.3 View account patients
10.1.2.3.1 Request
GET /v1/integration/accounts/{account identifier}/patients
10.1.2.3.2 Response
Page 27 of 73
Date issued:
05-Dec-20
The response will include an array of patients. For each patient, a map with the following
details will be provided:
Name Data
type
firstName String
lastName String
sex String
dateOfBirth Date
IsPrimary Boolean
Http Code Comments
Status
404 ERROR_ACCOUNT_NOT_FOUND An account with this
identifier doesn’t exist
(or exists but disabled)
10.1.2.4 View accounts
10.1.2.4.1 Request
GET /v1/integration/accounts

type ory
approvalStatus String No APPROVED or
PENDING or
DISAPPROVED
firstName String No Wildcard search
lastName String No Wildcard search
Identifier String No Wildcard search
tytoIdentifier String No Wildcard search
email String No Wildcard search
phone String No Wildcard search
Page 28 of 73
Date issued:
05-Dec-20
hasPatients Boolean No (excluding the

acccoun’t default
patient)
isActive Boolean No
One of the fields above must be provided.
10.1.2.4.3 Response
The response will include an array of accounts. For each account, a map with the following
Name Data
type
firstName String
lastName String
sex String
dateOfBirth Date
email String
phone String
isActive Boolean
identifier String
tytoIdentifier String
10.1.2.4.4 Notes
The method can be used to retrieve the list of self-registered accounts with identifiers that
were not approved.
The maximum number of records returned per request is 100
10.1.2.5 View accounts’ patients
10.1.2.5.1 Request
GET /v1/integration/accounts/patients
Page 29 of 73
Date issued:
05-Dec-20

type ory
approvalStatus String No APPROVED or
PENDING or
DISAPPROVED
firstName String No Wildcard search
lastName String No Wildcard search
tytoIdentifier String No Wildcard search
accountIdentifier String NO Wildcard search
10.1.2.5.3 Response
The response will include an array of accounts. For each account, a map with the following
Name Data
type
firstName String
lastName String
sex String
dateOfBirth Date
identifier String
accountIdentifier String
10.1.2.5.4 Notes
The method can be used to retrieve the list of self-registered account patients with identifiers
that were not approved.
10.1.2.6 Approve account
10.1.2.6.1 Request
PUT /v1/integration/accounts/{tyto identifier}/approvalStatus
Page 30 of 73
Date issued:
05-Dec-20

type ory
isApproved Boolean Yes
Http Code Comments
Status
doesn’t exist
10.1.2.7 Approve patient
10.1.2.7.1 Request
PUT /v1/integration/patients/{tyto identifier}/approvalStatus

type ory
isApproved Boolean Yes
Http Code Comments
Status
doesn’t exist
10.1.2.8 Account device pairing request
10.1.2.8.1 Request
POST /v1/integration/accounts/{identifier}/pairingRequests

No parameters are needed
10.1.2.8.3 Response
The response will include the following fields
Name Data Comments
type
Page 31 of 73
Date issued:
05-Dec-20
pairingDetails String The information included in the response should be

added to the QR code along with the Wi-Fi network
details
Http Code Comments

Status
404 ERROR_ACCOUNT_NOT_FOUND Account doesn’t exist
10.1.2.8.5 Notes
The pairing code returned from the server is valid for 10 minutes. After this time elapsed, a
new code should be generated.
10.2 Patients
10.2.1 Overview
Those APIs enable the patient’s management. Patients created in this API do not have access
to Tyto device and cannot login to Tyto applications.
10.2.2 API List
10.2.2.1 Add Patient
10.2.2.1.1 Request
POST /v1/integration/patients

Name Data Mand Validation Length Comments
type atory
dateOfBirth Date Yes
sex String Yes F or M are accepted 1
Page 32 of 73
Date issued:
05-Dec-20

unique
the location
entity within Tyto
Http Code Comments

Status
409 ERROR_PATIENT_EXTERNAL_IDENTIFIER_ALREADY_EXISTS A patient with the
same identifier
already exists
10.2.2.2 Update Patient
10.2.2.2.1 Request
PUT /v1/integration/patients/{identifier}
Or
POST /v1/integration/ patients/{identifier}?isExternal=true

type
dateOfBirth Date No
accepted
the location
entity within
Tyto
Identifier String No Can be used to
replace the
Page 33 of 73
Date issued:
05-Dec-20
current
identifier. Can be
used in
conjunction with
setting isExternal
to false when
using a tyto
identifier
Http Code Comments
Status
doesn’t exist
10.2.2.2.4 Notes
10.2.2.3 Delete Patient
10.2.2.3.1 Request
DELETE /v1/integration/patients/{identifier}
Http Code Comments
Status
doesn’t exist
10.2.2.3.3 Notes
The patient will not be removed from the system, but will become inactive.
10.2.2.4 View patient
10.2.2.4.1 Request
GET /v1/integration/patients/{identifier}
10.2.2.4.2 Response
Page 34 of 73
Date issued:
05-Dec-20
Name Data type

firstName String
lastName String
sex String
dateOfBirth Date
approvalState String
accountIdentifiers List of Strings
Http Code Comments

Status
404 ERROR_PATIENT_NOT_FOUND A patient with that identifier does
not exists (or exists but disabled)
10.2.2.4.4 Notes
10.2.2.5 View patient exams
10.2.2.5.1 Request
GET /v1/integration/patients/{identifier}/exams
10.2.2.5.2 Response
The response will include a list of exams the patient agreed to share with the organization.
Each exam will include the following fields
Name Data type Comments
date String
checkups String The list of checkups performed within the exam
(lungs, heart etc.), comma delimited
Http Code Comments

Status
404 ERROR_PATIENT_NOT_FOUND A patient with that identifier does not exists
Page 35 of 73
Date issued:
05-Dec-20
10.2.2.5.4 Notes
10.2.2.6 Create patient review
10.2.2.6.1 Request
POST /v1/integration/patients/{identifier}/reviews

type ory
clinicianIdentifier String Yes (No)
accountIdentifier String No (Yes)
remoteAddress String Yes The ip from
which the
account will hold
the session
The request parameters consists of 2 pairs, that only one of them should be set – either the
account’s or the clinician’s
10.2.2.6.3 Response
The response will include an array of the visits details (map) with the following fields
url String A URL that is used to open a web application to review the
visit
Http Code Comments
Status
404 ERROR_PATIENT_DOES_NOT_EXIST A patient with that identifier
could not be found
404 ERROR_ONE_USER_IDENTIFIER_IS_EXPECTED The clinician identifier or
account identifiers were not
provided
409 ERROR_REMOTE_ADDRESS_NOT_PROVIDED The remote address was not
provided for the account
10.2.2.6.5 Notes
If a session was already created for this user – it will be reused
Page 36 of 73
Date issued:
05-Dec-20
10.2.2.1 Merge patients
10.2.2.1.1 Request
POST /v1/integration/patients/merges

type ory
sourceIdentifier String Yes
targetIdentifier String Yes
Http Code Comments
Status
404 ERROR_PATIENT_DOES_NOT_EXIST A patient with that identifier
could not be found
10.3 Clinicians
10.3.1 Overview
The API enables clinician management. Clinicians will, in most cases, use single sign-on to
login.
10.3.2 API List
10.3.2.1 Add clinician
10.3.2.1.1 Request
POST /v1/integration/clinicians

Name Data type Mandat Validation Length Comments
ory
dateOfBirth Date Yes Clinician’s age must
be more than 21
Page 37 of 73
Date issued:
05-Dec-20
sex String Yes F, M and U are 1

accepted
email String Yes Email pattern is 70 This email will be
used used to
communicate
with the account
user
phone String No A 10 digits’ string is 10
expected
unique
title String No ^[A-Za-z\., \-' ]*$ 20
username String No ^[a-zA-Z0-9@\.]*$ 70 If no username is

provided, a
random
username will be
created
role String No The name is The name of the
compared to the role created in
names created via the admin portal.
the admin portal If no role
provided, a
default one will
be used
locationIdentifi String No A comma delimited
ers list of location
identifiers
Http Code Comments

Status
409 ERROR_CLINICIAN_EXTERNAL_IDENTIFIER_ALREADY_EXISTS A clinician with the
same identifier
already exists
Page 38 of 73
Date issued:
05-Dec-20
409 ERROR_USERNAME_ALREADY_EXISTS A user with the

same username
already exists
404 ERROR_ROLE_NOT_FOUND Role name doesn’t
exist
10.3.2.2 Update clinician
10.3.2.2.1 Request
PUT /v1/integration/clinicians/{identifier}

type ory
dateOfBirth Date No Clinician’s age must
be more than 21
sex String No F, M and U are 1
accepted
email String No Email pattern is 70
used
phone String No A 10 digits’ string is 10
expected
title String No ^[A-Za-z\., \-' ]*$ 20
locationIdentifi String No A comma delimited

ers list of location
identifiers
Http Code Comments

Status
404 ERROR_CLINICIAN_NOT_FOUND A clinician with this identifier does not
exist (or exists but disabled)
10.3.2.2.4 Notes
Page 39 of 73
Date issued:
05-Dec-20

• A message with an empty content (e.g. {phone:’’}) will nullify the field content
10.3.2.3 Enable/Disable clinician
10.3.2.3.1 Request
PUT /v1/integration/clinicians/{identifier}/status

type ory
Http Code Comments
Status
404 ERROR_CLINICIAN_NOT_FOUND A clinician with this identifier doesn’t exist
10.3.2.3.4 Notes
The clinician will not be able to login once disabled
10.3.2.4 View clinician
10.3.2.4.1 Request
GET /v1/integration/clinicians/{identifier}
10.3.2.4.2 Response
Name Data
type
firstName String
lastName String
sex String
dateOfBirth Date
username String
email String
phone String
title String
isActive Boolean
Page 40 of 73
Date issued:
05-Dec-20

devicePairingStatus
instead
locationIdentifiers String
devicePairingStatus String
Valid values are
PAIRED
PREVIOUSLY_PAIRED
NOT_PAIRED
was recently active
(communicated with
5 minutes)
address in case the
devicePairingStatus
is PAIRED
number in case the
devicePairingStatus
is PAIRED
Http Code Comments

Status
404 ERROR_CLINICIAN_NOT_FOUND The clinician identifier doesn’t exist (or
exists but disabled)
10.3.2.5 Clinician device pairing request
10.3.2.5.1 Request
POST /v1/integration/clinicians/{identifier}/pairingRequests

No parameters are needed
10.3.2.5.3 Response
Page 41 of 73
Date issued:
05-Dec-20

Name Data Comments
type
details
Http Code Comments

Status
404 ERROR_CLINICIAN_NOT_FOUND Clinician doesn’t exist
10.3.2.5.5 Notes
The pairing code returned from the server is valid for 10 minutes. After this time elapsed, a
new code should be generated.
10.4 Stations
10.4.1 Overview
Stations can be any type of computer (desktop, laptop, mobile device) that is attached to a
TytoCare device at the Point of Care. This can apply to cases such as hospital carts,
ambulances etc.
10.4.2 API List
10.4.2.1 Create station
10.4.2.1.1 Request
POST /v1/integration/stations

type ory
identifier String Yes ^[0-9a-zA-Z' ]*$ 40
Page 42 of 73
Date issued:
05-Dec-20
description String No 150 Can be used to

specify location
or computer type
the location
entity within
Tyto
Http Code Comments

Status
409 ERROR_STATION_ALREADY_EXISTS
Page 43 of 73
Date issued:
05-Dec-20
10.4.2.2 Update station
10.4.2.2.1 Request
PUT /v1/integration/stations/{identifier}

type ory
description String No 150
the location
entity within
Tyto
Http Code Comments

Status
404 ERROR_STATION_NOT_FOUND A station with this identifier does not exist
10.4.2.3 Enable/Disable station
10.4.2.3.1 Request
PUT /v1/integration/stations/{identifier}/status

type ory
Http Code Comments
Status
404 ERROR_STATION_NOT_FOUND A station with this identifier doesn’t exist
10.4.2.3.4 Notes
The station will not be able to be used
Page 44 of 73
Date issued:
05-Dec-20
10.4.2.4 View station
10.4.2.4.1 Request
GET /v1/integration/stations/{identifier}
10.4.2.4.2 Response
Name Data Comments
type
description String
isActive Boolean
devicePairingStatus
instead
devicePairingStatus String Valid values are
PAIRED
PREVIOUSLY_PAIRED
NOT_PAIRED
was recently active
(communicated with
5 minutes)
address in case the
devicePairingStatus
is PAIRED
number in case the
devicePairingStatus
is PAIRED
Http Code Comments

Status
404 ERROR_STATION_NOT_FOUND The station identifier doesn’t exist
Page 45 of 73
Date issued:
05-Dec-20
10.4.2.1 View stations
10.4.2.1.1 Request
GET /v1/integration/stations

type ory
10.4.2.1.3 Response
The response will include an array of stations. For each station, a map with the following
Name Data
type
isActive Boolean
Identifier String
description String
10.4.2.1.4 Notes
10.4.2.2 Station device pairing request
10.4.2.2.1 Request
POST /v1/integration/stations/{identifier}/pairingRequests

type ory
Description String No 150 Wildcard search
10.4.2.2.3 Response
Name Data Comments
type
Page 46 of 73
Date issued:
05-Dec-20

details
10.4.2.2.4 Notes
• The system can be configured to support creation of stations on the fly if they are
missing
• The pairing code returned from the server is valid for 10 minutes. After this time
elapsed, a new code should be generated.
Http Code Comments

Status
404 ERROR_STATION_NOT_FOUND Station doesn’t exist
Page 47 of 73
Date issued:
05-Dec-20
10.5 Visits
10.5.1 Overview
The visits API is used for creation of visits and for data retrieval after their completion.
10.5.2 API List
10.5.2.1 Get visits
10.5.2.1.1 Request
GET /v1/integration/visits

type ory
fromDate Date No Refers to the visit
creation date
toDate Date No Refers to the visit
creation date
clinicianIdentifier String No
patientIdentifier String No
visitIdentifier String No
status String No PENDING or
ACTIVE or
COMPLETED or
READY
assistingClinicianId String No
entifier
stationIdentifier String No
10.5.2.1.3 Response
Name Data Comments
type
createdOnDate Date
status String
statusDate Date
performedCheckups String A comma separated list of exams performed within the
visit
Page 48 of 73
Date issued:
05-Dec-20
isOnline Boolean Indicates whether this visit was done in a conference

with a clinician
tytoIdentifier String A unique identifier provided by Tyto
identifier String The identifier provided by the create visit API call
clinicianIdentifier String
Http Code Comments
Status
404 ERROR_ACCOUNT_NOT_FOUND The account identifier
could not be found
404 ERROR_PATIENT_NOT_FOUND The patient identifier could
not be found
404 ERROR_CLINICIAN_NOT_FOUND The clinician identifier
could not be found
10.5.2.1.5 Notes
• Automatic filters:
o Offline visits that are still in preparation phase will not be returned.
o Cancelled visits will not be returned.
• When there are no results – the result will be an empty list (with Http status OK)
• Not more than 100 results (the latest) will be returned for each request.
10.5.2.2 Create visit
10.5.2.2.1 Request
POST /v1/integration/visits

type
patientIdentifier String Yes
accountIdentifier String No (see
notes)
identifier String Yes ^[A-Za-z0- 40
9\.:_\-@ ]*$
Page 49 of 73
Date issued:
05-Dec-20
In addition,
this field must
be unique
clinicianRemoteAd String No The ip from
dress which the
clinician will hold
the session. This
field is
mandatory if a
clinician is
provided
tytoExamIdentifiers String No A list of exams
Array created in the
POC that will be
reviewed during
the visit
AssistingClinicianId String No (see The identifier of
entifier notes) the clinician in
the POC
reviewerIdentifier String No The identifier of a
clinician that can
review
recordings done
within this
session
reviewerRemoteAd String No The ip from
dress which the
reviewer will
hold the session.
This field is
mandatory if a
clinician is
provided
stationIdentifier String No (see The identifier of
notes) the station in the
POC
stationRemoteAddr String No The ip from
ess which the station
will hold the
session.
Page 50 of 73
Date issued:
05-Dec-20
useTytoApp Boolean No Should be

marked with
“true” when the
visit includes not
only the device
part
status String No ACTIVE or When a clinician
PENDING details are
provided, the
visit becomes
Active by default.
It is possible to
specify that the
visit will remain
Pending, so
turning to Active
will be done
manually from
within Tyto web
application
mobileIdentifier String No Should include
the mobile mac
address. When
provided, only
calls from within
that mobile will
be answered
10.5.2.2.3 Response
Name Data Comments
type
tytoIdentifier String A 32 characters string that can be later used by the EHR
system
patientUrl String A URL that is used to open a web view. The web view
includes a QR code that the device should scan. The URL
includes a session token which enables the device to
communicate with the server without additional
authentication.
Created only for online visits.
Page 51 of 73
Date issued:
05-Dec-20
The patientUrl is not returned if the device is already

connected
clinicianUrl String A URL that is opened to open the web page / IFrame that
can be integrated in the clinician web application
The URL includes a session token which enables the
device to communicate with the server without
additional authentication.
Created only for online visits and only if a clinician
identifier was provided.
reviewerUrl String A URL that is used to open a web application to review
the visit. The link is provided only if a reviewer identifier
was provided.
isDeviceConnected Boolean Indicates whether the device is up and running (only in
case the device is configured to join a visit automatically).
Http Code Comments
Status
could not be found
404 ERROR_PATIENT_NOT_FOUND The patient identifier
could not be found
could not be found
404 ERROR_STATION_NOT_FOUND The station identifier
could not be found
409 ERROR_VISIT_EXTERNAL_IDENTIFIER_ALREADY_EXISTS A visit with the same
identifier already
exists (and cannot be
resumed)
409 ERROR_PARTICIPANT_ENGAGED At least one of the
participants is
currently engaged on
another visit
409 ERROR_PATIENT_IS_ON_ANOTHER_QUEUE The patient is on
another visit
409 ERROR_STATION_IS_NOT_PAIRED The station doesn’t
not have a device
10.5.2.2.5 Notes
Page 52 of 73
Date issued:
05-Dec-20
If the visit is active, and all the identifiers are the same – the returned response will be
identical to the one returned in case of success. This behavior will enable resuming
interrupted sessions.
If sessions expire, the visit users – both the clinician and consumer – will be able to resume
the visit using the same API call.
If clinician was not provided, the visit status will remain pending, until a clinician is assigned,
and the visit status is set to “ACTIVE”.
The identifier of either the account, assisting clinician or station should be provided.
If the visit should be used within tyto (useTytoApp is set as true) the API doesn’t return patient
and clinician urls.
10.5.2.2.6 Example
Request URL /v1/integration/visits
Request body {“clinicianIdentifier”:” WGZ6BwcWCa0qLXoBGcLCS”,
“clinicianRemoteAddress”:”212.135.14.31”,
“patientIdentifier”:”6rswepssefie”,
“accountIdentifier”:”78whfpefh98a4”,
“identifier”:”78gdywe8yfw74whfn”,
“examIdentifiers”:[“zb8wg8oew”,”sc8ufesfj9sefa“]}
Response body {“clinicianUrl”:”https://cloud.tytocare.com/#/onlineVisits/9KLOkGxDf”,
“patientUrl”:”https://cloud.tytocare.com/#/deviceVisits/78ysno8ufcvs”,
“tytoIdentifier”:”hf9qf8e7f9wpeh99”}
10.5.2.3 Update visit
10.5.2.3.1 Request
PUT /v1/integration/visits/{identifier}

Name Data Manda Validation Length Comments
type tory
procedureCodes String No 1000
diagnosisCodes String No 1000
Http Status Code Comments
404 ERROR_VISIT_NOT_FOUND The visit identifier could not be found
Page 53 of 73
Date issued:
05-Dec-20
10.5.2.3.4 Example
Request URL /v1/integration/visits/t1tnMsHwhqmuZLqeIk
Request body {“clinicianIdentifier”:”ma0fufaa”, “diagnosisCodes”:”123.2, 495.8”}
10.5.2.3.5 Notes
This method can be used to assign a clinician to the visit
10.5.2.4 Complete visit / Cancel visit / start visit
10.5.2.4.1 Request
PUT /v1/integration/visits/{identifier}/status

type tory
status String Yes COMPLETED or
CANCELLED or
ACTIVE
clinicianRemoteA String No Mandatory only
ddress if the status is
ACTIVE
clinicianIdentifier String No Mandatory only
if the status is
ACTIVE
10.5.2.4.3 Response
clinicianUrl String A URL that is opened to open the web page / IFrame that
can be integrated in the clinician web application
The URL includes a session token which enables the device
to communicate with the server without additional
authentication.
Created only for online visits if the status provided to this
call is “ACTIVE”
Page 54 of 73
Date issued:
05-Dec-20
Http Code Comments
Status
404 ERROR_VISIT_NOT_FOUND A visit with the provided identifier
could not be found
409 ERROR_INVALID_STATE Visit status cannot be changed
409 ERROR_CLINICIAN_IS_NOT_ASSIGNED The visit was not assigned to any

clinician
10.5.2.4.5 Notes
Once a visit status has been set to COMPLETED or CANCELLED, it cannot change again.
10.5.2.4.6 Example
Request URL /v1/integration/visits/t1tnMsHwhqmuZLqeIk/status
Request body {”status”:”COMPLETED”}
If a clinician / account has visits that have started but were not completed, a new visit cannot
be created.
10.5.2.5 View visit
10.5.2.5.1 Request
GET /v1/integration/visits/{tyto identifier}
10.5.2.5.2 Response
The response will include of the visits details (map) with the following fields
Name Data Comments
type
patientIdentifier String
accountIdentifier String
clinicianIdentifier String
isOnline Boolean
identifier String As provided by the EHR system
createdOnDate Date
status String Online visits can active be pending, active, completed or
cancelled
Offline visits can be ready, completed or cancelled
Page 55 of 73
Date issued:
05-Dec-20
statusDate Date
isPatientOnline Boolean
isClinicianOnline Boolean
isDeviceConnected Boolean Indicates that the device has connected to the visit (for
Active or Pending visits only)
url String A static (session-less) link to the visit that can be
embedded in EMR (SSO link is created if the organization
supports SSO)
results List A list of vital signs collected in the visit
performedCheckups String A comma separated list of checkup types included in that
visit
10.5.2.5.4 Example
Request URL /v1/integration/visits/t1tnMsHwhqmuZLqeIk
Response body {“tytoIdentifier”:”9KL5OkGpPxoDfa”,
“patientIdentifier”:”sdjkfhis98sfs”,
“accountIdentifier”:”y87aysdkad909u”,
“clinicianIdentifier”:”s7f8yn309werf”, “isOnline”:true,
“createdOnDate”:”2016-10-24T18:21Z”,”status”:”COMPLETED”,
“statusDate”: ”2016-10-24T18:27:04Z”}
10.5.2.6 Create visit review
10.5.2.6.1 Request
POST /v1/integration/visits/{tyto identifier}/reviews
Or
POST /v1/integration/visits/{identifier}/reviews?isExternal=true

type ory
clinicianIdentifier String Yes (No)
Page 56 of 73
Date issued:
05-Dec-20
accountIdentifier String No (Yes)

remoteAddress String Yes (No) The ip from
which the
clinician will hold
the session
Either the account’s identifier or the clinician’s identifier should be set
10.5.2.6.3 Response
url String A URL that is used to open a web application to review the
visit
Http Code Comments
Status
404 ERROR_VISIT_NOT_FOUND The visit identifier could not be
found
404 ERROR_CLINICIAN_NOT_FOUND The clinician identifier could not
be found
409 ERROR_REMOTE_ADDRESS_NOT_PROVIDED The remote address was not
provided for the clinician /
account
10.5.2.6.5 Notes
If a session was already created for this user – it will be reused
10.5.2.6.6 Example
Request URL /v1/integration/visits/t1tnMsHwhqmuZLqeIk/reviews
Request body {“clinicianIdentifier”:” WGZ6BwcWCa0qLXoBGcLCS”,
“remoteAddress”:”212.135.14.31”}
Response body {“url”:”https://cloud.tytocare.com/#/visitReviews/ 9KL5OkGpPxoDf”}
10.5.2.7 Add visit results
10.5.2.7.1 Request
POST /v1/integration/visits/{tyto identifier}/results
Page 57 of 73
Date issued:
05-Dec-20

type tory
checkupType String Yes Can be one of the
followings:
• BLOOD_PRESSURE
• SP_O2
• WEIGHT
values String No For multi result (blood
array pressure)
value String No
measurementUnit String No Can be one of the
followings:
• mmHg
• kg
• lbs
Either values or value should be provided
Http Code Comments
Status
404 ERROR_VISIT_NOT_FOUND The visit identifier could not be
found
409 ERROR_VISIT_WAS_ALREADY_COMPLETED The visit status doesn’t allow
adding results to it
409 ERROR_VISIT_WAS_ALREADY_CANCELLED The visit status doesn’t allow
adding results to it
409 ERROR_INVALID_CHECKUP_TYPE The checkup type is not supported
409 ERROR_MISSING_VALUE A value field is empty or missing

409 ERROR_MISSING_VALUES A values field is empty or missing
409 INVALID_MEASUREMENT_UNIT The measurement unit doesn’t
match
409 ERROR_TOO_MANY_VALUES Too many values were provided
10.5.2.7.4 Example
Request URL /v1/integration/visits/t1tnMsHwhqmuZLqeIk/reviews
Request body {“checkupType”:”BLOOD_PRESSURE”, “values”:[80,120],
“measurementUnit:”mmHg”}
Page 58 of 73
Date issued:
05-Dec-20
10.5.2.8 Update notes
10.5.2.8.1 Request
PUT /v1/integration/visits/{identifier}/notes

type tory
discussion String No 5000
recommendation String No 5000
Page 59 of 73
Date issued:
05-Dec-20
10.6 User Settings
10.6.1 Overview
The API enables changing a few settings for users (accounts or clinicians).
10.6.2 API List
10.6.2.1 Update parameter
10.6.2.1.1 Request
PUT /v1/integration/accounts/{account identifier}/parameters/{parameter name}
Or
PUT /v1/integration/clinicians/{clinician identifier}/parameters/{parameter name}
Or
PUT /v1/integration/stations/{station identifier}/parameters/{parameter name}

Name Data type Mandatory Validation Length Comments
value String Yes See above
Http Code Comments

Status
could not be found or
The parameter name
doesn’t exist
The parameter name
doesn’t exist
404 ERROR_STATION_NOT_FOUND The station identifier could
not be found or
Page 60 of 73
Date issued:
05-Dec-20
The parameter name

doesn’t exist
404 ERROR_SYSTEM_PARAMETER_NOT_FOUND The clinician/account
identifier could not be
found or
The parameter name
doesn’t exist
10.6.2.1.4 Notes
The list of parameters that can be changed is as follows:
Name Allowed values Comments
TEMPERATURE_MEASUREMENT_SYSTEM • CELSIUS
• FAHRENHEIT
LENGTH_MEASUREMENT_SYSTEM • IMPERIAL
• METRIC
10.6.2.1.5 Example
Request URL /v1/integration/accounts/t1tnMsHwhqmuZLqeIk/parameters/
LENGTH_MEASUREMENT_SYSTEM
Request body {“value”:”IMPERIAL”}
10.6.2.2 View parameter
10.6.2.2.1 Request
GET /v1/integration/accounts/{account identifier}/parameters/{parameter name}
Or
GET /v1/integration/clinicians/{clinician identifier}/parameters/{parameter name}
10.6.2.2.2 Response parameters

value String
Page 61 of 73
Date issued:
05-Dec-20

The parameter name
doesn’t exist
The parameter name
doesn’t exist
404 ERROR_SYSTEM_PARAMETER_NOT_FOUND The clinician/account
identifier could not be
found or
The parameter name
doesn’t exist
10.6.2.2.4 Example
Request URL /v1/integration/accounts/t1tnMsHwhqmuZLqeIk/parameters/
LENGTH_MEASUREMENT_SYSTEM
Response body {“value”:”IMPERIAL”}
Page 62 of 73
Date issued:
05-Dec-20
10.7 Deeplinks
10.7.1 Overview
The deep links API is provided to enable partner applications to launch TytoCare mobile app
without requesting users to login (SSO) and potentially focus on specific patient (and visit).
10.7.2 API List
10.7.2.1 Create deep links
10.7.2.1.1 Request
POST /v1/integration/deepLinks

Name Data Mand Validati Length Comments
type atory on
accountIdentifier String Yes
visitIdentifier String No
flow String No Values can be one of the
following:
EXTERNAL_PATIENT_SETU
P
EXTERNAL_PATIENT_ONLI
NE
EXTERNAL_PATIENT_OFFLI
NE
useTytoDevice Boolean No
10.7.2.1.3 Response
Name Data Comments
type
androidDeepLink String A deep link that can be used to launch tyto app (Android
version)
iosDeepLink String A deep link that can be used to launch tyto app (iOS
version)
Page 63 of 73
Date issued:
05-Dec-20
Http Code Comments

Status
could not be found
404 ERROR_PATIENT_NOT_FOUND The patient identifier
could not be found
404 ERROR_VISIT_DOES_NOT_EXIST The visit identifier could
not be found
409 ERROR_VISIT_RELATED_TO_A_DIFFERENT_PATIENT The visit is associated
with a different patient
409 ERROR_VISIT_RELATED_TO_A_DIFFERENT_ACCOUNT The visit is associated
with a different account
409 ERROR_PATIENT_NOT_DEFINED_FOR_ACCOUNT The patient is not
associated to the
account
409 ERROR_WAS_ALREADY_CANCELLED
409 ERROR_WAS_ALREADY_COMPLETED
Page 64 of 73
Date issued:
05-Dec-20
10.8 Registration codes
10.8.1 Overview
The API enables creating registration codes used in user (accounts) registration process
10.8.2 API List
10.8.2.1 Create codes
10.8.2.1.1 Request
POST /v1/integration/registrationCodes

type
name String No A campaign
named default
will be used
count Integer No The default value
is 1
the location
entity within
Tyto
10.8.2.1.3 Response
The response will include a list (json array) of registration codes
10.9 Utils
10.9.1 Overview
The utils API is provided to enable partner applications access to system resources and
documentation.
10.9.2 API List
10.9.2.1 Get Terms and Conditions URL
10.9.2.1.1 Request
Page 65 of 73
Date issued:
05-Dec-20
GET /v1/integration/utils/documentation/termsAndConditions/url

type ory
languageCode String No See supported
languages list
10.9.2.1.3 Response
The response will include the url itself
Page 66 of 73
Date issued:
05-Dec-20
10.9.2.1 Get Privacy Policy URL
10.9.2.1.1 Request
GET /v1/integration/utils/documentation/privacyPolicy/url

type ory
languages list
10.9.2.1.3 Response
10.9.2.1.4 Supported language

The list of supported language might change from one environment to another.
10.9.2.2 Get Web Address URL

Returns the URL used for web access login
10.9.2.2.1 Request
GET /v1/integration/utils/addresses/webAccess/url
10.9.2.2.2 Response
10.9.2.3 Get Integration terms of use URL

Returns the URL used for the integration terms of use
10.9.2.3.1 Request
GET /v1/integration/utils/ documentation/integrationTermsOfUse/url

type ory
languages list
Page 67 of 73
Date issued:
05-Dec-20
10.9.2.3.3 Response
The response will include the url itself. The document version number is part of its name
10.9.2.3.4 Supported language

The list of supported language might change from one environment to another.
10.9.2.4 Epic data encryption
10.9.2.4.1 Request
POST /v1/integration/utils/epic/encryptData

type ory
data String yes The text to be
encrypted
10.9.2.4.3 Response
Name Data Comments
type
data String The encrypted text
10.9.2.4.1 Notes
Can be used for debugging during epic integration
10.9.2.5.1 Request
POST /v1/integration/utils/epic/decryptData

type ory
data String yes The encrypted
text
Page 68 of 73
Date issued:
05-Dec-20
10.9.2.5.3 Response
Name Data Comments
type
data String The decrypted text
10.9.2.5.4 Notes
10.9.2.6.1 Request
POST /v1/integration/utils/epic/key

type ory
secret String yes The secret used
to generate the
key
keySize Intege No Default is 128
r
10.9.2.6.3 Response
Name Data Comments
type
key String The generated key
10.9.2.6.4 Notes
10.9.2.7 Create full pairing QR
10.9.2.7.1 Request
POST /v1/integration/utils/pairingQRs
Page 69 of 73
Date issued:
05-Dec-20

type
accountIdentifier String No
ssid String No
ssidPassword String No
10.9.2.7.3 Response
Name Data Comments
type
code String The QR code
link String A link to the graphical display of the QR
10.9.2.7.4 Notes
Should be use for debugging purposes only
11. OUTGOING MESSAGES

11.1 Overview
TytoCare server can generate calls to an external server to provide real time information
about specific events. At this point this option is available for the following events:
• Visit creation
• Visit completion
• Visit cancellation
11.2 Security consideration

The calls will be made only to endpoints provided manually to TytoCare integration team. The
endpoints must be running on a secured channel (HTTPS over 443).
The calls will be using Basic authentication. Credentials must be provided manually to the
integration team.
Do note that since TytoCare servers are hosted within AWS, they do not have fixed IP.
Page 70 of 73
Date issued:
05-Dec-20
11.3 General behavior

TytoCare server will submit requests in real time. In case of a timeout, or if the endpoint
returns HTTP status code of 5xx, the TytoCare server will retry sending the message again (up
to 3 times, with some delay). Other HTTP response will mean that the information was
transferred successfully (and it’s up to the partner’s server to decide what to with the
information).
All requests will be sent using POST and assume the endpoint can handle JSON format.
11.4 Endpoints description
11.4.1 Visit details

The following parameters will be included in a standard message
Name Data Mandatory Length Comments
type
visitIdentifier String Yes Internal identifier that can be
later used by the partner APIs
accountIdentifier String No
patientFirstName String Yes
patientLastName String Yes
patientDateOfBirth String Yes
patientSex String Yes
clinicianIdentifier String Yes
clinicianFirstName String No
clinicianLastName String No
isOnline Boolean Yes
identifier String No If provided externally to Tyto
assistingClinicianIden String No
tifier
assistingClinicianFirst String No
Name
assistingClinicianLast String No
Name
stationDescription String No
createdOnDate Date Yes
performedCheckups String No
visitUrl String Yes A link to the TytoCare
application that will display the
Page 71 of 73
Date issued:
05-Dec-20
details of that visit. The Url will

not include sign in information,
so using this Url requires the end
user to login to TytoCare (unless
SSO is activated)
The link for a pending visit and
completed visit might be
different.
For cancelled visits, the link will
not be sent
visitTytoIdentifier String Yes The visit internal identifier
within Tyto
patientTytoIdentifier String Yes The patient internal identifier
within Tyto
Notes Map No The visit notes documented by
the clinician.
Results List No A list of vital signs. Each result
includes the following fields:
• checkupType (can be
BLOOD_PRESSURE,
SP_O2, WEIGHT,
HEART_RATE,
BLOOD_GLUCOSE)
• value
• measurementUnit
• isCalibrated
• isOnline
• performedBy
11.4.2 Sample outbound message (only fields containing values are included)
{
"clinicianFirstName": "John",
"clinicianLastName": "Smith",
"createdOnDate": "2020-07- 06T15:11:44.000+0000",
"isOnline": false,
"locationIdentifier": "Pharmacy",
"patientDateOfBirt h": "1980-01- 01T12:00:00.000+0000",
"patientFirstName": "Jane",
"patientLastName": "Doe",
Page 72 of 73
Date issued:
05-Dec-20
"patientSex": " F",

"patientTytoIdentifier": "1c3017ad9a26470c8dbbe839f3ba318a",
"identifier": "MRN12345 ",
"performedCheckups": "Heart Rate,Skin,Temperature,Throat",
"results": [
{
"checkupType": "Temperature",
"checkupTypeCod e": "TEMPERATURE",
"dateTaken": "2020-07- 06T15:08:44.000+0000",
"isOnline": false,
"measurementUnit": "FAHRENHEIT",
"performedBy": "ACCOUNT",
"preparationEndDate": "2020-07- 06T15:11:11.000+0000",
"preparationStartDate": "2020-07- 06T15:08:26.000+0000",
"value": "97.6"
},
{
"checkupType": "Heart Rate",
"checkupTypeCode": "HEART_RATE",
"dateTaken": "2020-07- 06T15:10:39.000+0000",
"isOnline": false,
"performedBy": "ACCOUNT",
"preparationEndDate": "2020-07-06T15:11:11.000+0000",
"preparationStartDate": "2020-07- 06T15:08:26.000+0000",
"value": "52"
}
],
"status":"COMPLETED",
"visitLink":"https://cloud.tytocare.com/redirect.htm?url=https%3A%2F%2Fcloud.tytocare
.com%2Findex.htm%23%2Fsta rtSingleVisitReview%2FG6dQ3kj1",
"visitTytoIdentifier": "1ce1e70883be43c0a118c4341cdd0 530"
}
Page 73 of 73

TytoCare API

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

TytoCare API

Uploaded by

Copyright:

Available Formats

Date issued:

Rev. Change Description Date

20 Add API for utils/documentation 1-Nov-18

10.1.2 API List ...................................................................................................................................... 19

3. DEFINITIONS & ABBREVIATION

5.2 Tyto Online Examination integration with Telehealth System

5.3 Visit outcomes integration with EHR system

6.2 TytoCare Entities

6.5 Manual data entry

7.1.1 Online integration flow

Server Side Clinician

TytoCare TeleHealth TytoCare Telehealth

Launch (session token, Tyto

7.1.2 Offline review

Server Side Clinician

TytoCare TeleHealth TytoCare Telehealth

Get Tyto Visit (visit id, clinician

Launch (session token, Tyto

Tyto Visit (Clinician and patients details, Visit meta data)

7.1.3 Online integration vs Offline review

7.1.1 TytoCare clinician application dashboard

7.2 Point of care (POC)

7.2.1 Internet access

7.2.2 Joining a visit

Server Side Point of Care

Visit QR Code (webview) (session token, Tyto Visit id)

Join Visit (session token, Tyto Visit id)

Unlike the client-to-server mechanism mentioned before – the server-to-server

As part of the integration, it is possible to receive notifications messages from TytoCare

7.3.2 API Concept

7.3.2.1 URL signatures

7.3.2.2 Request Methods

7.3.2.3 Response status codes

7.3.2.4 Content type (&accept header)

7.3.3 Security considerations

Name URL Purpose Comments

Staging https://app- To be used prior to A stable

7.3.5 Notification messages

8. WEB INTERFACE – DETAILS

8.1 Web View

9. POC INTERFACE – DETAILS

9.1 Internet access

9.2 QR Format – updated version

Parameter Description Value

The format is:

10. SERVER INTERFACE - DETAILS

10.1.2 API List

10.1.2.1 Add Account

10.1.2.1.2 Request parameters

username String No ^[a-zA-Z0-9@\.]*$ 70 If no username is

Http Code Comments

10.1.2.2 Update Account

10.1.2.2.2 Request parameters

10.1.2.3 View account

isPaired Boolean Deprecated – use

isDeviceOnline Booolean Indicates if the

Http Code Comments

10.1.2.4 Add account patient

POST /v1/integration/accounts/{account identifier}/patients

10.1.2.4.2 Request parameters

Http Code Comments

409 ERROR_PATIENT_NAME_ALREADY_EXISTS_FOR_THE_A A patient with the same

404 ERROR_ACOUNT_NOT_FOUND The account identifier

10.1.2.5 Update account patient