TeamViewer

API Documentation

2023-03-001

TeamViewer Germany GmbH • Bahnhofsplatz 2 • D-73033 Göppingen www.teamviewer.com

Table of Contents

1 Changelog 4

2 Introduction 5
2.1 Definitions 5

2.2 REST 5

2.3 IDs 6

2.4 Date format 6

2.5 Number_Format 6

2.6 User Permissions 7

2.7 Rate Limits 9

3 OAuth 2.0 Authorization 10

3.1 Roles & Terms 10

3.2 Registering an application in the Management Console 10

3.3 Client/Application-Types 11

3.4 Access Token Permissions and Scopes 11

3.5 The Authorization Process 12

3.6 User Level Access 12

3.7 Company Level Access 13

3.8 Authorization Endpoint 13

4 API Functions 18

TeamViewer Manual – API Documentation www.teamviewer.com Page 2 of117

4.1 Ping 18

4.2 Event Logging 19

4.3 Account Management 22

4.4 User Management 24

4.5 Group Management 32

4.6 Session Management 40

4.7 Reporting 47

4.8 Meetings 54

4.9 Contacts 64

4.10 Devices 68

4.11 Policy Management 73

4.12 Remote Management Web Monitoring 79

4.13 Remote Management Monitoring Policy Management 87

4.14 Remote Management MonitoringManagement 92

4.15 Remote Management Policy Management 99

4.16 Remote Management Patch Management 103

4.17 Remote Management Endpoint Protection 108

5 Errors 111
5.1 HTTP Response Codes 111

5.2 JSON Error Responses 111

6 Licensing 113

7 Contact 114

8 Appendix 115
8.1 Additional Parameters 115

8.2 URLs for Connections with Devices 116

8.3 URLs for Connections with Contacts 116

TeamViewer Manual – API Documentation www.teamviewer.com Page 3 of 117

 1 Changelog

1 Changelog

2023-03-001:

l Updated permissions parameters in User Management section section 4.4, page 24.

2022-01-001:

l Updated parameters and return values in Remote Management Web Monitoring

section in section 4.12, page 79.
l Added chapter Monitoring Management
l Updated parameters and return values in Remote Management Patch Management
section in section 4.16, page 103.
l Added section "Remote Management Endpoint Protection" section 4.17, page 108.

2021-03-001:

l Updated parameters and return values in Remote Management Monitoring section in

section 4.12, page 79.
l Updated parameters and return values in Remote Management Patch Management
section in section 4.16, page 103.
l Added section "Remote Management Endpoint Protection" section 4.17, page 108.

2021-01-001:

l Added Remote Management Web Monitoring section in section 4.12, page 79.
l Updated link to webapi.teamviewer.com in section 2.2, page 5.
l Updated "Permission names in API and Management Console" table with GetData and
ManageData for Remote Management in section 2.6, page 7.
l Added Remote Management Monitoring section in section 4.13, page 87.
l Added Remote Management Patch Management section in section 4.16, page 103.

TeamViewer Manual – API Documentation www.teamviewer.com Page 4 of 117

 2 Introduction

2 Introduction

2.1 Definitions

Name Description

Supporter A user who provides support to the end customer. This user must have a
TeamViewer account.

End Cus- A user who does not need to have a TeamViewer account. The user is in most
tomer cases a customer of the company who is using the API.

Client The application (or user, if the HTTP requests are typed in manually) that uses
the API.

2.2 REST
The TeamViewer API is a REST API which uses the already existing HTTP methods to create
(POST), read (GET), change (PUT) or delete (DELETE) single items or a collection of items. The
following table shows the general use cases for these HTTP methods.

GET POST PUT DELETE

Collection retrieve list of create new item - -

items in this in this collection
collection

Single item retrieve item data - changes the item deletes this item

The basic URI scheme for all API functions is:

https://host/path/to/resources[/id][/verb][?param1=value1].

The TeamViewer API can be found at https://webapi.teamviewer.com/api/v1/docs/index#.

TeamViewer Manual – API Documentation www.teamviewer.com Page 5 of 117

 2 Introduction

Parameters in the URI are only allowed for GET and DELETE. Generally there should be no
need for any pa-rameters for DELETE, though. POST and PUT need to have the parameters in
the body formatted as JSON or XML.

2.3 IDs
IDs are prefixed with a type in order to make them more distinguishable. The following types
are used:

l "u" - user ID
l "g" – group ID
l "m" – meeting ID
l "s" – session code
l "c" – contact ID
l "d" – device ID
l "r" – remote control ID, also referred to as TeamViewer ID in other documentations

Note: Reports use a GUID and are not prefixed.

2.4 Date format

All dates and times follow the ISO 8601. They should have the following format:
YYYY-MM-DD"T"HH:MM:SS"Z". Times are always in UTC unless stated otherwise.

Example 2013 02 21T13:42:55Z = 21st February 2013, 13:42:55 UTC

2.5 Number_Format
Decimal numbers are returned in US English format, using a point as decimal separator.
Digits are never grouped by a delimiter.

Example 12345.67

TeamViewer Manual – API Documentation www.teamviewer.com Page 6 of 117

 2 Introduction

2.6 User Permissions

2.6.1 Permission names in API and Management Console

The following table shows the relation between user permissions as they can be set in the
Management Console and the technical name that is used for the API.

Name in API Name in Management Console

ManageAdmins Manage administrators and company settings

ManageUsers Manage users

ShareOwnGroups Allow group sharing

ViewAllConnections View all connections

ViewOwnConnections View own connections

EditConnections Edit logged connections

DeleteConnections Delete logged connections

EditFullProfile Allow full profile modification

AllowPasswordChange Allow password change only

ManagePolicies Manage & Assign policies

AssignPolicies Assign policies

AcknowledgeAllAlerts View & acknowledge all alerts

AcknowledgeOwnAlerts View & acknowledge own alerts

ViewAllAssets View all assets

ViewOwnAssets View assets

EditAllCustomModuleConfigs Manage all customizations

EditOwnCustomModuleConfigs Manage own customizations

GetData Allow to get all monitor’s data

TeamViewer Manual – API Documentation www.teamviewer.com Page 7 of 117

 2 Introduction

Name in API Name in Management Console

ManageData Allow to manage monitors

None <no permission is set in console>

2.6.2 Permission dependencies

Some permissions are depending on each other and cannot be set individually, e. g. if a user
has the permis-sion to ManageAdmins he also must have the permission to ManageUsers.
When these permissions are set in the Management Console, the other permissions are set
automatically. When setting permissions through the API using a PUT or POST command, all
permissions must be included explicitly. The following table shows the dependencies.

Name in API To set this right through the API, these rights
also have to be set

None -

ManageAdmins ManageUsers, ShareOwnGroups, EditFullProfile,

ViewAllConnections, ViewOwnConnections, EditCon-
nections, DeleteConnections, ManagePolicies,
AssignPolicies, Acknow-
ledgeAllAlerts,AcknowledgeOwnAlerts, ViewAllAssets,
ViewOwnAssets, EditAllCustomModuleConfigs,
EditOwnCustomModuleConfigs

ManageUsers ShareOwnGroups, EditFullProfile, ViewAllConnections,

ViewOwnConnections, EditConnections, DeleteCon-
nections, ManagePolicies, AssignPolicies, Acknow-
ledgeAllAlerts, AcknowledgeOwnAlerts, ViewAllAssets,
ViewOwnAssets, EditAllCustomModuleConfigs,
EditOwnCustomModuleConfigs

ShareOwnGroups -

ViewAllConnections View own connections

ViewOwnConnections -

EditConnections -

DeleteConnections -

TeamViewer Manual – API Documentation www.teamviewer.com Page 8 of 117

 2 Introduction

Name in API To set this right through the API, these rights
also have to be set

EditFullProfile -

AllowPasswordChange -

ManagePolicies AssignPolicies, AcknowledgeAllAlerts, Acknow-

ledgeOwnAlerts

AssignPolicies AcknowledgeAllAlerts, AcknowledgeOwnAlerts

AcknowledgeAllAlerts AcknowledgeOwnAlerts

AcknowledgeOwnAlerts -

ViewAllAssets ViewOwnAssets

ViewOwnAssets -

EditAllCustomModuleConfigs EditOwnCustomModuleConfigs

EditOwnCustomModuleConfigs -

2.7 Rate Limits

Rate limits apply per API call based on the TeamViewer license.

License Rate limit per API call

Free 300 requests per hour

Business 7,200 requests per 24 hours

Premium 14,400 requests per 24 hours

Corporate 36,000 requests per 24 hours

TeamViewer Manual – API Documentation www.teamviewer.com Page 9 of 117

 3 OAuth 2.0 Authorization

3 OAuth 2.0 Authorization

3.1 Roles & Terms

For more information about OAuth 2.0, see http://oauth.net/2/ and the official specification at
http://tools.ietf.org/html/rfc6749.

Names used by the RFC and their meaning for the TeamViewer API:

l resource owner: The user behind a TeamViewer account who wants to access their
resources through the API.
l resource server: Our servers where the API runs.
l client: The application, plug-in, script or user who is making the API HTTP requests.
l authorization server: In our case that's the same servers that run the rest of the API.
l client ID: A unique ID to identify the application that wants to use the TeamViewer API.
l client secret: A unique string only known to the creator of the client ID.
l authorization code: Code used during the OAuth process to prove that an author-
ization re-quest was granted in the Management Console.
l access token: A token that has to be used to access any API function (except those
explicitly marked as not requiring any access tokens).
l refresh token: A token that can be used once to obtain a new access token and a new
refresh token.

3.2 Registering an application in the Management Con-

sole
Before using any API functionality, you need to register an application in the Management
Console. When you register the application you have to specify if you want to use it for your
own account only (private application, also referred to as “Script”) or if you want to create an
application to be used by any TeamViewer user (public application, also referred to as “App”).
In both cases you also specify if the application will have access to the data of one single
account or to the data of the entire company.

TeamViewer Manual – API Documentation www.teamviewer.com Page 10 of 117

 3 OAuth 2.0 Authorization

3.3 Client/Application-Types

Script App

User Access Access token is created that Client ID is created when creating the
can only be used to access application. The Client ID can be used with
the user who created the OAuth to create an access token for the
application. user granting access.

Company Access Access token is created that Client ID is created when creating the
can be used to access the application. The Client ID can be used with
company of the user OAuth to create an Access-Token to
(=company admin) who cre- access the company of the user
ated the application. (=company admin) granting access.

When you register an application for your own use only, you will get an access token that can
be used di-rectly for any API function that requires it. When you register the application for
others to use as well, you will get a Client ID. This Client ID is used in the OAuth process
described below. At the end of this process the application will also have an access token that
must be used by the other API functions. This access to-ken is tied to the account/company
that uses the application, not the company that created the application.

If you are using OAuth in your application and the application was registered for company
use, the user who grants access to your application needs to be an administrator. The user
who registered the application does not have to be in a company however.

3.4 Access Token Permissions and Scopes

Access tokens can be either issued for a single user or for a whole company. Company access
tokens have to be created by an administrator of that company. Besides this distinction
access tokens also have a number of permissions attached to them. This is called the scope of
the access token.

The following table shows all available scopes:

API function Scopes

Account user level Account.Create, Account.Read, Account.ReadEmail, Accoun-

access only) t.Modify, Account.ModifyEmail, Account.ModifyPassword

Groups Groups.Create, Groups.Read, Groups.Modify, Groups.Share,

Groups.Delete

TeamViewer Manual – API Documentation www.teamviewer.com Page 11 of 117

 3 OAuth 2.0 Authorization

API function Scopes

Users Users.CreateUsers, Users.CreateAdministrators, Users.Read,

Users.ModifyUsers, Users.ModifyAdministrators

Sessions Sessions.Create, Sessions.ReadAll, Sessions.ReadOwn,

Sessions.ModifyAll, Sessions.ModifyOwn

Connections Connections.Read, Connections.Modify, Connections.Delete

Meetings user level Meetings.Create, Meetings.Read, Meetings.Modify, Meet-

access only) ings.Delete

Devices & Contacts ContactList.Create, ContactList.Read, ContactList.Modify,

user level access ContactList.Delete
only)

3.5 The Authorization Process

When using private Script Tokens, there is no need for an authorization process. Access to
the ac-count/company data through the TeamViewer API is defined when creating the token.
The data that is accessed is the account or company data of the user creating the token. Note
that a Script Token is still valid after changing the user’s password.

For public Apps the case is different. Because these applications can be used by other
TeamViewer users, access to their data is controlled via OAuth 2.0. We distinguish between
application with access to user level data and company level data.

3.6 User Level Access

If a user starts an app that requires user level access for the first time, TeamViewer will ask
the user to grant a set of permissions to the app. This set of permissions was specified when
creating the application. The permissions are checked against the rights of the current user.
If the application asks for permissions that exceed the rights of the user (e. g. the application
wants to edit connection report entries whereas the user is only allowed to view them), the
permissions in question are highlighted and a warning is displayed that some parts of the
application may not behave as intended because of the lacking user rights.

In any case, the user may either choose to deny or to grant access to the application. If
access is granted, the app can access the user’s data, as long as the user’s permissions allow.
If user rights are changed later, the application may be able to access more data.

TeamViewer Manual – API Documentation www.teamviewer.com Page 12 of 117

 3 OAuth 2.0 Authorization

3.7 Company Level Access

To grant company level access to an application the user needs to have all required permis-
sions. Unlike user level access it is not possible to grant access when some permissions are
missing.

Also unlike user level access the rights of the user are not relevant for the app any more after
granting access.

3.8 Authorization Endpoint

3.8.1 GET login.teamviewer.com/oauth2/authorize

Requests to the authorization endpoint must be made via HTTPS. The authorization endpoint
is used to interact with the resource owner and therefore must be viewed in a browser. Secur-
ity best practice is to open the authorization endpoint in a popup with address bar visible.

Parameters
l response_type: Must be code.
l client_id: Client ID, a unique string that identifies the application.
l redirect_uri: URI of the redirection endpoint. The client is redirected to this URI once
access has been granted. The value of this parameter must match the registered redir-
ect URI.
l state (optional): Can be set if needed, and will be returned to the callback URI if it was
set here.
l display: Must be popup.

Redirection Endpoint

The client is redirected to the redirection endpoint, which is specified when creating an applic-
ation in Management Console, after the interaction with the authorization endpoint is
completed. Values added to the redirect_uri:

l code: Code that can be used to get an access token.

l state (optional): Same as the one provided as parameter.

Description

Requests an authorization code from the server. This code is only valid for 10 minutes and
should be used to obtain an access token. This is the only function that should not be called

TeamViewer Manual – API Documentation www.teamviewer.com Page 13 of 117

 3 OAuth 2.0 Authorization

directly from a 3rd party application but it should be opened in a browser where the user can
grant access to the 3rd party application.

Example

Request:

GET login.teamviewer.com oauth2/authorize?response_type=code&client_

id=12333-133Ea4Hdf3e9ec0543fX&redirect_uri=https%3A% 2F%2Fcli-
ent%2Eexample%2Ecom%2Fcb

3.8.2 POST /api/v1/oauth2/token (token endpoint)

Parameters

Parameters must be inside the body of the request and encoded with the "application/x-
www-form-urlencoded" format. This is the only exception where the body is not JSON or XML.
There are two different requests for this URI, one to retrieve an access token using an author-
ization code and one using a refresh token.

Authorization-Code Grant:

l grant_type: Must be authorization_code.

l code: Authorization code acquired from the /oauth2/authorize page.
l redirect_uri: Must be the same value as in the previous call to /oauth2/authorize.
l client_id: Client ID, a unique string that identifies the application.
l client_secret: The client secret, which is known only to the creator of the application.

Refresh-Token:

l grant_type: Must be refresh_token.

l refresh_token: Refresh-token from a previous call.
l client_id: Client ID, a unique string that identifies the application.
l client_secret: The client secret, a unique string known only to the creator of the applic-
ation.

Return values
l access_token: Access token to use with all further API calls.
l token_type: Authentication-method used for this access token, currently only bearer is
used.
l expires_in: Time in seconds until the access token expires and needs to be refreshed.

TeamViewer Manual – API Documentation www.teamviewer.com Page 14 of 117

3 OAuth 2.0 Authorization

l refresh_token: Refresh token that needs to be used to get a new access token when
the old access token expires. Requesting a new access token will also create a new
refresh token. The refresh token becomes invalid after use or if the access token is
revoked.

Description

Requests a new access token, either by using the code from a previous authorization step or
by using an existing refresh token. Access tokens have a limited lifetime of 1 day. The
response always has the Cache-Control and Pragma fields (see example below). Refresh
tokens can only be used once. For this request the Content-Type header should be set to
application/x-www-form-urlencoded (as per OAuth 2 specifi-cation), however JSON/XML
also works.

Example

Request (Authorization code grant):

POST /api/v1/oauth2/token HTTP/1.1

Host: webapi.teamviewer.com
Content Type: application/x www form urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSb&redirec t_uri-
i=https%3A%2F%2Ffanyv88.com%3A443%2Fhttps%2Fclient%2Eexample%2Ecom%2Fcb&client_id=12333 133Ea4Hd-
f3e9ec0543fX

Response (Authorization code grant):

HTTP/1.1 200 OK
Content Type: application/json
Cache Control: no store
Pragma: no cache

{"access_token":"54213 2YotnFZFE jr1zCsicMWp",

"token_type":"bearer",
"expires_in":3600,
"refresh_token":"12854 zv3JOkF0XG5Qx2TlKWIA"}

Requests using the access token

All API requests need to include the "Authorization" header if the API function requires an
access token.

TeamViewer Manual – API Documentation www.teamviewer.com Page 15 of 117

 3 OAuth 2.0 Authorization

Example

GET /api/v1/users HTTP/1.1

Host: webapi.teamviewer.com
Authorization: Bearer 54213 2YotnFZFEjr1zCsicMWp

All examples in the following sections will have this header omitted but if an access token is
required the Authorization header field needs to be added to the request.

If no access token is given in the header, or the access token is past its expiration date, the
return will have a WWW-Authenticate header field.

Response for no access token, but access token required:

HTTP/1.1 401 Unauthorized

WWW Authenticate: Bearer

Response for expired access token:

HTTP/1.1 401 Unauthorized

WWW Authenticate: Bearer

{ "error" : "token_expired",
"error_code" : 1,
"error_description" : "The access token expired"

3.8.3 POST /api/v1/oauth2/revoke

Parameters

None

Return values

None

Description

Revokes an access token that was created using oauth. The access token has to be included
in the header Authorization field. After revoking it, it and its attached refresh token cannot be
used any longer.

TeamViewer Manual – API Documentation www.teamviewer.com Page 16 of 117

3 OAuth 2.0 Authorization

Example

Request:

POST /api/v1/oauth2/r evoke HTTP/1.1

Host: https://webapi.teamviewer.com
Authorization: Bearer 54213 2YotnFZFEjr1zCsicMWp

Response:

HTTP/1.1 200 OK

TeamViewer Manual – API Documentation www.teamviewer.com Page 17 of 117

 4 API Functions

4 API Functions

4.1 Ping

4.1.1 GET /api/v1/ping

Parameters

None

Return values
l token_valid: Is set to true if the provided access token is OK and the message is signed
correctly. In all other cases the value is set to false.

Authentication

Access tokens are optional but will be verified if provided. Scope: None required.

Description

This function can be used to check if the API is available. It can also be used to verify if the
token is valid.

Example

Request:

GET /api/v1/ping

Response:

HTTP/1.1 200 OK
Content Type: application/json
{"token_valid":false}

TeamViewer Manual – API Documentation www.teamviewer.com Page 18 of 117

 4 API Functions

4.2 Event Logging

4.2.1 POST /api/v1/EventLogging

Required Parameters
l StartDate (format: "2019-01-01T14:00:00Z"): The start of the requested time range.
l EndDate (format: "2020-01-01T14:00:00Z") : The end of the requested time range.

Note:
l We only provide data from the last 12 months.

l Requesting an invalid time range (e.g., start time after end time) will result in an
error.

Optional Parameters

If the following optional parameters are not given, all information will be returned.

l AffectedItem (string) (optional): Filter for a specified item name.

l EventNames (List<string>) (optional): Filter for specified events (name of the event).
l AccountEmails (List<string>) (optional): Filter for specified account e-mail addresses.
l EventTypes (List<string>) (optional): Filter for specified types.
l RCSessionGuid (UUID) (optional): Filter for a specified session.
l ContinuationToken (byte[]) (optional): Token that needs to be used to get the "next"
50 results.

Possible Events

UserCreated UserDeleted JoinCompany

EditUserProperties EditOwnProfile EditUserPermissions

StartedSession IncomingSession EndedSession

JoinedSession LeftSession ParticipantJoinedSession

ParticipantLeftSession ChangedDisabledRemoteInput ReceivedDisabledLocalInput

ChangedShowBlackScreen ReceivedShowBlackScreen SwitchedSides

StartedRecording EndedRecording PausedRecording

ResumedRecording SentFile ReceivedFile

CreateCustomHost UpdateCustomHost DeleteCustomHost

TeamViewer Manual – API Documentation www.teamviewer.com Page 19 of 117

4 API Functions

PolicyAdded PolicyUpdated PolicyDeleted

ScriptTokenAdded ScriptTokenDeleted ScriptTokenUpdated

GroupAdded GroupUpdated GroupDeleted

GroupShared EmailConfirmed

Possible EventTypes

Session CustomModules Policy

CompanyAdministration GroupManagement UserProfile

Return values
l ContinuationToken:
o Needs to be copied to the next request to get the next result set.
o Is null if it is the last result set.
l AuditEvents: A list of all logged events returned by the filtered criteria:
o EventDetails: A list of all EventDetails
n PropertyName: Name of the changed property.
n PropertyCategory: Category of the changed property.
n OldValue: Value before the change.
n NewValue: Value after the change.
n PolicyEnforcementNewValue: New value for PolicyEnforcements. Applicable
for EventType of Policy.
n PolicyEnforcementOldValue: Old value for PolicyEnforcements. Applicable
for EventType of Policy.
o EventName: Name of the event.
o EventType: Type of the event.
o Timestamp: Time stamp of the event.
o Author: Name of the user who initiated the event.
o AffectedItem: The affected item. The event type Session is represented by its Ses-
sionID.

TeamViewer Manual – API Documentation www.teamviewer.com Page 20 of 117

4 API Functions

Authentication
l User access token scope: Event logging - Allow requesting all event logs.
l A Tensor license is required.

Description

Lists logged Events. If no filters are given it will list all events the active user is able to see
(user access token).
A single request will return a maximum of 50 events (each event can contain multiple
EventDetails). To get the next 50 events repeat the same request with the Continu-
ationToken parameter set to the value from ContinuationToken of the previous request.

Example

Request:

POST /api/v1/EventLogging
Content-Type: application/json
{
"StartDate":"2020-01-01T14:00:00Z",
"EndDate":"2021-01-31T14:00:00Z"
}

TeamViewer Manual – API Documentation www.teamviewer.com Page 21 of 117

 4 API Functions

Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
"ContinuationToken": "someTokenOrNull",
"AuditEvents": [
{
"EventDetails": [
{
"OldValue": "group",
"NewValue": "group-abcdef",
"PolicyEnforcementNewValue": "null",
"PolicyEnforcementOldValue": "null",
"PropertyName": "Name",
"PropertyCategory": "ChangedProperty",

}
],
"EventName": Group updated,
"EventType": "Group management",
"Timestamp": "2020-04-16T09:33:57Z",
"Author": "TestUser",
"AffectedItem": "group-abcdef"
},
......]
}

4.3 Account Management

4.3.1 GET /api/v1/account (retrieve account data)

Parameters

None

Return values
l name: The name of the user.
l email: The associated email address. Only returned if access token has the "Ac-coun-
t.ReadEmail" scope.

TeamViewer Manual – API Documentation www.teamviewer.com Page 22 of 117

 4 API Functions

l userid: The user ID.

l company_name (optional): The name of the company that the user belongs to.
l email_validated (optional): The validation status of the account’s e-mail address. Can
be true or false. Only returned if access token has the “Account.ReadEmail” scope.
l mail_language (optional): The selected e-mail language of the user.

Authentication

User access token. Scope: Account.Read and (optionally) Account.ReadEmail.

Description

Retrieves account information of the account associated with the access token.

Example

Request:

GET /api/v1/account

Response:

HTTP/1.1 200 OK
Content Type: application/json

{
"userid": "u1234567",
"email": "[email protected]",
"name": "John Doe",
"company_name": "John’s Company",
"email_validated": true
}

4.3.2 PUT /api/v1/account (change account data)

Parameters
l name (optional): The name of the user.
l email (optional): The associated email address. Note that changing the email address
needs to be confirmed in the Management Console first before changes take effect.

TeamViewer Manual – API Documentation www.teamviewer.com Page 23 of 117

 4 API Functions

l password (optional): A new password for this account. If password is set, oldpassword
must be set to the correct value of the old password.
l oldpassword (optional): The old password of this account.
l email_language (optional): Allows to set the language of the e-mail based on these val-
ues: auto, da, de, es, fr, it, nl, pt, en, bg, cs, el, fi, hr, hu, id, ja, ko, lt, no, pl, ro, ru, sk, sr,
sv, th, tr, uk, vi, zh_CN, zh_TW.

Return values

None

Authentication

User access token. Scope:Account.Modify, Account.ModifyEmail or Account.ModifyPassword.

Description

Changes account information of the account associated with the access token.

Example

Request:

PUT /api/v1/account
Content Type: application/json

{ "name" : "John Locke" }

Response:

HTTP/1.1 204 No Content

4.4 User Management

Note: License restrictions apply. Please see chapter "Licensing" in section 6, page 113 for
further information.

TeamViewer Manual – API Documentation www.teamviewer.com Page 24 of 117

 4 API Functions

4.4.1 GET /api/v1/users (retrieve list of users)

Parameters
l email (optional): Lists the user that has an exact match of the given email address. This
may also contain a comma separated list of email addresses, allowing to query multiple
users with a single call.
l name (optional): List all users that have the given string as part of their user name.
l permissions (optional): List all users with certain permissions. Multiple permissions can
be separated by comma and only users having all the permissions will be listed in that
case (see section 2.6.1 , page 7 for a list of possible values).
l full_list (optional):
l true: list contains all info fields about the users,
l false (default): list contains only minimal info about the users

Return values

For the minimal list:

l id: user ID, needed to access/modify that user.

l name: name of the user.
l email: E-mail address of the user.

For the full list (additionally):

l permissions (optional): Comma-separated list of permissions that this user has (see
section 2.6.1 , page 7 for a list of possible values).
l active: – true if the account is active, false otherwise.
l custom_quicksupport_id (optional): ID of the default custom QuickSupport module for
this user. Omitted if value is auto.
l custom_quickjoin_id (optional): ID of the default custom QuickJoin module for this
user. Omitted if value is auto.
l last_access_date: Last login date of the user.
l activated_license_id: The user’s activated TeamViewer license ID.
l activated_license_name: The user’s activated TeamViewer license name. For example:
Tensor.
l activated_subLicense_name (optional): Name of the channel group that the user
belongs to.

TeamViewer Manual – API Documentation www.teamviewer.com Page 25 of 117

4 API Functions

Authentication

User or company access token. Scope: Users.Read

Description

Lists all users in a company. The list can be filtered with additional parameters. The function
can also return a list containing all information about the users. This data is the same as
when using GET /users/uID for each of these users.

Example

Request:

GET /api/v1/users?full_list=true

Response (Example 1):

HTTP/1.1 200 OK
Content-Type: application/json

{ "users" : [
{ "id" : "u1234567",
"name" : "Mighty Administrator",
"permissions" : "ManageAdmins, ManageUsers, ShareOwnGroups,
EditFullProfile, ViewAllConnections, ViewOwnConnections, EditCon-
nections, DeleteConnections, ManagePolicies, AssignPolicies, Acknow-
ledgeAllAlerts,AcknowledgeOwnAlerts, ViewAllAssets, ViewOwnAssets,
EditAllCustomModuleConfigs, EditOwnCustomModuleConfigs",
"active": true,
"email": "[email protected]"
},
{ "id" : "u2345678",
"name" : "John Doe",
"permissions" : "EditFullProfile"
"email": "[email protected]"
}]
}

Response (Example 2):

TeamViewer Manual – API Documentation www.teamviewer.com Page 26 of 117

 4 API Functions

{
"users": [
{
"id": "u1234567",
"name": "Test User Name",
"permissions": "EditFullProfile",
"active": true,
"log_sessions": true,
"show_comment_window": true,
"email": "[email protected]",
"last_access_date": "2020-02-07T15:09:42Z",
"activated_license_id": "edcca240-b2fc-4e7c-b41f-90a2dc800a21",
"activated_license_name": "Corporate"
"activated_subLicense_name": "sales group"
},
{
"id": "u2345679",
"name": "Admin Name",
"permissions": "ShareOwnGroups,Man-
ageAdmins,ManageUsers,EditConnections,DeleteConnections,ManagePolicies,
AssignPolicies,Ac-
knowledgeAllAlerts,AcknowledgeOwnAlerts,ViewAllAssets,ViewOwnAssets,
EditAllCus-
tomModuleConfigs,EditOwnCustomModuleConfigs,ManageSettingPolicies,
"active": true,
"log_sessions": true,
"show_comment_window": true,
"email": "[email protected]",
"last_access_date": "2020-02-07T15:09:42Z",
"activated_license_id": "edcca240-b2fc-4e7c-b41f-90a2dc800a21",
"activated_license_name": "Tensor"
},...]
}

4.4.2 POST /api/v1/users (create new company member)

Parameters
l email: E-mail of that user. Will be used for login.
l password: Password for the user. Will be used for login.

TeamViewer Manual – API Documentation www.teamviewer.com Page 27 of 117

4 API Functions

l sso_customer_id (optional): The Customer Identifier that is needed for Single Sign-On.
If the parameter is specified, newly created users are SSO-enabled and do not need a
TeamViewer account password. Using this parameter requires a user access token.
l permissions (optional): Comma-separated list of permissions that this user has (see
section 2.6.1 , page 7 for valid values). If omitted, no permissions are set.
l name: The name of the new user.
l language: Language code for the user. Will be used for the welcome email. Valid lan-
guages are: id, cs, da, de, en, es, fr, hr, it, lt, hu, nl, no, pl, pt, ro, sk, sr, fi, sv, vi, tr,
el, bg, uk, ru, th, ko, zh_TW, zh_CN, ja.
l DEPRECATED: license_key (optional) – License key of the license that will be assigned to
the new user. If omitted, your default license will be set. To assign a license to a user, it
must have been added to the company first.
l custom_quicksupport_id (optional): The ID of the default custom QuickSupport mod-
ule for this user. Defaults to auto if omitted.
l custom_quickjoin_id (optional): The ID of the default custom QuickJoin module for this
user. Defaults to auto if omitted.

Return values

HTTP status code 200 on success and a JSON containing the same data as GET /users/uID.
The new URI for that user will also be returned as part of the HTTP header.

Authentication

User or company access token. Scope: Users.CreateUsers or Users.CreateAdministrators.

Description

Creates a new user for the company. The data for the new user will be returned as response
to the POST. This should be the same as GET /users/uID, except that it will include the id as
well. You will need to have the scope Users.CreateAdministrators to set the permissions
ManageUsers or ManageAdmins.

Example

Request:

TeamViewer Manual – API Documentation www.teamviewer.com Page 28 of 117

 4 API Functions

POST /api/v1/users
Content-Type: application/json

{ "email" : "[email protected]",
"password" : "abc!de#f3g2h3",
"name" : "John Michael Dorian",
"language" : "en",
"permissions" : "EditFullProfile" }

Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
"id" : "u456789",
"name" : "Ted",
"permissions" : "EditFullProfile"
}

4.4.3 GET /api/v1/users/<uID> (get information for one user)

Parameters

None

Return values

This is the same as the full list for GET /users.

l id: User ID. Should be the same as in the URL.

l name: name of the user.
l permissions (optional): String list of permissions that this user has (see section 2.6.1 ,
page 7 for valid values).
l active: true if the account is active, false otherwise.
l custom_quicksupport_id (optional): The ID of the default custom QuickSupport mod-
ule for this user. Omitted if value is auto.
l custom_quickjoin_id (optional): The ID of the default custom QuickJoin module for this
user. Omitted if value is auto.
l email: E-mail address of the user.

TeamViewer Manual – API Documentation www.teamviewer.com Page 29 of 117

 4 API Functions

Authentication

User or company access token. Scope: Users.Read.

Description

Returns the information for a single user.

The information is the same as when using GET /users?full_list=true.

Example

Request:

GET /api/v1/users/u123

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"id" : " u123",
"email" : "[email protected]",
"name" : "John Doe",
"permissions" : "EditFullProfile",
"active" : true
}

4.4.4 PUT /api/v1/users/<uID> (modify user information)

Parameters
l email (optional):New Email of the user. A verification Email will be sent to the new
address.
l name (optional): Real name of the user.
l permissions (optional): Comma-separated list of permissions that this user has (see
section 2.6.2 , page 8 for valid values and combinations).
l password (optional): Assign a new password for this user.
l active (optional): Activates or deactivates an account.

TeamViewer Manual – API Documentation www.teamviewer.com Page 30 of 117

4 API Functions

l DEPRECATED: license_key (optional) – License key of the license that will be assigned to
the new user. If omitted, your default license will be set. To assign a license to a user, it
must have been added to the company first.
l custom_quicksupport_id (optional): The ID of the default custom QuickSupport mod-
ule for this user. Set to auto if no specific module should be assigned.
l custom_quickjoin_id (optional): The ID of the default custom QuickJoin module for this
user. Set to auto if no specific module should be assigned.

Return values

HTTP status code 204 (No Content) on success.

Authentication

User or company access token. Scope: Users.ModifyUsers or Users.ModifyAdministrators.

Description

Changes information for a selected user. Only the parts that need to be changed are needed
in the request body.

Security-Warning: An attacker can gain access to a user account either by changing the email
(+password reset) or by changing the password if he can steal the company access token.
This makes the company access token equivalent to email and password for ALL company
accounts with which an attacker can get the full Computer & Contacts list (and not just what
is available over the API).

Example

Request:

PUT /api/v1/users/u123
Content Type: application/json

{ "name" : "John Locke"}

Response:

HTTP/1.1 204 No Content

TeamViewer Manual – API Documentation www.teamviewer.com Page 31 of 117

 4 API Functions

4.5 Group Management

4.5.1 Accessing groups from different users in a company

Note: If you are using a company access token, you can use all the functions below but
have to prefix them with a user location.
GET /groups for example becomes GET /users/<uID>/groups.

4.5.2 GET /api/v1/groups (list all available groups)

(GET /api/v1/users/<uID>/groups for company access token)

Parameters
l name (optional): Group name or part of the group name.
l shared (optional):
l True: list only shared groups, i. e. groups where the current user is not the owner.
l False: list only not shared groups, i. e. groups owned by the current user. If left
out both types will be in the list.

Return values
l groupd: List of groups.
l id: Group ID
l name: Name of the group.
l shared_with (optional): List of users who this group is shared with. Can be omitted if
empty.
l userid: User ID of the user the group is shared with.
l name: Name of the user the group is shared with.
l permissions: Access-permissions of the user on this group. Either read or read-
write.
l pending: true if the user hasn't accepted the shared group yet, otherwise the
field can be omitted.
l owner (optional): Owner of this group. Omitted if the owner is the current user.
l userid: User ID of the owner of this group.
l name: Name of the owner of this group.
l permissions: read, readwrite, or owned.

TeamViewer Manual – API Documentation www.teamviewer.com Page 32 of 117

 4 API Functions

l policy_id (optional): ID of the policy that is assigned to the group. License restric-
tions apply, please see section 6, page 113 for further information.

Authentication

User or company access token. Scope: Groups.Read.

Description

Returns a list of groups.

Example

Request:

GET /api/v1/groups?name=Test

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{ "groups" : [
{ "id" : "g53235",
"name" : "Testing",
"shared_with" : [
{ "userid" : "u631645",
"name" : "Ted",
"permissions" : "read"}],
"permissions" : "owned"
},
{ "id" : "g425123356",
"name" : "Test",
"owner" : {
"userid" : "u814464403",
"name" : "Tester" },
"permissions" : "readwrite"
}]
}

4.5.3 POST /api/v1/groups (create a new group)

POST /api/v1/users/<uID>/groups for company access token)

TeamViewer Manual – API Documentation www.teamviewer.com Page 33 of 117

4 API Functions

Parameters
l name: Name of the new group.
l policy_id (optional): ID of the policy that will be assigned to the group. Must be a policy
ID.

Return values
l id: Group ID of the newly created group.
l name: Name of the new group. This should be the same parameter as the input para-
meter.
l permissions: Will always be owned, because the group is not yet shared at this point.
l policy_id (optional): ID of the policy that is assigned to the group. License restrictions
apply, please see section 6, page 113 for further information.

Authentication

User or company access token. Scope: Groups.Create.

Description

Creates a new group and returns its info.

Example

Request:

POST /api/v1/groups
Content-Type: application/json

{ "name" : "Test",
"policy_id": "5d93f008-3b1f-8472-8555-3549d5a68092" }

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 34 of 117

 4 API Functions

HTTP/1.1 200 OK
Content-Type: application/json
Location: https://webapi.teamviewer.com/groups/g425123356

{
"id" : "g425123356",
"name" : "Test",
"permissions" : "owned",
"policy_id": "5d93f008-3b1f-8472-8555-3549d5a68092"
}

4.5.4 GET /api/v1/groups/<gID> (get group details)

(GET /api/v1/users/<uID>/groups/<gID> for company access token)

Parameters

None

Return values
l id: Group ID
l name: Name of the group.
l shared_with (optional): List of users who this group is shared with. Only available if the
user is owner of the group. Will be omitted if empty.
l userid: User ID of the owner of this group.
l permissions: Access-permissions of the user on this group. Either read or read-
write.
l owner (optional): Owner of this group. Will be omitted if the owner is the current user.
l userid: User ID of the user the group is shared with.
l name: Name of the owner of this group.
l permissions: Access permissions for the current user. read, readwrite, or owned.
l policy_id (optional): ID of the policy that is assigned to the group. License restrictions
apply, please see section 6, page 113 for further information.

Authentication

User or company access token. Scope: Groups.Read.

TeamViewer Manual – API Documentation www.teamviewer.com Page 35 of 117

 4 API Functions

Description

Returns info for one group.

Example

Request:

GET /api/v1/groups/g425123356

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"id" : "g425123356",
"name" : "Test",
"owner" : {
"userid" : "u814464403",
"name" : "Tester" },
"permissions" : "owned",
"policy_id": "5d93f008-3b1f-8472-8555-3549d5a68092"
}

4.5.5 PUT /api/v1/groups/<gID> (change group details)

(PUT /api/v1/users/<uID>/groups/<gID> for company access token)

Parameters
l name: New name of the group.
l policy_id (optional): ID of the new policy that will be assigned to the group. Must be a
policy ID. License restrictions apply, please see section 6, page 113 for further inform-
ation.

Return values

HTTP status code 204 if change succeeded.

Authentication

User or company access token. Scope: Groups.Modify.

TeamViewer Manual – API Documentation www.teamviewer.com Page 36 of 117

 4 API Functions

Description

Changes a group. Right now only the name can be changed.

Example

Request:

PUT /api/v1/groups/g425123356
Content-Type: application/json

{ "name" : "Test 123",

"policy_id": "5d93f008-3b1f-8472-8555-3549d5a68092" }

Response:

HTTP/1.1 204 No Content

4.5.6 DELETE /api/v1/groups/<gID> (delete a group)

(DELETE /api/v1/users/<uID>/groups/<gID> for company access token)

Parameters

None

Return values

HTTP status code 204 on success.

Authentication

User or company access token. Scope: Groups.Delete

Description

Deletes an existing group. If the group is not owned, but only shared with the user's account
it will just be unshared.

Example

Request:

DELETE /api/v1/groups/g425123356

TeamViewer Manual – API Documentation www.teamviewer.com Page 37 of 117

 4 API Functions

Response:

HTTP/1.1 204 No Content

4.5.7 POST /api/v1/groups/<gID>/share_group (share group with

other user(s))
(POST /api/v1/users/<uID>/groups/<gID>/share_group for company access token)

Parameters
l users: List of users with whom the group will be shared.
l userid: User ID of one of the users you want to share the group with.
l permissions: Access-permissions of the user on this group. Either read or read-
write.

Return values

HTTP status code 204.

Authentication

User or company access token. Scope: Groups.Share.

Description

Shares a group with the given users. Will not change the share state with other users, but it is
possible to overwrite the permissions for existing shares.

Example

Request:

POST /api/v1/groups/g425123356/share_group
Content-Type: application/json

{ "users" : [
{ "userid" : "u33516235",
"permissions" : "read" },
{ "userid" : "u51235",
"permissions" : "readwrite" }]
}

TeamViewer Manual – API Documentation www.teamviewer.com Page 38 of 117

 4 API Functions

Response:

HTTP/1.1 204 No Content

4.5.8 POST /api/v1/groups/<gID>/unshare_group (unshare a group

from certain users)
(POST /api/v1/users/<uID>/groups/<gID>/unshare_group for company access token)

Parameters
l users: List of User IDs that this group should not longer be shared with.

Return values

HTTP status code 204.

Authentication

User or company access token. Scope: Groups.Share.

Description

Unshares a group from certain users.

Example

Request:

POST /api/v1/groups/g425123356/unshare_group
Content-Type: application/json

{ "users" : [ "u33516235", "u51235" ]}

Response:

HTTP/1.1 204 No Content

TeamViewer Manual – API Documentation www.teamviewer.com Page 39 of 117

 4 API Functions

4.6 Session Management

4.6.1 GET /api/v1/sessions (list session codes)

Parameters
l groupid (optional): Filter by group id.
l assigned_userid (optional): Filter by assigned_userid.
l state (optional): State of the session. Can be open or closed. By default only open ses-
sions will be selected. States can be combined with a comma.
l full_list (optional): true: Return all information for the sessions. This is false by default.
l offset (optional): Can contain a session code from a previous request. The returned list
will contain session codes after the one specified as offset.

Return values

For the minimalistic list (full_list=false):

l sessions: List of session codes.

l code: Session code.
l state: State of the session. Can be "open" or "closed".
l online: Online state of the session. Can be true or false.
l groupid: Group ID where this session is stored under.
l support_session_type: Defines the platform that the session code is created for. Can
be "Default" or "Pilot".
l sessions_remaining: Number of session codes left after the ones returned here. Will
be omitted if there are no further session codes.
l next_offset: Offset that can be used to get the next 1,000 session codes.

For the full list (full_list=true):

l waiting_message: Message displayed to the waiting end customer.

l description: Description for this session code.
l end_customer: End Customer info
l name: Name of the end customer.
l email: Email of the end customer.
l assigned_userid: User ID of the user this session is assigned to. If session is unas-
signed, value is "u0".
l assigned_at: Date when the last user was assigned.

TeamViewer Manual – API Documentation www.teamviewer.com Page 40 of 117

4 API Functions

l end_customer_link: Link for the end customer.

l supporter_link: Link for the supporter.
l custom_api: Custom field that can be used to store an arbitrary string but is only avail-
able to API functions. It is limited to 4,000 characters.
l created_at: Date when the session code was created.
l valid_until: Date until when the session code is/was valid.
l closed_at: Date when the session was closed.

Authentication

User or company access token. Scope: Sessions.ReadAll or Sessions.ReadOwn.

Description

Lists sessions. If no filters are given it will list all sessions in the active account (user access
token) or all ses-sions from all accounts (company access token). A single request will return a
maximum of 1000 session codes. To get the next 1000 session codes, repeat the same
request with the offset parameter set to the value from next_offset. Session codes will be
sorted by the created_at date from new to old.

Example

Request:

GET /api/v1/sessions?groupid=g425123356&full_list=true

Response:

{
"sessions" : [
{"code" : "s31 328 542",
"groupid" : "g425123356",
"description" : "Hello, I have an issue with my printer, can you
please assist?",
"end_customer" : { "name" : "Peter Niedhelp", "email" : "help-
[email protected]"
"assigned_userid" : "u7254190",
"end_customer_link" : https://getpilot.teamviewer.com/
"supporter_link" : https://getpilot.teamviewer.com/
"custom_api" : "{ "ticket_id" : "535824"
"support_session_type" : "Pilot"}, ...]
}

TeamViewer Manual – API Documentation www.teamviewer.com Page 41 of 117

 4 API Functions

4.6.2 POST /api/v1/sessions (create new session code)

Parameters
l valid_until (optional): Date when session code becomes invalid. Will default to 24h from
now when no date is given.
l groupid (partially required): ID of the group the session will be inserted into. The group
can be in a different account when the API user has access to it. Either this or group-
name must be set. For applications with company level access, this parameter is
required.
l groupname (partially required): Name of the group the session code will be inserted
into. Either this or the groupid parameter must be set. If no group exists with that
name a new group will be created. If both groupid and groupname are set, both have
to point to the same group. Otherwise an error is returned.
l waiting_message (optional): Message displayed to the waiting end customer.
l description (optional): Description for the new session code.
l end_customer (optional): End customer info.
l name (optional): Name of the end customer. Maximum length is 100 characters.
l email (optional): Email of the end customer. Maximum length is 254 characters.
l assigned_userid (optional): User ID of the user this session code will be assigned to. If
not set, session code will be assigned to the user who created the session code. If set to
"u0", session is unassigned.
l custom_api (optional): Custom field that stores any arbitrary string (such as JSON or
XML) but is only available to API functions. It is limited to 4,000 characters.
l support_session_type (optional): Defines the platform that the session code is created
for. If it is not given, "Default" is set.

Return values
l code: Newly created session code.
l state: State of the session. Can be "open" or "closed".
l groupid: Group ID where this session is stored in.
l waiting_message: Message displayed to the waiting end customer.
l description: Description for this session code.
l end_customer: End Customer info
l name: Name of the end customer.
l email: E-mail of the end customer.

TeamViewer Manual – API Documentation www.teamviewer.com Page 42 of 117

4 API Functions

l assigned_userid: User ID of the user this session code is assigned to. If session code is
not assigned, the value will be "u0".
l assigned_at: Date when the last user last assigned.
l end_customer_link: Link for the end customer.
l supporter_link: Link for the supporter.
l custom_api: Custom field that stores any valid JSON/XML object (max 4,000 characters)
and is only visible for API users.
l created_at: Date when the session code was created.
l valid_until: Date when session code becomes invalid.

Authentication

User or company access token. Scope: Sessions.Create.

Description

Creates a new session code. A session code will always be stored in a group, so either the
groupid or groupname parameter must be set. Session codes will expire after 24h if no
valid_until date is set.

Example

Request (with user/company access token):

{
"groupid" : "g2605812312"
"description" : I have aproblem with myspace bar.",
"end_customer" : { "name" : "Max"},
"support_session_type" : "Pilot"
}

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 43 of 117

 4 API Functions

HTTP/1.1 200 OK
Content-Type: application/json
Location: https://webapi.teamviewer.com/api/v1/sessions/s12-345-678

{"code" : "s12-345-678",
"state" : "open",
"groupid" : "g425123356",
"end_customer" : { "name" : "Max" },
"description" : "I have a problemwith myspace bar.",
"assigned_userid" : "u7254190",
"end_customer_link" : "https://getpilot.teamviewer.com/s12345678",
"supporter_link" : "https://getpilot.teamviewer.com/s12345678-
asfg1234asfg",
"valid_until" : "2013-10-30T12:03:29Z"
}

4.6.3 GET /api/v1/sessions/<code> (get info about a certain session

code)

Parameters

None

Return values
l code: Session code.
l state: State of the session. Can be open or closed.
l online: Online-state of the session. Can be true or false.
l groupid: Group ID where this session is stored in.
l waiting_message: Message displayed to the waiting end customer.
l description: Description for this session code.
l end_customer: End customer info
l name: Name of the end customer. Maximum length is 100 characters.
l email: E-mail of the end customer. Maximum length is 254 characters.
l assigned_userid: User ID of the user this session code is assigned to.
l end_customer_link: Link for the end customer.
l supporter_link: Link for the supporter.

TeamViewer Manual – API Documentation www.teamviewer.com Page 44 of 117

4 API Functions

l custom_api: Custom fields, this stores any arbitrary string but is only available to API
func-tions. It is limited to 4,000 characters.
l valid_until: Date until when the session code is/was valid.
l created_at: Date when the session code was created.
l assigned_at: Date when the last user last assigned.
l closed_at: Date when the session was closed.
l support_session_type: Defines the platform that the session code is created for. Can
be "Default" or "Pilot"

Authentication

User or company access token. Scope: Sessions.ReadAll or Sessions.ReadOwn.

Description

Returns information for one session code. It will return exactly the same data that a POST to
/sessions would return except that some of the fields may have changed values.

Example

Request:

GET /api/v1/sessions/s15-542-091

Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
"code" : "s15-542-091",
"state" : "open",
"groupid" : "g391471283",
"waiting_message" : "",
"description" : "HELP!!11",
"end_customer" : { "name" : "Max", "email" : ""},
"assigned_userid" : "u12948192"
"end_customer_link" : "https://getpilot.teamviewer.com/...",
"supporter_link" : "https://getpilot.teamviewer.com/...",
"support_session_type" : "Default"
}

TeamViewer Manual – API Documentation www.teamviewer.com Page 45 of 117

 4 API Functions

4.6.4 PUT /api/v1/sessions/<code> (modify info for a certain session

code)

Parameters
l groupid(optional): Group ID where this session will be moved to.
l groupname (optional): Group name where this session will be moved to. If both group-
name and groupid are set, the group with the specified ID must have the specified
name. Otherwise an error is returned. This parameter can only be used by applications
with user-level access.
l waiting_message(optional): Message displayed to the waiting end customer.
l description(optional): Description for this session code.
l end_customer(optional): End customer info
l name(optional): Name of the end customer.
l email(optional): E-mail of the end customer.
l assigned_userid(optional): User ID of the user to assign this session to. Set to u0 unas-
sign session.
l custom_api(optional): Custom fields, this stores any arbitrary string but is only avail-
able to API functions. It is limited to 4,000 characters.
l state(optional): State of the session. Can be open or closed.

Return values

HTTP status 204 if changes succeeded.

Authentication

UUser or company access token. Scope: Sessions.ModifyAll or Sessions.ModifyOwn.

Description

CModifies an existing session code.

Example

Request:

PUT /api/v1/sessions/s13-123-123
Content-Type: application/json

{"description" : "Still not working."}

TeamViewer Manual – API Documentation www.teamviewer.com Page 46 of 117

 4 API Functions

Response:

HTTP/1.1 204 No Content

4.7 Reporting

Note: License restrictions apply. Please see chapter "Licensing" in section 6, page 113 for
further information.

4.7.1 GET /api/v1/reports/connections (list connection reports)

Parameters
l username (optional): Filter by user name of the person who started the connection.
l userid (optional): Filter by user ID of the person who started the connection.
l groupid (optional): Filter by group ID where the target device or user was in.
l devicename (optional): Filter by target device name. Set to unnamed_device only
return results for unnamed devices. Only available if you are using a user access token.
l deviceid (optional): Filter by device ID.
l from_date (optional): First start_date for all listed connections. Parameter must con-
tain a date and can also contain a time. If no time is specified it defaults to 00:00:00Z.
Connections with start_date equal to from_date are included in the results.
l to_date (optional): Last start_date for all listed connections. Parameter must contain
a date and can also contain a time. If no time is specified it defaults to 00:00:00Z. Con-
nections with start_date equal to to_date are excluded from the results.
l offset_id (optional): All returned reports will follow the report-ID given in this field. The
given report-ID is excluded from the results.
l has_code (optional): Filters out reports that have no session code if true that have a
ses-sion code if false. If the parameter is left out both types will be returned.

Additional parameters for connections that were done with a session code:

l session_code (optional): specified the response will contain only connections for this
session code.

TeamViewer Manual – API Documentation www.teamviewer.com Page 47 of 117

4 API Functions

Return values
l records: List of remote control connections
l id: Report-ID
l userid: User ID of the person who started the connection.
l username: User name of the person who started the connection.
l contact_id (optional): ID of the target. The Contact ID is returned only for con-
nections made to contacts.
l deviceid: TeamViewer ID of the target device.
l devicename (optional): name of the target device. Only returned if you are using a
user access token.
l groupid: ID of the group where the device is currently located.
l groupname: Name of the group where the device is currently located.
l start_date: Start date and time of the connection.
l end_date: End date and time of the connection.
l fee (optional): Costs for the connection.
l currency (optional): Currency for the fee field.
l billing_state: Can be Bill, Billed, or DoNotBill.
l notes (optional): Notes for this connection.
l records_remaining (optional): Number of records after the ones listed here. Can be
omitted if there are no more reports left.
l next_offset (optional): ID of the last returned report in this response. Can be used as
off-set_id in a follow-up request to get the next set of connection reports.

Additional return parameters when the connection was done with a session code

l records
l assigned_userid: User ID of the user this session code is assigned to.
l assigned_at: Date when the session code was last assigned to another user.
l session_code: Session code.
l session_created_at: Date when the session code was created.
l valid_until: Date until when the session code is/was valid.
l session_note: Description of the Service Case.
l custom_api: Custom fields, this stores any arbitrary string but is only available to API
functions. It is limited to 4,000 characters.
l end_customer

TeamViewer Manual – API Documentation www.teamviewer.com Page 48 of 117

4 API Functions

l name (optional): Name of the end customer.

l email (optional): E-mail address of the end customer.
l feedback: If feedback was enabled but customer did not provide feedback, an
empty object is returned.
l session_rating (optional): Session rating from customer (integer, higher is bet-
ter).
l user_comment (optional): Comment on the session from customer.

Authentication

User or company access token. Scope: Connections.Read.

Description

Returns a list of connection reports. The list is limited to 1,000 reports per request. If there
are more reports the reports_remaining field will tell you how many. The next_offset
field will contain the offset ID to get the next 1000 (or less) reports and should be used as
offset_id parameter for the next request.

If you want to get connections for a single day or multiple days, use the first day at 0:00 for
the from_date parameter and the day after the last day at 0:00 for the to_date parameter.

Example

Request:

GET /api/v1/reports/connections?username=Adam

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 49 of 117

4 API Functions

HTTP/1.1 200 OK
Content-Type: application/json

{"records" : [
{ "id" : "B144268F-5A3A-4130-9054-A8F4598B0125",
"username" : "Adam",
"userid" : "u4387123",
"devicename" : "Server 15",
"deviceid" : "20301234",
"start_date" : "2013-01-16T19:20:30Z",
"end_date" : "20130116T194014Z",
"bill" : "0.00",
"currency" : "EUR",
"billing_state" : "Bill",
"notes" : "fixed webserver"
},
{ "id" : "CAB5E30E-7A51-4F74-A9AE-089EE206D220",
"username" : "Adam",
"userid" : "u4387123",
"devicename" : "Server 12",
"deviceid" : "20301234",
"start_date" : "20130117T144011Z",
"end_date" : "20130117T151324Z",
"bill" : "0.00",
"currency" : "EUR",
"billing_state" : "DoNotBill",
"notes" : "installed Windows updates"
},
{ "id" : "F846B994-4259-4F00-BEC0-258D12A6C0BE",
"username" : "Adam",
"userid" : "u4387123",
"devicename" : "Server 12",
"deviceid" : "20301234",
"start_date" : "20130117T152004Z",
"end_date" : "20130117T152351Z",
"bill" : "0.00",
"currency" : "EUR",
"billing_state" : "DoNotBill",
"notes" : "server rebooted and running again"
}
]}

TeamViewer Manual – API Documentation www.teamviewer.com Page 50 of 117

 4 API Functions

4.7.2 PUT /api/v1/reports/connections/<rID> (change connection

report)

Parameters
l billing_state (optional): Can be Bill, Billed, or DoNotBill.
l notes (optional): Notes for this connection.

Return values

HTTP status code 204.

Authentication

User or company access token. Scope: Connections.Modify.

Description

Changes a field in the connection report.

Example

Request:

PUT /api/v1/reports/connections/F846B994-4259-4F00-BEC0-258D12A6C0BE
Content-Type: application/json

{"notes" : "server rebooted but not fixed yet."}

Response:

HTTP/1.1 204 No Content

4.7.3 DELETE /api/v1/reports/connections/<rID> (delete a con-

nection report)

Parameters

None

Return values

HTTP status code 204.

TeamViewer Manual – API Documentation www.teamviewer.com Page 51 of 117

 4 API Functions

Authentication

User or company access token. Scope: Connections.Delete.

Description

Deletes a connection report.

Example

Request:

DELETE /api/v1/reports/connections/F846B994-4259-4F00-BEC0-258D12A6C0BE

Response:

HTTP/1.1 204 No Content

4.7.4 GET /api/v1/reports/devices (list device reports)

Parameters
l originid(optional): Filter by ID of the device that started the connection.
l userid (optional): Filter by ID of the user that was signed in on the origin device.
l targetid(optional): Filter by ID of the target device.
l from_date(optional): First start_date for all listed connections. Parameter must con-
tain a date and can also contain a time. If no time is specified it defaults to 00:00:00Z.
Connections with start_date equal to from_date are included in the results.
l to_date(optional): Last start_date for all listed connections. Parameter must contain
a date and can also contain a time. If no time is specified it defaults to 00:00:00Z. Con-
nections with start_date equal to to_date are excluded from the results.
l offset_id(optional): All returned reports will follow the report-ID given in this field. The
given report-ID is excluded from the results.

Return values
l records: List of remote control connections
l id: Report-ID
l userid(optional): ID of the user that was signed in on the origin device.
l username (optional): User name of the person who started the connection.

TeamViewer Manual – API Documentation www.teamviewer.com Page 52 of 117

4 API Functions

l originid: TeamViewer ID of the origin device.

l targetid: TeamViewer ID of the target device.
l targetname(optional): Device name of the target device.
l start_date: Start date and time of the connection.
l end_date: End date and time of the connection.
l next_offset(optional): ID of the last returned report in this response. Can be used as
off-set_id in a follow-up request to get the next set of connection reports.

Authentication

User or company access token. Scope: Connections.Read.

Description

Note: License restrictions apply. Please see chapter "Licensing" in section 6, page 113 for
further information.

Returns a list of connection reports. The list is limited to 1,000 reports per request. The next_
offset field will contain the offset ID to get the next 1,000 (or less) reports and should be
used as offset_id parameter for the next request.

If you want to get connections for a single day or multiple days, use the first day at 0:00 for
the from_date parameter and the day after the last day at 0:00 for the to_date parameter.

Example

Request:

GET /api/v1/reports/devices

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 53 of 117

 4 API Functions

HTTP/1.1 200 OK
Content-Type: application/json

{"records" : [
{ "Id": "a6baa54f-e9d1-23ec-bd8f-fc8851923da3",
"originid": 123456789,
"targetid": 234567890,
"targetname": "Desktop",
"start_date": "2016-08-22T12:11:29Z",
"end_date": "2016-08-22T12:11:34Z"
},
{
"Id": "cc1e203f-7a4a-85f8-9fd5-6f23b5d51343",
"originid": 987654321,
"userid": "u13245678",
"targetid": 098765432,
"targetname": "Laptop",
"start_date": "2016-08-22T11:23:04Z",
"end_date": "2016-08-22T11:23:13Z",
"username": "Adam"
},
{
"Id": "ced87ee5-22a7-42cd-8963-90aa45cc55a2",
"originid": 123456789,
"targetid": 321654987,
"targetname": "Server",
"start_date": "2016-08-22T11:20:18Z",
"end_date": "2016-08-22T11:20:34Z"
}
]}

4.8 Meetings

4.8.1 Meeting types

The TeamViewer API handles two types of meetings: scheduled and instant.

Scheduled meetings

Scheduled meetings have a subject, a start and an end time associated with them. They can
be retrieved using the GET /api/v1/meetings method and are displayed in the desktop client.

TeamViewer Manual – API Documentation www.teamviewer.com Page 54 of 117

 4 API Functions

Instant meetings

Instant meetings are meant to be started quickly after creating them. They do not have a
scheduled time or subject. Instant meetings cannot be seen or edited later, the ID and parti-
cipant link only appear in the response of the POST request.

4.8.2 GET /api/v1/meetings (list all scheduled meetings)

Parameters
l from_date (optional): First start date for all listed meetings. Date is included in the fil-
ter. Only the date counts. If a time is provided in the parameter it will be ignored.
l to_date (optional): Last start date for all listed meetings. Date is included in the filter.
Only the date counts. If a time is provided in the parameter it will be ignored.

Return values
l id: The unique meeting ID.
l subject: The subject of the meeting.
l start: The start date and time of the meeting.
l end: The end date and time for the meeting.
l password (optional): The meeting password. Omitted if no password is set.
l conference_call_information: Information about the conference call
l type:ype of the conference call information. Can be either None, TeamViewer, or
Custom.
l custom_data (optional): The custom text that is displayed when type is set to Cus-
tom. Omitted if empty.
l participant_web_link: A web link to join the meeting.

Authentication

User access token. Scope: Meetings.Read.

Description

Lists all scheduled meetings for the account associated with the authentication token. The list
can be filtered with additional parameters. This data is the same as when using GET /meet-
ings/<mID> for each of these users.

Example

Request:

TeamViewer Manual – API Documentation www.teamviewer.com Page 55 of 117

 4 API Functions

GET /api/v1/meetings

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"meetings": [
{
"id": "m12-345-678",
"subject": "TeamViewer API Webinar",
"start": "2013-11-25T14:00:00Z",
"end": "2013-11-25T15:00:00Z",
"password": "1234",
"conference_call_information": {
"type": "Custom",
"custom_data": "Dial 555-4816-2342 to join the conference."
},
"participant_web_link": "https://go.teamviewer.com/m12345678"
},
{
"id": "m98-765-432",
"subject": "API Next Steps",
"start": " 2013-11-25T14:00:00Z",
"end": "2013-11-25T15:00:00Z ",
"conference_call_information": {
"type": "TeamViewer"
},
"participant_web_link": "https://go.teamviewer.com/m98765432"
}
]
}

4.8.3 GET /api/v1/meetings/<mID> (get details of a meeting)

Parameters

None.

TeamViewer Manual – API Documentation www.teamviewer.com Page 56 of 117

4 API Functions

Return values
l id: The unique meeting ID.
l subject: The subject of the meeting.
l start: The start date and time of the meeting.
l end: The end date and time for the meeting.
l password (optional): The meeting password. Omitted if no password is set.
l conference_call_information: Information about the conference call:
l type: Type of the conference call information. Can be either None, TeamViewer, or
Custom.
l custom_data (optional): he custom text that is displayed when type is set to Custom.
Omitted if empty.
l participant_web_link: A web link to join the meeting.

Authentication

User access token. Scope: Meetings.Read.

Description

Retrieve the details of one single meeting.

Example

Request:

GET /api /v1/meetings/m12-345-678

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 57 of 117

 4 API Functions

HTTP/1.1 200 OK
Content-Type: application/json

{
"id": "m12-345-678",
"subject": "TeamViewer API Webinar",
"start": "2013-11-25T14:00:00Z",
"end": "2013-11-25T15:00:00Z",
"password": "1234",
"conference_call_information": {
"type": "Custom",
"custom_data": "Dial 555-4816-2342 to join the conference."
},
"participant_web_link": "https://go.teamviewer.com/m12345678"
}

4.8.4 GET /api/v1/meetings/<mID>/invitation (retrieve invitation

information for a scheduled meeting)

Parameters
l timezone: The time zone for which the invitation is created. Specified as offset to UTC
as defined by ISO 8061. Examples:
l +0100 for the time zone 1 hour east of UTC, e.g. Central European Time (CET)
l +0200 the time zone 2 hours east of UTC, e.g. Central European Summer Time (CEST)
l -0500 for the time zone 5 hours west of UTC, e.g. US/Canadian Eastern Standard
Time (EST).

Example code in C# on how to retrieve the current local time zone:

var utcOffset = TimeZone.CurrentTimeZone.GetUtcOffset(DateTime.Now);

string timezoneParam =
((utcOffset < TimeSpan.Zero) ? "-" : "+") + utcOffset.ToString("hhmm");

l language: The language in which the invitation text is returned, e.g. de or en.

Return values
l invitation_text: An invitation text that can be used for e-mails, chat programs, etc. It
con-tains the meeting ID, a link to directly connect and start and end time given in the
timezone that is stated as parameter. Line breaks are denoted as \n.

TeamViewer Manual – API Documentation www.teamviewer.com Page 58 of 117

 4 API Functions

Authentication

User access token. Scope: Meetings.Read.

Description

Retrieve an invitation text with start and end time adapted to the given time zone.

Example

Request:

GET /api/v1/meetings/m12-345-678/invitation?timezone=+0100&language=en

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{ "invitation_text" : "Hello,\nYou have been invited to a meet-

ing:\n\nSubject: TeamViewer API Webinar\nStart: 15:00, 25.11.2013\nEnd:
16:00, 25.11.2013\n\nPlease join the meeting, by clicking on this
link:\nhttps://go.teamviewer.com/m12345678\nMeeting ID: m12-345-
678\n\nPassword: 1234\n\nRegards,\nJohn Doe\n\nwww.teamviewer.com -
Easy online meeting & screen sharing"}

4.8.5 POST /api/v1/meetings (create a new meeting)

Parameters
l instant (optional): Set true for an instant meeting, false for a scheduled meeting. See
3.7.1 for details about meeting types. Defaults to false.
l subject (optional): Subject of the meeting. Required for scheduled meetings, must be
left empty for instant meetings.
l start (optional): Start date and time. Required for scheduled meetings, must be left
empty for instant meetings.
l end (optional): End date and time. Required for scheduled meetings, must be left
empty for instant meetings.
l password (optional): A password that participants must enter to join the meeting.
l conference_call_information (optional): Information about how to join a conference
for the meeting. Defaults to {"type" : "TeamViewer"} if omitted.

TeamViewer Manual – API Documentation www.teamviewer.com Page 59 of 117

4 API Functions

l type: Type of the conference call information. Can be either None, TeamViewer, or
Custom.
l custom_data (optional): The custom text that is displayed when type is set to Cus-
tom.

Return values
l id: The unique meeting ID.
l subject (optional): Subject of the meeting. Omitted for instant meetings.
l start (optional): The start date and time of the meeting. Omitted for instant meetings.
l end (optional): The end date and time for the meeting. Omitted for instant meetings.
l password (optional): The meeting password. Omitted if no password is set.
l conference_call_information (optional): Information about the conference call:
l type: Type of the conference call information. Can be either None, TeamViewer, or
Custom.
l custom_data (optional): The custom text that is displayed when type is set to Cus-
tom. Omitted if empty.
l participant_web_link: A web link to join the meeting.

Authentication

User access token. Scope: Meetings.Create.

Description

Creates a new meeting. The response contains the values for the new meeting.

Example for a Scheduled Meeting

Request:

TeamViewer Manual – API Documentation www.teamviewer.com Page 60 of 117

4 API Functions

POST /api/v1/meetings
Content-Type: application/json
{
"subject": "TeamViewer API Webinar",
"start": "2013-11-25T14:00:00Z",
"end": "2013-11-25T15:00:00Z",
"password": "1234",
"conference_call_information": {
"type": "Custom",
"custom_data": "Dial 555-4816-2342 to join the conference."
}
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"id": "m12-345-678",
"subject": "TeamViewer API Webinar",
"start": "2013-11-25T14:00:00Z",
"end": "2013-11-25T15:00:00Z",
"password": "123",
"conference_call_information": {
"type": "Custom",
"custom_data": "Dial 555-4816-2342 to join the conference."
},
"participant_web_link": "https://go.teamviewer.com/m12345678"
}

Example for a Scheduled Meeting

Request:

POST /api/v1/meetings
Content-Type: application/json
{
"instant" : "true"
}

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 61 of 117

 4 API Functions

HTTP/1.1HTTP/1.1 200 OK
Content-Type: application/json

{
"id": "m13-345-678",
"participant_web_link": "https://go.teamviewer.com/m13345678"
}

4.8.6 PUT /api/v1/meetings/<mID> (change details of a meeting)

Parameters
l subject (optional): Subject of the meeting.
l start (optional): Start date and time.
l end (optional): End date and time.
l password (optional): A password that participants must enter to join the meeting.
l conference_call_information (optional): Information about how to join a conference
for the meeting.
l type (optional): Type of the conference call information. Can be either None,
TeamViewer, or Custom.
l custom_data (optional): The custom text that is displayed when type is set to Cus-
tom. Omitted if empty.

Return values

HTTP status code 204 (No Content) on success.

Authentication

User access token. Scope: Meetings.Modify.

Description

Changes one or more values of a meeting.

Example

Request:

TeamViewer Manual – API Documentation www.teamviewer.com Page 62 of 117

 4 API Functions

PUT /api/v1/meetings/m12-345-678
Content-Type: application/json

{"subject" : "Webinar: TeamViewer API Best Practices"}

Response:

HTTP/1.1 204 No Content

4.8.7 DELETE /api/v1/meetings/<mID> (delete a meeting)

Parameters

None.

Return values

HTTP status code 204 on success.

Authentication

User access token. Scope: Meetings.Delete.

Description

Deletes a meeting.

Example

Request:

DELETE /api/v1/meetings/m12-345-678

Response:

HTTP/1.1 204 No Content

TeamViewer Manual – API Documentation www.teamviewer.com Page 63 of 117

 4 API Functions

4.9 Contacts

4.9.1 GET /api/v1/contacts (list all contacts from the Computers &
Contacts list)

Parameters
l name (optional): Return only contacts that contain the value of this parameter in their
name.
l email (optional): Return only the contact or invitation that exactly matches the given
email address. This may also contain a comma separated list of email addresses, allow-
ing to query multiple contacts with a single call.
l online_state (optional): Return only contacts with the given online_state.
l groupid (optional): Return only contacts that are in the specified group.
l include_invitations (optional): Additionally returns a list of all pending invitations if
true.

Return values
l contact_id: The ID that is unique for this entry of the Computers & Contacts list. Values
are always prefixed with a ‘c’.
l user_id: the User ID of the contact. Prefixed with a ‘u’.
l name: The name of the contact.
l email (optional): The e-mail address of the contact. This is only returned if the para-
meter email was provided when calling the function.
l groupid: The ID of the group that this contact is a member of.
l description: The description that the current user has entered for this contact.
l online_state: The current online state of the contact. Possible values are: online, busy,
away, offline.
l profilepicture_url (optional): The profile picture of the contact. Contains the URL at
which the profile picture can be found. The URL contains the string “[size]” as place-
holder for the size of the picture, which needs to be replaced by an integer to retrieve
the picture of that size. Valid sizes are 16, 32, 64, 128, and 256. Omitted if a contact has
no profile picture set.
l supported_features: The features supported by the contact. Possible values are: chat,
remote_control, meeting, videocall.
l invitations (optional): List of all pending invitations.

TeamViewer Manual – API Documentation www.teamviewer.com Page 64 of 117

4 API Functions

l groupId: The ID of the group this contact will be a member of.

l email: The e-mail address of the invitee.

Authentication

User access token. Scope: ContactList.Read.

Description

Returns a list of contacts in the user’s Computers & Contacts list that match the criteria given
in the parameters.

The contact_id can also be used to request TeamViewer sessions (such as chat with
contact, send file to contact, prompt remote access, etc.) using the TeamViewer website. For
more information, please see "Appendix A", page 66.

Example

Request:

GET /api/v1/contacts

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{"contacts": [
{ "contact_id": "c123456789",
"user_id": "u987654321",
"name": "Jack",
"groupid": "g12345678",
"online_state": "Offline",
"profilepicture_url": "https://profilepicturedl.teamviewer.com/a-
35489836/81cae6b1-4acf-4138-bd14-f3c27716b400/[size]"
"supported_features": "remote_control, videocall, chat, meeting"
},
{
"contact_id": "c123456780",
"name": "John",
"groupid": "g12345678",
"online_state": "Offline"
}]
}

TeamViewer Manual – API Documentation www.teamviewer.com Page 65 of 117

 4 API Functions

4.9.2 POST /api/v1/contacts (add a new contact)

Parameters
l email: The unique e-mail of the account that is to be added as a contact.
l groupid (partially required): ID of the group the contact will be added to. Either this or
the parameter ‘groupname’ must be set.
l groupname (partially required): Name of the group the contact will be added to. Either
this or the groupid parameter must be set. If no group exists with that name a new
group will be created. If both groupid and groupname are set, both have to point to
the same group. Otherwise an error is returned.
l description (optional): The description of the contact.
l invite (optional): true: Creates an invitation if the contact does not exist.
If invite is true and a request to add a non-existing contact was made an error is
returned stating that the contact could not be added but an invitation was sent. The
invitation will be sent via email.

Return values

On success, the contact is returned with the same values as in GET /contacts.

Authentication

User access token. Scope: ContactList.Write.

Description

Adds a contact to the Computers & Contacts list. An error is returned if either

l the contact is already present in the Computers & Contact list in a group owned by the
current user.
l an account with the specified email does not exist.
l the user does not have sufficient rights to add a contact in the specified group.

Example

Request (with user/company access token):

TeamViewer Manual – API Documentation www.teamviewer.com Page 66 of 117

 4 API Functions

POST /api/v1/contacts
Content-Type: application/json

{
"email": "[email protected]",
"groupid": "g12345678"
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"contact_id": "c123456780",
"name": "John Locke",
"groupid": "g12345678",
"online_state": "Offline"
}

4.9.3 DELETE /api/v1/contacts/<cID> (Delete a contact)

Parameters

None

Return values

HTTP status code 204 on success.

Authentication

User access token. Scope: ContactList.Delete.

Description

Deletes a contact from the Computers & Contacts list. An error is returned if either

l a contact with the given cID does not exist in the current user’s Computers & Contact
list.
l the user does not have sufficient rights to remove the specified contact from a shared
group.

TeamViewer Manual – API Documentation www.teamviewer.com Page 67 of 117

 4 API Functions

Example

Request:

DELETE /api/v1/contacts/c123456789

Response:

HTTP/1.1 204 No Content

4.10 Devices

4.10.1 GET /api/v1/devices (list all devices from the Computers &
Contacts list)

Parameters
l online_state (optional): Return only devices with the given online_state.
l groupid (optional): Return only devices that are in the specified group.
l remotecontrol_id: Return only devices with the specified remotecontrol_id.

Return values

For the full list (full_list=true):

l device_id: The ID that is unique for this entry of the Computers & Contacts list. Values
are always prefixed with a ‘d’.
l remotecontrol_id: ID that is unique to this device and can be used to start a remote
control session.
l groupid: The ID of the group that this device is a member of.
l alias: The alias that the current user has given to this device.
l description: The description that the current user has entered for this device.
l online_state: The current online state of the device. Possible values are: online,
offline.
l supported_features: features supported by the device. Possible values are: chat,
remote_control.
l assigned_to: Indicates whether the device is assigned to the current user. Possible val-
ues are: true, false.

TeamViewer Manual – API Documentation www.teamviewer.com Page 68 of 117

4 API Functions

l policy_id (optional): ID of the policy that is assigned to the device. Possible values are: a
policy_id, inherit. License restrictions apply, see chapter Licensing.
l last_seen (optional): The timestamp of the last time, the device was online. Is not
returned if the device is currently online. Only available if the device is assigned to the
current user.

Authentication

User access token. Scope: ContactList.Read.

Description

Returns a list of devices in the user’s Computers & Contacts list.

The remotecontrol_id can also be used to request TeamViewer sessions (such as chat with
device, send file to device, prompt remote access, etc.) using the TeamViewer website. For
more information, please see “Appendix A”, page 66.

Example

Request:

GET /api/v1/devices

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 69 of 117

 4 API Functions

HTTP/1.1 200 OK
Content-Type: application/json

{ "devices": [
{
"remotecontrol_id": "r123456789",
"device_id": "d123456789",
"alias": "PC",
"groupid": "g12345678",
"online_state": "Online"
"supported_features": "remote_control, chat",
"policy_id": "5d93f008-3b1f-8472-8555-3549d5a68092"
},
{
"remotecontrol_id": "r123456780",
"device_id": "d345667567",
"alias": "Laptop",
"groupid": "g12345678",
"online_state": "Offline"
"supported_features": "remote_control"
},
{
"remotecontrol_id": "r345678890",
"device_id": "d444443226",
"alias": "Office",
"groupid": "g12345678",
"online_state": "Offline"
"assigned_to": true,
"last_seen": "2017-11-28T11:08:31Z"
}
]
}

4.10.2 PUT /api/v1/devices/<dID> (change device details)

Parameters
l alias (optional): A new alias for the device.
l description (optional): A new description for the device.
l password (optional): A password that will be used when connecting to the device.

TeamViewer Manual – API Documentation www.teamviewer.com Page 70 of 117

 4 API Functions

l policy_id (optional): ID of the policy that will be assigned to the device. Possible values
are: a policy_id, inherit, none. License restrictions apply, see chapter Licensing.
l groupid (optional): ID of the group the device will be moved to. May not be used
together with parameter policy_id.

Return values

HTTP status code 204 (No Content) on success.

Authentication

User access token. Scope: ContactList.Modify.

Description

Changes one or more values of a device.

Example

Request:

PUT /api/v1/devices/d12345
Content-Type: application/json

{"description" : "Swan Terminal",

"policy_id": "5d93f008-3b1f-8472-8555-3549d5a68092" }

Response:

HTTP/1.1 204 No Content

4.10.3 POST /api/v1/devices (add a new device)

Parameters
l remotecontrol_id: The TeamViewer ID of the device to be added.
l groupid: The group in which the device is to be added.
l description (optional): The description of the device.
l alias (optional): The alias of the device.
l password (optional): A password that will be used when connecting to the device.

TeamViewer Manual – API Documentation www.teamviewer.com Page 71 of 117

4 API Functions

Return values

On success, the device is returned with the same values as in GET /devices.

Authentication

User access token. Scope: ContactList.Write.

Description

Adds a device to the Computers & Contacts list. An error is returned if either

l the device is already present in the Computers & Contact list in a group owned by the
current user.
l the user does not have sufficient rights to add a device in the specified group.

Example

Request:

POST /api/v1/devices
Content-Type: application/json

{
"remotecontrol_id": “r123456789”,
"groupid": "g12345678",
"password": "4815162342"
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{ "remotecontrol_id": "r123456789",
"device_id": "d999999999",
"alias": "Laptop",
"groupid": "g12345678",
"online_state": "online"
}

TeamViewer Manual – API Documentation www.teamviewer.com Page 72 of 117

 4 API Functions

4.10.4 DELETE /api/v1/devices/<dID> (delete a device)

Parameters

None.

Return values

HTTP status code 204 on success.

Authentication

User access token. Scope: ContactList.Delete.

Description

Deletes a device from the Computers & Contacts list. An error is returned if either

l a device with the given dID does not exist in the current user’s Computers & Contact
list.
l the user does not have sufficient rights to remove the specified contact from a shared
group.

Example

Request:

DELETE /api/v1/devices/d999999999

Response:

HTTP/1.1 204 No Content

4.11 Policy Management

Note: License restrictions apply. Please see chapter "Licensing" in section 6, page 113 for
further information.

4.11.1 GET /api/v1/teamviewerpolicies

Parameters

None.

TeamViewer Manual – API Documentation www.teamviewer.com Page 73 of 117

4 API Functions

Return values
l policies: List of policies.
l settings: List of all settings of a policy.
l key: The label of a setting.
l value: Value of a setting.
l enforce: Enforced settings cannot be set on the device. Possible values are: true,
false.
l name: Name of a policy.
l policy_id: Unique ID of a policy.

Authentication

User access token.

Description

Lists all policies created by the account. Use in combination with

PUT /api/v1/teamviewerpolicies/<policy_id> to modify a policy.

Example

Request:

GET /api/teamviewerpolicies

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 74 of 117

4 API Functions

HTTP/1.1 200 OK
Content-Type: application/json

{ "policies": [
{
"settings": [
{
"Key": "CheckForNewVersion",
"Value": 0,
"Enforce": false
}
],
"name": "One",
"policy_id": "5431b8a2-8b2a-479c-a66a-80c5ce067dc3"
},
{
"settings": [
{
"Key": "EnableBlackScreenOnDisabledInput",
"Value": false,
"Enforce": false
}
],
"name": "Two",
"policy_id": "5d93f008-2b0f-4971-8555-3549d5a68092"
},
{
"settings": [
{
"Key": "DisableTeamViewerShutdown",
"Value": true,
"Enforce": false
}
],
"name": "Three",
"policy_id": "261a9fb5-8f05-4db8-a2a5-2dd7713d12f7"
}
]
}

TeamViewer Manual – API Documentation www.teamviewer.com Page 75 of 117

 4 API Functions

4.11.2 GET /api/v1/teamviewerpolicies/<policy_id>

Parameters

None.

Return values
l policies: List of policies.
l settings: List of all settings of the policy.
l key: The label of a setting.
l value: Value of a setting.
l enforce: Enforced settings cannot be set on the device. Possible values are: true,
false.
l name: Name of the policy.
l policy_id: Unique ID of the policy.

Authentication

User access token.

Description

Returns a specific policy. Use in combination with PUT /api/v1/teamviewerpolicies/<policy_id>

to modify the policy.

Example

Request:

GET /api/teamviewerpolicies/5431b8a2-8b2a-479c-a66a-80c5ce067dc3

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 76 of 117

 4 API Functions

HTTP/1.1 200 OK
Content-Type: application/json

{ "policies": [
{
"settings": [
{
"Key": "CheckForNewVersion",
"Value": 0,
"Enforce": false
}
],
"name": "One",
"policy_id": "5431b8a2-8b2a-479c-a66a-80c5ce067dc3"
}
]
}

4.11.3 PUT /api/v1/teamviewerpolicies/<policy_id>

Parameters
l settings: List of all settings of the policy.
l key: The label of a setting.
l value: Value of a setting.
l enforce: Enforced settings cannot be set on the device. Possible values are: true,
false.
l name: Name of the policy.

Return values

HTTP status code 204 (No Content) on success.

Authentication

User access token.

Description

Modifies the settings of the specified policy. Use in combination with

GET /api/v1/teamviewerpolicies/<policy_id> to retrieve the settings of the policy.

TeamViewer Manual – API Documentation www.teamviewer.com Page 77 of 117

 4 API Functions

Example

Request:

PUT /api/v1/teamviewerpolicies/5431b8a2-8b2a-479c-a66a-80c5ce067dc3
Content-Type: application/json

{
"settings": [
{
"Key": "CheckForNewVersion",
"Value": 1,
"Enforce": false
}
]
}

Response:

HTTP/1.1 204 No Content

4.11.4 DELETE /api/v1/teamviewerpolicies/<policy_id>

Parameters

None.

Return values

HTTP status code 204 (No Content) on success.

Authentication

User access token.

Description

Deletes the specified policy.

Example

Request:

DELETE api/v1/teamviewerpolicies/5431b8a2-8b2a-479c-a66a-80c5ce067dc3

TeamViewer Manual – API Documentation www.teamviewer.com Page 78 of 117

 4 API Functions

Response:

HTTP/1.1 204 No Content

4.12 Remote Management Web Monitoring

Note: License restrictions apply. Please see chapter "Licensing" in section 6, page 113 for
further information.

4.12.1 GET /api/v1/webMonitoring/browsers

Parameters

None.

Return values
l browserId: List of browser IDs.
l type: Browser types (Google Chrome, Mozilla Firefox, etc).
l version: List of supported browser versions (currently null).

Authentication

User access token.

Description

GET browsers action is used to get the list of supported browsers. Currently, we only support
one browser version. Therefore, the API action returns only browser types and ID. The return
of versions will be available soon.

Example

Request:

GET api/v1/webMonitoring/browsers/<accessToken>

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 79 of 117

 4 API Functions

HTTP/1.1 200 OK
Content-Type: application/json

{
"browserId": 1,
"type": "GoogleChrome",
"version": null
},
{
"browserId": 2,
"type": "MozillaFirefox",
"version": null
}

4.12.2 GET /api/v1/webMonitoring/locations

Parameters

None.

Return values
l locationId: List of location Ids.
l continent: List of continents.
l countryCode: List of country codes (de, us, br, etc.).
l city: List of cities.

Authentication

User access token.

Description

GET Locations action is used to get the list of supported locations. It returns location Id,
continent, country, and city names.

Example

Request:

GET api/v1/webMonitoring/locations/<accessToken>

TeamViewer Manual – API Documentation www.teamviewer.com Page 80 of 117

 4 API Functions

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"locationId": 1,
"continent": "Europe",
"countryCode": "de",
"city": "Frankfurt"
},
{
"locationId": 2,
"continent": "Europe",
"countryCode": "gb",
"city": "London"
}

4.12.3 GET /api/v1/webMonitoring/monitors

Parameters

None.

Return values
l monitorId: List of monitor Ids.
l type: List of monitor types (HTTP, HTTPS, ICMP, Full Page Load, and, Transaction).
l name: List of monitor names.
l url: List of monitor URLs.
l port: List of ports.
l timeoutInMs: List of monitor timeout thresholds in milliseconds.
l frequencyInSec: List of monitors' check intervals in seconds.
l method: List of HTTP, HTTPS monitors request methods (GET or POST).
l body: List of POST request methods body texts.
l contentCheckType: List of content match (check for string) types ('should contain' or
'should not contain').
l contentCheckStrings: List of check for strings texts.
l locationId: List of location IDs.

TeamViewer Manual – API Documentation www.teamviewer.com Page 81 of 117

4 API Functions

l notificationsEnabled: The status of notification action. Can be true or false.

l alertingEnabled: The status of alerting action. Can be true or false.
l alertFailureCount: The number of consecutive failures.
l alertLocationCount: The number of locations that consecutive failures occur from.
l scriptName: The name of the transaction script based on which transaction monitor is
running (currentyl supports only transaction monitors).
l browserType: Browser types (Google Chrome, Mozilla Firefox, etc).
l continuationToken: The continuation token that was returned by the previous
request. Needs to be copied to the next request to get the next result set. Is null
if it is the last result set.

Authentication

User access token.

Description

GET all monitors list action is used to get the list of all monitors with configuration details that
are available on the account.

Example

Request:

GET api/v1/webMonitoring/monitors/<accessToken>

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 82 of 117

 4 API Functions

{
"monitorId": "073c6c11-e139-4c20-bcea-5fe72742d8e2",
"type": "Http",
"name": "teamviewer.com",
"url": "teamviewer.com",
"port": 80,
"timeoutInMs": 10000,
"frequencyInSec": 60,
"method": "Get",
"body": null,
"contentCheckType": null,
"contentCheckStrings": null,
"locationIds":
[
3,
4,
5,
10
],
"notificationsEnabled": true,
"alertingEnabled": true,
"alertFailureCount": 1,
"alertLocationCount": 2,
"scriptName": null,
"browserType": "Invalid"
}

4.12.4 GET /api/v1/webMonitoring/monitorsResults

Parameters
l monitorId: Unique ID of the monitor.
l intervalType: The interval type for which results should be obtained. Valid values are:
l LastHour
l Last3Hour
l Last6Hour
l Last12Hour
l Last24Hour
l Last3Day (hourly aggregation)

TeamViewer Manual – API Documentation www.teamviewer.com Page 83 of 117

4 API Functions

l Last7Day (hourly aggregation)

l Last30Day (daily aggregation)
l start: Start date of the day for which results should be obtained.
l end: End date of the day for which results should be obtained.
l continuationToken: The continuation token that was returned by the previous
request. Needs to be copied to the next request to get the next result set. Is
null if it is the last result set.
l start: Start date of the day for which results should be obtained.
l end: End date of the day for which results should be obtained.
l continuationToken: The continuation token that was returned by previous request, if it
is given.

Return values
l locationId: List of location IDs.
l time: The monitor check results time ( YYYY-MM-DD"T"HH:MM:SS"Z").
l responseTimeMs: List of monitor check latncy in ms.
l status: Monitor check results status. Can be success or returns the status based on
errors. Please see the list below.

Status Actual monitor types

Timeout for all type of monitors

ErrorResponseRecieved Uptime - HTTP and HTTPS

Example: "500 Internal Error" or " 403 Forbidden" or "404 Not
found"

ResolveDnsFailed for all type of monitors

InternalError for all type of monitors

UnsupportedBrowser Page load and transaction

UnsupportedScriptType Transaction

UnsupportedCommand Transaction

Interrupted Transaction

StepNotExecuted Transaction

TeamViewer Manual – API Documentation www.teamviewer.com Page 84 of 117

4 API Functions

Status Actual monitor types

ElementNotFound Transaction

Invalid for all type of monitors

ContentCheckFailed Uptime HTTP and HTTPS

InvalidConfig for all type of monitors

Authentication

User access token.

Description

GET monitor results action is used to get the specified monitor results for the specified date
and/or interval.

Example

Request:

GET api/v1/webMonitoring/monitorResults/<accessToken>

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"locationId": 3,
"time": "2020-11-30T15:09:06.071Z",
"status": "Success",
"responseTimeMs": 196
},
{
"locationId": 3,
"time": "2020-11-30T15:09:35.212Z",
"status": "ContentCheckFailed",
"responseTimeMs": 249
}

TeamViewer Manual – API Documentation www.teamviewer.com Page 85 of 117

 4 API Functions

4.12.5 GET /api/v1/webMonitoring/alarms

Parameters
l start: Start date of alarms data getting (ISO 8601 standard - YYYY-MM-
DD"T"HH:MM:SS"Z").
l end: end date of alarms data getting.

Return values
l alertId: Unique ID of the alert.
l monitorId: Unique ID of the monitor.
l failureLocationIds: List of location IDs where failures come from.
l alarmType: Description of the alarm.
l foundAt: Time when the alert started.
l resolvedAt: Time when the alert was resolved.
l acknowledgedAt: Time when the alert was acknowledged.
l acknowledgedBy: Contact ID of the person who acknowledged the alert.
l duration: Duration of the alert.
l responseTimeMs: List of monitor check latency in ms.
l alertStatus: Values are Raised, Resolved, or Acknowledged.

Authentication

User access token.

Description

GET Alarms data action is used to get the alarm's type, monitor IDs, location IDs, status
(Raised, Resolved or Acknowledged), duration, resolving, or being acknowledged time and
contact and, in some cases, the response time for a specified time period.

Example

Request:

GET api/v1/webMonitoring/monitors/alarms

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 86 of 117

 4 API Functions

HTTP/1.1 200 OK
Content-Type: application/json
{
"alertId": "a4774825-1-----------------fc5",
"monitorId": "50fe99a4---------------654c374",
"failureLocationIds": [
3,
4,
10
],
"alarmType": " Timeout",
"foundAt": "2020-12-17T19:42:26.995Z",
"resolvedAt": null,
"acknowledgedAt": null,
"acknowledgedBy": null,
"duration": "0d 14h 15m",
"responseTimeMs": 3049,
"alertStatus": "Raised"
}

4.13 Remote Management Monitoring Policy Management

4.13.1 GET /api/v1/Monitoring/Policy

Parameters

None.

Return values
l policy_id: Unique ID of a policy.
l policy_name: Name of the policy.

Authentication

User access token.

Description

GET Monitoring Policies action is used to get the list of monitoring policies.

TeamViewer Manual – API Documentation www.teamviewer.com Page 87 of 117

 4 API Functions

Example

Request:

GET api/v1/Monitoring/Policy

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"policies": [
{
"policy_id": "261a9fb5-8f05-0000-0000-000000000000",
"policy_name": "Default monitoring policy"
}
]
}

4.13.2 GET /api/v1/Monitoring/Policy/{id}

Parameters

None.

Return values
l policy_id: Unique ID of a policy.
l policy_name: Name of the policy.

Note: Further policy details will follow at a later stage.

Authentication

User access token.

Description

GET Monitoring Policies action is used to get the details of the monitoring policies.

Example

Request:

TeamViewer Manual – API Documentation www.teamviewer.com Page 88 of 117

 4 API Functions

GET api/v1/Monitoring/Policy{id}

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"policies": [
{
"policy_id": "261a9fb5-8f05-0000-0000-000000000000",
"policy_name": " Default monitoring policy"
}
]
}

4.13.3 POST /api/v1/Monitoring/Policy/Assign

Parameters
l teamviewer_id: Unique ID of the device.
l policy_id: Unique ID of a policy.

Return values

On success returns true and gives description, otherwise brings corresponding validation
messages.

Authentication

User access token.

Description

POST Monitoring Policy Assigns action is used for updating assigned monitoring policies.

Example

Request:

GET api/v1/Monitoring/Policy/Assign

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 89 of 117

 4 API Functions

HTTP/1.1 200 OK
Content-Type: application/json

[
{
"teamviewer_id": "0000000",
"success": true,
"description": "string"
}
]

4.13.4 POST /api/v1/Monitoring/devices

Parameters
l teamviewer_id: Unique TeamViewer ID of the device.
l monitoring_policy_id: Unique ID of a policy for monitoring.
l patch_management_policy_id: Unique ID of a policy for monitoring.

Return values

On success returns Activation started for corresponding service, otherwise returns error
that describes the reason for not activating.

Authentication

User access token.

Description

POST Monitoring Activate action is used for activating patch management and monitoring
services on a managed device.

Example

Request:

GET api/v1/Monitoring/Policy/device

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 90 of 117

 4 API Functions

HTTP/1.1 200 OK
Content-Type: application/json

[
{
"teamviewer_id": 38600000,
"monitoring_activation_status": "activationStarted",
"patch_management_activation_status": "activationStarted"
}
]

4.13.5 GET /api/v1/Monitoring

Parameters

None.

Return values
l teamviewer_id: Unique TeamViewer ID of the device.
l alias: The name of the device.

Authentication

User access token.

Description

GET Monitoring active devices action is used to get the service activation information.

Example

Request:

GET api/v1/Monitoring

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 91 of 117

 4 API Functions

HTTP/1.1 200 OK
Content-Type: application/json

{
"devices": [
{
"teamviewer_iD": 00000000",
"alias": "string"
}
]
}

4.14 Remote Management MonitoringManagement

4.14.1 GET /api/v1/monitoring/devices

Parameters

None.

Return values
l teamviewer_id: Unique TeamViewer ID of the device.
l alias: The name of the device.

Authentication

User access token.

Description

GET Monitoring active devices action is used to get the service activation information.

Example

Request:

GET api/v1/monitoring/devices

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 92 of 117

 4 API Functions

HTTP/1.1 200 OK
Content-Type: application/json

{
"devices": [
{
"teamviewer_id": "00000",
"alias": "string"
}
]
}

4.14.2 POST /api/v1/monitoring/devices

Parameters
l teamviewer_id: Unique TeamViewer ID of the device.
l monitoring_policy_id: Unique ID of a policy for monitoring.
l patch_management_policy_id: Unique ID of a policy for monitoring.

Return values

On success returns Activation started for corresponding service, otherwise returns error
that describes the reason for not activating.

Authentication

User access token.

Description

POST /api/v1/monitoring/devices action is used to activate patch management and monit-

oring services action is used for activating the services on a given device.

Example

Request:

POST api/v1/monitoring/devices

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 93 of 117

 4 API Functions

HTTP/1.1 200 OK
Content-Type: application/json

[
{
"teamviewer_id": 38600000,
"monitoring_activation_status": "activationStarted",
"patch_management_activation_status": "activationStarted "
}
]

4.14.3 GET /api/v1/monitoring/devices/{deviceId}/information

Parameters
l deviceId: The same ID as the TeamViewer ID of the target device.

Return values
l teamviewer_id: The unique TeamViewer ID of the device.
l computer_name: The unique name of the computer.
l domain: The name of the domain, e.g WORKGROUP.
l internal_ip: Internal IP address.
l external_ip: External IP address.
l os_name: The name of the operating system.
l os_version: The running version of the operating system.

Authentication

User access token.

Description

GET monitoring device information action is used to get the main information of the system
of the provided device.

Example

Request:

GET /api/v1/monitoring/devices/{deviceId}/information

TeamViewer Manual – API Documentation www.teamviewer.com Page 94 of 117

 4 API Functions

Response:

HTTP/1.1 200 OK
Content-Type: application/json

[
{
"teamviewer_id": 000000000,
"computer_name": "DESKTOP-DDT…",
"domain": "WORKGROUP",
"internal_ip": "10. . .,
"external_ip": "10. . . ",
"os_name": "Microsoft Windows 10 Pro",
"os_version": "10. . . "
}
]

4.14.4 GET /api/v1/monitoring/devices/{deviceId}/hardware

Parameters
l deviceId: The same ID as the TeamViewer ID of the target device.

Implementation Notes

This request will return hardware information of the device, which ID is provided in the
request. type enum values of HardwareItem are:
0 - Not an update
1 - Update
2 - Security update
4 - Motherboard
5 - Keyboard
6 - Pointing device
7 - Monitor
8 - Video controller
9 - Disk drive
11 - Physical memory
13 - Processor

TeamViewer Manual – API Documentation www.teamviewer.com Page 95 of 117

4 API Functions

Return values
l teamviewer_id: The unique TeamViewer ID of the device.
l device_name: The unique name of the computer.
l group_name: The name of the group that contains the device.
l items:
l name: The name of the item.
l type: The type of the item like 5 as Keyboard or 8 as Video controller (see "Imple-
mentation notes" above).
l details: Some details depending on the type.
l manufacturer: The name of the item manufacturer, e.g. Intel Corporation.

Authentication

User access token.

Description

GET monitoring device hardware action is used to get the hardware data of the provided
device.

Example

Request:

GET /api/v1/monitoring/devices/{deviceId}/hardware

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 96 of 117

 4 API Functions

HTTP/1.1 200 OK
Content-Type: application/json

{
"teamviewer_id": 100000000,
"device_name": "DESKTOP-DD…",
"group_name": "My computers",
"items": [
{
"name": "Intel(R) Xeon(R) Gold 6230 CPU @ 2.10GHz",
"type": 13,
"details": "x64, 2.1 GHz, Cores: 2, Logical processors: 2, L2
cache: 0 Bytes, L3 cache: 0 Bytes",
"manufacturer": "GenuineIntel"
},
{
"name": "440BX Desktop Reference Platform",
"type": 4,
"details": "",
"manufacturer": "Intel Corporation"
},
{
"name": "Physical Memory",
"type": 11,
"details": "4 GB",
"manufacturer": ""
}
]
}

4.14.5 GET /api/v1/monitoring/devices/{deviceId}/software

Parameters
l deviceId: The same ID as the TeamViewer ID of the target device.

TeamViewer Manual – API Documentation www.teamviewer.com Page 97 of 117

4 API Functions

Implementation Notes

This request will return hardware information of the device, which ID is provided in the
request. type enum values of HardwareItem are:
0 - Unknown
1 - Network
2 - BIOS
3 - Hotfix

Return values
l teamviewer_id: The unique TeamViewer ID of the device.
l device_name: The unique name of the computer.
l group_name: The name of the group that contains the device.
l items:
l Id: Software item ID number.
l type: The type of the item like 0 as Not an update or 2 as Security update (see
implementation notes above).
l name: The name of the item.
l version: The software version.

Authentication

User access token.

Description

GET monitoring device hardware action is used to get the software data of the provided
device.

Example

Request:

GET /api/v1/monitoring/devices/{deviceId}/software

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 98 of 117

 4 API Functions

HTTP/1.1 200 OK
Content-Type: application/json

{
"teamviewer_id": 100001178,
"device_name": "DESKTOP-DDTTKFJ",
"group_name": "My computers",
"items": [
{
"Id": "5d4d1b9d-4256-4a90-aa98-4e6a48c5e078",
"type": 0,
"name": "Microsoft Windows 10 Pro",
"version": "10.0.19042",
"modified_date": "2021-08-24 13:49:52Z"
},
{
"Id": "ed85f19f-057a-4ee6-bc8d-f576deace78d",
"type": 0,
"name": "Cloudbase-Init 0.9.11",
"version": "0.9.11.0",
"modified_date": "2021-08-06 00:00:00Z"
},
{
"Id": "18617514-b40a-42a5-b352-c057875ffbb3",
"type": 0,
"name": "Microsoft Edge",
"version": "96.0.1054.29",
"modified_date": "2021-11-23 00:00:00Z"
}
]
}

4.15 Remote Management Policy Management

4.15.1 GET /api/v1/PatchManagement/Policy

Parameters

None.

TeamViewer Manual – API Documentation www.teamviewer.com Page 99 of 117

 4 API Functions

Return values
l policy_id: Unique ID of a policy.
l policy_name: Name of the policy.

Authentication

User access token.

Description

GET Patch Management Policies action is used to get the list of patch management policies.

Example

Request:

GET api/v1/PatchManagement/Policy

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"policies": [
{
"policy_id": "261a9fb5-8f05-0000-0000-000000000000",
"policy_name": "Default monitoring policy"
}
]
}

4.15.2 GET /api/v1/PatchManagement/Policy/{id}

Parameters
l policy_id: Unique ID of a policy.

Return values
l policy_id: Unique ID of a policy.
l policy_name: Name of the policy.

TeamViewer Manual – API Documentation www.teamviewer.com Page 100 of 117

 4 API Functions

Note: Further policy details will follow at a later stage.

Authentication

User access token.

Description

GET Patch Management Policies action is used to get the details of the patch management
policy.

Example

Request:

GET api/v1/PatchManagement/Policy{id}

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"policies": [
{
"policy_id": "261a9fb5-8f05-0000-0000-000000000000",
"policy_name": "Default monitoring policy"
}
]
}

4.15.3 POST /api/v1/PatchManagement/Policy/Assign

Parameters
l teamviewer_id: Unique TeamViewer ID of the device.
l patchManagementPolicyId: Unique ID of a policy.

Return values

On success returns true and gives description, otherwise brings corresponding validation
messages.

TeamViewer Manual – API Documentation www.teamviewer.com Page 101 of 117

 4 API Functions

Authentication

User access token.

Description

POST Patch Management Policy Assign action is used for updating assigned patch manage-
ment policies.

Example

Request:

POST api/v1/PatchManagement/Policy/Assign

Response:

HTTP/1.1 200 OK
Content-Type: application/json

[
{
"teamviewer_id": "0000000",
"success": true,
"description": "string"
}
]

4.15.4 GET /api/v1/PatchManagement/devices

Parameters

None.

Return values
l teamviewer_id: Unique TeamViewer ID of the device.
l activation_time: The time of the patch management service activation.

Authentication

User access token.

TeamViewer Manual – API Documentation www.teamviewer.com Page 102 of 117

 4 API Functions

Description

GET Patch Management active devices action is used to get the service activation inform-
ation.

Example

Request:

GET api/v1/patchmanagement/devices

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"devices": [
{
"teamviewer_id": 00000000",
"activationTime": "2020-12-17T19:42:26.995Z"
}
]
}

4.16 Remote Management Patch Management

4.16.1 GET /api/v1/patchmanagement/devices

Parameters
l continuation_token: The continuation token that was returned by previous request (if
given).

Return values
l teamviewer_id:The unique TeamViewer ID of the device.
l activation_time: The time of the patch management service activation.
l continuationToken: The continuation token that was returned by a previous request, if
given.

TeamViewer Manual – API Documentation www.teamviewer.com Page 103 of 117

 4 API Functions

Authentication

User access token.

Description

GET Patch Management active devices action is used to get the service activation inform-
ation.

Example

Request:

GET api/v1/pPatchmManagement/devices

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"devices": [
{
"teamviewer_id": "000000",
"activation-Ttime": {
"underlyingValue": "2021-12-15T07:18:34.680Z"
}
],
"continuation_token": "string"
}

4.16.2 POST /api/v1/patchmanagement/scanresultcounts

Parameters
l device_id_list: The list of device id or just a simple device id.

Return values
l teamviewer_id:The unique TeamViewer ID of the device.
l activation_time: The time of the patch management service activation.
l continuationToken: The continuation token that was returned by a previous request, if
given.

TeamViewer Manual – API Documentation www.teamviewer.com Page 104 of 117

 4 API Functions

Authentication

User access token.

Description

POST Patch Management scan results counts is used to get the devices on which the patches
are missing.

Example

Request:

POST api/v1/patchmanagement/scanresultcounts

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"DeviceMissingPatchesCountInfoList": [
{
"DeviceId": 100001178,
"ErrorCode": 1,
"ScanResultCount": 0
}
],
"ContinuationToken": null
}

4.16.3 GET /api/v1/patchmanagement/devices/{deviceId}/patches/-

missing

Parameters
l deviceId: The same ID as the TeamViewer ID of the target device.

Implementation Notes

This request will return all missing patches of the devices the IDs of which are provided in the
request.
Severity enum values of MissingPatchData are:
0 - Not rated

TeamViewer Manual – API Documentation www.teamviewer.com Page 105 of 117

4 API Functions

1 - Critical
2 - Important
3 - Moderate
4 - Low
tzype enum values of MissingPatchData are:
0 - Unknown
1 - Security patches
2 - Software distribution
3 - Security tools
4 - Non security patches
5 - Custom actions

Return values
l device_id: The unique TeamViewer ID of the device.
l patches:
l patch_id: The unique ID of the patch.
l patch_region_id: The region ID of the patch.
l severity: The enum of the severity like 1 or 3.
l product_name: The name of the product.
l bulletin_name: The name of the patch bulletin.
l bulletin_url: The URL of the patch bulletin.
l bulletin_title: The title of the patch bulletin.
l download_url: The URL of the downloadable file.
l type: enum of the missing patch type like 2 or 5.
l kb:
l cve: The Common Vulnerabilities and Exposures number is a unique identifier.
l release_date: The release date of the patch.
l patch_size: The size of the patch file in bytes.
l patch_details: Some more details about the patch file.
l installable: true or false.
l is_service_pack: true or false.

Authentication

User access token.

TeamViewer Manual – API Documentation www.teamviewer.com Page 106 of 117

4 API Functions

Description

GET Patch Management missing patches action is used to get the list of patches for the given
device.

Example

Request:

GET /api/v1/patchmanagement/devices/{deviceId}/patches/missing

Response:

TeamViewer Manual – API Documentation www.teamviewer.com Page 107 of 117

 4 API Functions

HTTP/1.1 200 OK
Content-Type: application/json

{
"device_id": 1000…..,
"patches": [
{
"patch_id": "00000000-0000-0000-000000000000",
"patch_region_id": 1033,
"severity": 1,
"product_name": "Windows 10 Pro (x64)",
"bulletin_name": "MS21-11-…",
"bulletin_url": "http://support.microsoft.......",
"bulletin_title": "Security Cumulative …..",
"download_url": "http://-
download.windowsupdate.com/c/msdownload/.........",
"type": 1,
"kb": "Q5007186",
"cve": [
"CVE-2021-26443",
"CVE-2021-36957",
"CVE-2021-38631",
"CVE-2021-38665",
"CVE-2021-38666",
"CVE-2021-41351",
"CVE-2021-41356",
],
"release_date": "2021-11-09
"patch_size": 674489601,
"patch_details": "Please se
details.",
"installable": true,
"is_service_pack": false
}
]
}

4.17 Remote Management Endpoint Protection

TeamViewer Manual – API Documentation www.teamviewer.com Page 108 of 117

 4 API Functions

4.17.1 POST /api/v1/endpointprotection/install

Parameters
l teamviewer_id: Unique TeamViewer ID of the device.
l policy: Unique ID of a policy.

Return values

HTTP status code.

Authentication

User access token.

Description

POST Install TVRM Endpoint Protection on a given device when it is online and assigned.

Example

Request:

POST api/v1/endpointprotection/install

Response:

HTTP/1.1 200 OK
Content-Type: application/json

4.17.2 GET /api/v1/endpointprotection/devices

Parameters

None.

Return values
l teamviewer_id: The unique TeamViewer ID of the device.
l alias: Device description.

Note: Further policy details will follow at a later stage.

TeamViewer Manual – API Documentation www.teamviewer.com Page 109 of 117

4 API Functions

Authentication

User access token.

Description

GET devices on which endpoint protection is activated.

Example

Request:

GET api/v1/endpointprotection/devices

Response:

HTTP/1.1 200 OK
Content-Type: application/json

[
{
"teamviewer_id":0,
"alias":"string"
}
]

TeamViewer Manual – API Documentation www.teamviewer.com Page 110 of 117

 5 Errors

5 Errors

5.1 HTTP Response Codes

Name Description

200 OK: Used for successful GET, POST and DELETE.

204 No Content: Used for PUT to indicate that the update succeeded, but no content is
included in the response.

400 Bad Request: One or more parameters for this function is either missing, invalid or
unknown. Details should be included in the returned JSON.

401 Unauthorized: Access token not valid (expired, revoked, …) or not included in the
header.

403 Forbidden / Rate Limit Reached: IP blocked or rate limit reached.

500 Internal Server Error: Some (unexpected) error on the server. The same request
should work if the server works as intended.

5.2 JSON Error Responses

If there is an error while processing a request, the API server returns a 4xx/5xx HTTP status
code with a JSON in the body with the following parameters:

l error: A short string describing the category of error.

l error_description: A longer string containing a human readable error message.
l error_code: A number that is unique for each type of error.
l error_signature (optional): A number that we can use to find the log entry if there is
one. This should be unique for every time an error happens. The parameter may be
omitted if there was nothing logged.

Valid values for the error field are:

TeamViewer Manual – API Documentation www.teamviewer.com Page 111 of 117

5 Errors

l invalid_request: The request is missing a required parameter, includes an unsup-

ported parameter or parameter value, repeats the same parameter, uses more than
one method for including an access token, or is otherwise malformed. Should be used
with HTTP response code 400.
l invalid_token: The access token provided is revoked, malformed, or invalid. Should be
used with HTTP response code 401 (Unauthorized).
l internal_error: There was an error while processing the request. The error was caused
by an error on our servers that should not happen and can indicate some problems at
our end. Error code and signature can be used to debug the error. Should be used with
HTTP status code 500 (Internal Server Error).
l blocked: The request was blocked. That should only happen when the IP was blocked.
l rate_limit_reached: Too many calls to a single function with the same access token.
l token_expired: Access token is expired. A new access token needs to be requested.
l invalid_client: Client ID was invalid.
l email_in_use: Returned during account creation or when changing the email if the e-
mail is already used by another account.

Note: invalid_request and invalid_token are taken from http://self-issued.in-

fo/docs/draft-ietf-oauth-v2-bearer.html#resource-error-codes (with the exception that they
are not included in the WWW-Authenticate header field but the returned JSON).

TeamViewer Manual – API Documentation www.teamviewer.com Page 112 of 117

 6 Licensing

6 Licensing

Certain API functions require a TeamViewer license to use them. These functions are:

l Connection reporting and user management: TeamViewer 9 or above, Premium or Cor-

porate
l Functions with company level access: TeamViewer 9 or above, Premium or Corporate
l Contacts and Devices: TeamViewer 10
l Device reporting: TeamViewer 12 or above, Corporate
l Policy Management: TeamViewer 12 or above, Premium or Corporate

All other functions are available with any license and free for private use.

Without a valid license, it is not possible to create private Script Tokens or grant access to
public Apps that require any of the aforementioned functions.

To purchase or update your current license, visit http://www.teamviewer.com/licensing.

TeamViewer Manual – API Documentation www.teamviewer.com Page 113 of 117

 7 Contact

7 Contact

If you have questions or feedback, please visit https://www.teamviewer.com/ticket.

TeamViewer Manual – API Documentation www.teamviewer.com Page 114 of 117

 8 Appendix

8 Appendix

8.1 Additional Parameters

Via the URL https://start.teamviewer.com and additional parameters, it is possible to request
connections or call up TeamViewer features. Because the features are called up via a
browser, you can use this method from any application or operating system.

In conjunction with the TeamViewer web API, this will offer easy integration of TeamViewer
features into your own application environment.

l To use device related parameters, the remotecontrol_id of the device is needed.

How to get the remotecontrol_id using the API is described under section 4.10,
page 68.
l To use contact related parameters, the contact_id of the contact is needed. How to
get the contact_id using the API is described under section 4.9, page 64.

Please find a list of the available parameters below.

Parameter Values Default

device <remotecontrol_id> -

contact <contact_id> -

mode control, present, videocall, control

filetransfer, sendfile, vpn,
chat

authorization prompt, password password (if mode does not sup-

port a password, prompt is
default)

As a result, the following URLs can be called up for devices or contacts.

TeamViewer Manual – API Documentation www.teamviewer.com Page 115 of 117

 8 Appendix

8.2 URLs for Connections with Devices

URL Request

start.teamviewer.com/<remotecontrol_id> Remote control

(using password)

start.teamviewer.com/device/<remotecontrol_id>/au- File transfer (using

thorization/password/mode/filetransfer password)

start.teamviewer.com/device/<remotecontrol_id>/au- Remote control

thorization/password/mode/control (using password)

start.teamviewer.com/device/<remotecontrol_id>/au- VPN (using pass-

thorization/password/mode/vpn word)

start.teamviewer.com/device/<remotecontrol_id>/- Chat
mode/chat

8.3 URLs for Connections with Contacts

URL Request

start.teamviewer.com/contact/<contact_id>/au- Remote control (using

thorization/password/mode/control password)

start.teamviewer.com/contact/<contact_id>/au- File transfer (using pass-

thorization/password/mode/filetransfer word)

start.teamviewer.com/contact/<contact_id>/au- VPN (using password)

thorization/password/mode/vpn

start.teamviewer.com/contact/<contact_id>/au- Presentation (prompt

thorization/prompt/mode/present for confirmation)

start.teamviewer.com/contact/<contact_id>/au- Remote control (prompt

thorization/prompt/mode/control for confirmation)

start.teamviewer.com/contact/<contact_id>/au- Video Call (prompt for

thorization/prompt/mode/videocall confirmation)

start.teamviewer.com/contact/<contact_id>/au- Send file (prompt for

thorization/prompt/mode/sendfile confirmation)

TeamViewer Manual – API Documentation www.teamviewer.com Page 116 of 117

8 Appendix

URL Request

start.teamviewer.com/contact/<contact_id>/- Chat
mode/chat

Note: Connections and chat to contacts require both sides to be logged into their
TeamViewer account.

TeamViewer Manual – API Documentation www.teamviewer.com Page 117 of 117