TeamViewer

API
Documentation

Version 1.3.6

TeamViewer GmbH Jahnstr. 30 D-73037 Gppingen

www.teamviewer.com

Table of Contents

Introduction ............................................................................................... 9

1.1

Definitions .................................................................................................................... 9

1.2

REST ............................................................................................................................. 9

1.3

IDs .............................................................................................................................. 10

1.4

Date format ................................................................................................................ 10

1.5

Number format ........................................................................................................... 10

User permissions ...................................................................................... 11

2.1

Permission names in API and Management Console .................................................... 11

2.2

Permission dependencies ............................................................................................ 12

API Functions............................................................................................ 14

3.1

Authentication (OAuth 2.0) ......................................................................................... 14

3.1.1 Registering an application in the Management Console ...................................................................... 14
Client/Application-Types .............................................................................................................................. 15
3.1.2 Access Token Permissions and Scopes ................................................................................................. 15
3.1.3 The authorization process .................................................................................................................... 16
3.1.3.1 User level access ................................................................................................................................... 16
3.1.3.2 Company level access ........................................................................................................................... 16
3.1.4 GET /api/v1/oauth2/authorize (authorization endpoint) .................................................................... 16
Parameters ................................................................................................................................................... 16
Return values ................................................................................................................................................ 17
Description ................................................................................................................................................... 17
Example ........................................................................................................................................................ 17
3.1.5 POST /api/v1/oauth2/token (token endpoint) ..................................................................................... 17
Parameters ................................................................................................................................................... 17
Return values ................................................................................................................................................ 18
Description ................................................................................................................................................... 18
Example ........................................................................................................................................................ 18
Requests using the access token .................................................................................................................. 18

TeamViewer API - Documentation

www.teamviewer.com

Page 2 of 60

Example ........................................................................................................................................................ 18
3.1.6 POST /api/v1/oauth2/revoke ............................................................................................................... 19
Parameters ................................................................................................................................................... 19
Return values ................................................................................................................................................ 19
Description ................................................................................................................................................... 19
Example ........................................................................................................................................................ 19

3.2

Ping ............................................................................................................................ 19
3.2.1 GET /api/v1/ping .................................................................................................................................. 19
Parameters ................................................................................................................................................... 19
Return values ................................................................................................................................................ 19
Authentication .............................................................................................................................................. 20
Description ................................................................................................................................................... 20
Example ........................................................................................................................................................ 20

3.3

Account Management ................................................................................................. 20

3.3.1 GET /api/v1/account (retrieve account data) ....................................................................................... 20
Parameters ................................................................................................................................................... 20
Return values ................................................................................................................................................ 20
Authentication .............................................................................................................................................. 20
Description ................................................................................................................................................... 20
Example ........................................................................................................................................................ 20
3.3.2 PUT /api/v1/account (change account data) ........................................................................................ 21
Parameters ................................................................................................................................................... 21
Return values ................................................................................................................................................ 21
Authentication .............................................................................................................................................. 21
Description ................................................................................................................................................... 21
Example ........................................................................................................................................................ 21

3.4

User Management ...................................................................................................... 22

3.4.1 GET /api/v1/users (retrieve list of users).............................................................................................. 22
Parameters ................................................................................................................................................... 22
Return values ................................................................................................................................................ 22
Authentication .............................................................................................................................................. 22
Description ................................................................................................................................................... 22
Example ........................................................................................................................................................ 22
3.4.2 POST /api/v1/users (create new company member) ........................................................................... 23
Parameters ................................................................................................................................................... 23
Return values ................................................................................................................................................ 23
Authentication .............................................................................................................................................. 23
Description ................................................................................................................................................... 23
Example ........................................................................................................................................................ 24
3.4.3 GET /api/v1/users/<uID> (get information for one user) ..................................................................... 24
Parameters ................................................................................................................................................... 24
Return values ................................................................................................................................................ 24
Authentication .............................................................................................................................................. 24
Description ................................................................................................................................................... 24

TeamViewer API - Documentation

www.teamviewer.com

Page 3 of 60

Example ........................................................................................................................................................ 24
3.4.4 PUT /api/v1/users/<uID> (modify user information) ........................................................................... 25
Parameters ................................................................................................................................................... 25
Return values ................................................................................................................................................ 25
Authentication .............................................................................................................................................. 25
Description ................................................................................................................................................... 25
Example ........................................................................................................................................................ 26

3.5

Group Management .................................................................................................... 26

3.5.1 Accessing groups from different users in a company ........................................................................... 26
3.5.2 GET /api/v1/groups (list all available groups) ...................................................................................... 26
Parameters ................................................................................................................................................... 26
Return values ................................................................................................................................................ 26
Authentication .............................................................................................................................................. 27
Description ................................................................................................................................................... 27
Example ........................................................................................................................................................ 27
3.5.3 POST /api/v1/groups (create a new group) .......................................................................................... 27
Parameters ................................................................................................................................................... 27
Return values ................................................................................................................................................ 27
Authentication .............................................................................................................................................. 27
Description ................................................................................................................................................... 27
Example ........................................................................................................................................................ 28
3.5.4 GET /api/v1/groups/<gID> (get group details) ..................................................................................... 28
Parameters ................................................................................................................................................... 28
Return values ................................................................................................................................................ 28
Authentication .............................................................................................................................................. 28
Description ................................................................................................................................................... 28
Example ........................................................................................................................................................ 28
3.5.5 PUT /api/v1/groups/<gID> (change group details) .............................................................................. 29
Parameters ................................................................................................................................................... 29
Return values ................................................................................................................................................ 29
Authentication .............................................................................................................................................. 29
Description ................................................................................................................................................... 29
Example ........................................................................................................................................................ 29
3.5.6 DELETE /api/v1/groups/<gID> (delete a group) ................................................................................... 29
Parameters ................................................................................................................................................... 29
Return values ................................................................................................................................................ 29
Authentication .............................................................................................................................................. 30
Description ................................................................................................................................................... 30
Example ........................................................................................................................................................ 30
3.5.7 POST /api/v1/groups/<gID>/share_group (share group with other user(s)) ....................................... 30
Parameters ................................................................................................................................................... 30
Return values ................................................................................................................................................ 30
Authentication .............................................................................................................................................. 30
Description ................................................................................................................................................... 30
Example ........................................................................................................................................................ 30

TeamViewer API - Documentation

www.teamviewer.com

Page 4 of 60

3.5.8 POST /api/v1/groups/<gID>/unshare_group (unshare a group from certain users) ........................... 31

Parameters ................................................................................................................................................... 31
Return values ................................................................................................................................................ 31
Authentication .............................................................................................................................................. 31
Description ................................................................................................................................................... 31
Example ........................................................................................................................................................ 31

3.6

Session Management .................................................................................................. 31

3.6.1 GET /api/v1/sessions (list session codes) ............................................................................................. 31
Parameters ................................................................................................................................................... 31
Return values ................................................................................................................................................ 31
Authentication .............................................................................................................................................. 32
Description ................................................................................................................................................... 32
Example ........................................................................................................................................................ 32
3.6.2 POST /api/v1/sessions (create new session code) ............................................................................... 33
Parameters ................................................................................................................................................... 33
Return values ................................................................................................................................................ 33
Authentication .............................................................................................................................................. 34
Description ................................................................................................................................................... 34
Example ........................................................................................................................................................ 34
3.6.3 GET /api/v1/sessions/<code> (get info about a certain session code) ................................................ 34
Parameters ................................................................................................................................................... 34
Return values ................................................................................................................................................ 34
Authentication .............................................................................................................................................. 35
Description ................................................................................................................................................... 35
Example ........................................................................................................................................................ 35
3.6.4 PUT /api/v1/sessions/<code> (modify info for a certain session code) ............................................... 35
Parameters ................................................................................................................................................... 35
Return values ................................................................................................................................................ 36
Authentication .............................................................................................................................................. 36
Description ................................................................................................................................................... 36
Example ........................................................................................................................................................ 36

3.7

Connection Reporting ................................................................................................. 36

3.7.1 GET /api/v1/reports/connections (list connection reports) ................................................................. 36
Parameters ................................................................................................................................................... 36
Return values ................................................................................................................................................ 37
Authentication .............................................................................................................................................. 38
Description ................................................................................................................................................... 38
Example ........................................................................................................................................................ 38
3.7.2 PUT /api/v1/reports/connections/<rID> (change connection report) ................................................. 39
Parameters ................................................................................................................................................... 39
Return values ................................................................................................................................................ 39
Authentication .............................................................................................................................................. 39
Description ................................................................................................................................................... 39
Example ........................................................................................................................................................ 40

TeamViewer API - Documentation

www.teamviewer.com

Page 5 of 60

3.7.3 DELETE /api/v1/reports/connections/<rID> (delete a connection report) .......................................... 40

Parameters ................................................................................................................................................... 40
Return values ................................................................................................................................................ 40
Authentication .............................................................................................................................................. 40
Description ................................................................................................................................................... 40
Example ........................................................................................................................................................ 40

3.8

Meetings..................................................................................................................... 40
3.8.1 Meeting types ....................................................................................................................................... 40
3.8.1.1 Scheduled meetings ............................................................................................................................. 40
3.8.1.2 Instant meetings ................................................................................................................................... 41
3.8.2 GET /api/v1/meetings (list all scheduled meetings) ............................................................................. 41
Parameters ................................................................................................................................................... 41
Return values ................................................................................................................................................ 41
Authentication .............................................................................................................................................. 41
Description ................................................................................................................................................... 41
Example ........................................................................................................................................................ 41
3.8.3 GET /api/v1/meetings/<mID> (get details of a meeting) ..................................................................... 42
Parameters ................................................................................................................................................... 42
Return values ................................................................................................................................................ 42
Authentication .............................................................................................................................................. 42
Description ................................................................................................................................................... 43
Example ........................................................................................................................................................ 43
3.8.4 GET /api/v1/meetings/<mID>/invitation (retrieve invitation information for a scheduled meeting) . 43
Parameters ................................................................................................................................................... 43
Return values ................................................................................................................................................ 44
Authentication .............................................................................................................................................. 44
Description ................................................................................................................................................... 44
Example ........................................................................................................................................................ 44
3.8.5 POST /api/v1/meetings (create a new meeting) .................................................................................. 44
Parameters ................................................................................................................................................... 44
Return values ................................................................................................................................................ 45
Authentication .............................................................................................................................................. 45
Description ................................................................................................................................................... 45
Example for a scheduled meeting ................................................................................................................ 45
Example for an instant meeting ................................................................................................................... 46
3.8.6 PUT /api/v1/meetings/<mID> (change details of a meeting) ............................................................... 46
Parameters ................................................................................................................................................... 46
Return values ................................................................................................................................................ 46
Authentication .............................................................................................................................................. 46
Description ................................................................................................................................................... 46
Example ........................................................................................................................................................ 47
3.8.7 DELETE /api/v1/meetings/<mID> (delete a meeting) .......................................................................... 47
Parameters ................................................................................................................................................... 47
Return values ................................................................................................................................................ 47
Authentication .............................................................................................................................................. 47

TeamViewer API - Documentation

www.teamviewer.com

Page 6 of 60

Description ................................................................................................................................................... 47
Example ........................................................................................................................................................ 47

3.9

Contacts...................................................................................................................... 47
3.9.1 GET /api/v1/contacts (list all contacts from the computers & contacts list) ....................................... 47
Parameters ................................................................................................................................................... 47
Return values ................................................................................................................................................ 48
Authentication .............................................................................................................................................. 48
Description ................................................................................................................................................... 48
Example ........................................................................................................................................................ 49
3.9.2 POST /api/v1/contacts (add a new contact) ......................................................................................... 49
Parameters ................................................................................................................................................... 49
Return values ................................................................................................................................................ 49
Authentication .............................................................................................................................................. 49
Description ................................................................................................................................................... 49
Example ........................................................................................................................................................ 50
3.9.3 DELETE /api/v1/contacts/<cID> (Delete a contact) .............................................................................. 50
Parameters ................................................................................................................................................... 50
Return values ................................................................................................................................................ 50
Authentication .............................................................................................................................................. 50
Description ................................................................................................................................................... 50
Example ........................................................................................................................................................ 51

3.10

Devices ....................................................................................................................... 51
3.10.1 GET /api/v1/devices (list all devices from the computers & contacts list) ........................................... 51
Parameters ................................................................................................................................................... 51
Return values ................................................................................................................................................ 51
Authentication .............................................................................................................................................. 51
Description ................................................................................................................................................... 51
Example ........................................................................................................................................................ 52
3.10.2 PUT /api/v1/devices/<dID> (change device details) ............................................................................ 52
Parameters ................................................................................................................................................... 52
Return values ................................................................................................................................................ 52
Authentication .............................................................................................................................................. 52
Description ................................................................................................................................................... 52
Example ........................................................................................................................................................ 53
3.10.3 POST /api/v1/devices (add a new device) ............................................................................................ 53
Parameters ................................................................................................................................................... 53
Return values ................................................................................................................................................ 53
Authentication .............................................................................................................................................. 53
Description ................................................................................................................................................... 53
Example ........................................................................................................................................................ 53
3.10.4 DELETE /api/v1/devices/<dID> (delete a device) ................................................................................. 54
Parameters ................................................................................................................................................... 54
Return values ................................................................................................................................................ 54
Authentication .............................................................................................................................................. 54

TeamViewer API - Documentation

www.teamviewer.com

Page 7 of 60

Description ................................................................................................................................................... 54
Example ........................................................................................................................................................ 54

Errors ....................................................................................................... 55

4.1

HTTP response codes .................................................................................................. 55

4.2

JSON error responses .................................................................................................. 55

Licensing................................................................................................... 57

Contact ..................................................................................................... 58

Appendix A ............................................................................................... 59

7.1

URLs for connections with devices............................................................................... 59

7.2

URLs for connections with contacts ............................................................................. 60

TeamViewer API - Documentation

www.teamviewer.com

Page 8 of 60

Introduction

1 Introduction

1.1

1.2

Definitions
Name

Description

Supporter

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

End Customer

A user who does not need to have a TeamViewer account. The user is in
most 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.

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
items in this collection

create new item

in this 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
Parameters in the URI are only allowed for GET and DELETE. Generally there should be no need for any parameters for DELETE, though. POST and PUT need to have the parameters in the body formatted as JSON or
XML.

TeamViewer API - Documentation

www.teamviewer.com

Page 9 of 60

Introduction

1.3

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

"u" - user ID

"g" group ID

"m" meeting ID

"s" session code

c contact ID

d device ID

r remote control ID, also referred to as TeamViewer ID in other documentations

Reports use a GUID and are not prefixed.

1.4

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

Example

1.5

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

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 API - Documentation

www.teamviewer.com

Page 10 of 60

User permissions

2 User permissions

2.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

ManagePolicies

Manage & Assign policies

AssignPolicies

Assign policies

AcknowledgeAllAlerts

View & acknowledge all alerts

AcknowledgeOwnAlerts

View & acknowledge own alerts

ViewAllAssets

View all assets

TeamViewer API - Documentation

www.teamviewer.com

Page 11 of 60

User permissions

2.2

Name in API

Name in Management Console

ViewOwnAssets

View assets

EditAllCustomModuleConfigs

Manage all customizations

EditOwnCustomModuleConfigs

Manage own customizations

None

<no permission is set in console>

Permission dependencies
Some permissions are depending on each other and cannot be set individually, e. g. if a user has the permission 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, EditConnections, DeleteConnections,

ManagePolicies, AssignPolicies, AcknowledgeAllAlerts,AcknowledgeOwnAlerts, ViewAllAssets, ViewOwnAssets,
EditAllCustomModuleConfigs, EditOwnCustomModuleConfigs

ManageUsers

ShareOwnGroups, EditFullProfile, ViewAllConnections,

ViewOwnConnections, EditConnections, DeleteConnections, ManagePolicies, AssignPolicies, AcknowledgeAllAlerts, AcknowledgeOwnAlerts, ViewAllAssets, ViewOwnAssets, EditAllCustomModuleConfigs, EditOwnCustomModuleConfigs

ShareOwnGroups

ViewAllConnections

ViewOwnConnections

ViewOwnConnections

EditConnections

DeleteConnections

TeamViewer API - Documentation

www.teamviewer.com

Page 12 of 60

User permissions

Name in API

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

EditFullProfile

ManagePolicies

AssignPolicies, AcknowledgeAllAlerts, AcknowledgeOwnAlerts

AssignPolicies

AcknowledgeAllAlerts, AcknowledgeOwnAlerts

AcknowledgeAllAlerts

AcknowledgeOwnAlerts

AcknowledgeOwnAlerts

ViewAllAssets

ViewOwnAssets

ViewOwnAssets

EditAllCustomModuleConfigs

EditOwnCustomModuleConfigs

EditOwnCustomModuleConfigs

TeamViewer API - Documentation

www.teamviewer.com

Page 13 of 60

API Functions

3 API Functions

3.1

Authentication (OAuth 2.0)

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:

3.1.1

resource owner The user behind a TeamViewer account who wants to access their resources
through the API.

resource server Our servers where the API runs.

client The application, plug-in, script or user who is making the API HTTP requests.

authorization server In our case that's the same servers that run the rest of the API.

client ID A unique ID to identify the application that wants to use the TeamViewer API.

client secret A unique string only known to the creator of the client ID.

authorization code Code used during the OAuth process to prove that an authorization request was granted in the Management Console.

access token A token that has to be used to access any API function (except those explicitly
marked as not requiring any access tokens).

refresh token A token that can be used once to obtain a new access token and a new refresh
token.

Registering an application in the Management Console

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 API - Documentation

www.teamviewer.com

Page 14 of 60

API Functions

Client/Application-Types
Script

App

User Access

Access token is created that can

only be used to access the user
who created the application.

Client ID is created when creating the

application. The Client ID can be used
with OAuth to create an access token
for the user granting access.

Company Access

Access token is created that can be

used to access the company of the
user (=company admin) who created the application.

Client ID is created when creating the

application. The Client ID can be used
with OAuth to create an Access-Token
to access the company of the user
(=company admin) granting access.

When you register an application for your own use only, you will get an access token that can be used directly 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 token 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.1.2

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 access
only)

Account.Create, Account.Read, Account.ReadEmail, Account.Modify, Account.ModifyEmail, Account.ModifyPassword

Groups

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

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

TeamViewer API - Documentation

www.teamviewer.com

Page 15 of 60

API Functions

3.1.3

Meetings
(user level access
only)

Meetings.Create, Meetings.Read, Meetings.Modify, Meetings.Delete

Devices & Contacts

(user level access
only)

ContactList.Create, ContactList.Read, ContactList.Modify, ContactList.Delete

The authorization process

When using private Script Tokens, there is no need for an authorization process. Access to the account/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 users 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.1.3.1 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 users data, as long as the users permissions allow. If user rights are changed later,
the application may be able to access more data.

3.1.3.2 Company level access

To grant company level access to an application the user needs to have all required permissions. 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.1.4

GET /api/v1/oauth2/authorize (authorization endpoint)

Parameters

response_type Must be code.

client_id Client ID, a unique string that identifies the application.

redirect_uri (optional) URI to redirect to once access has been granted. If this parameter
is left out the code that would have been returned here is shown in the browser and has to be

TeamViewer API - Documentation

www.teamviewer.com

Page 16 of 60

API Functions

copied manually to the application. If a fixed redirect URI is specified for the provided client ID,
the value of this parameter must match it.

state (optional) Can be set if needed, and will be returned to the callback URI if it was set
here.

Return values
Not applicable here, because this needs to be opened in a browser and will return a website. The other values will be added to the redirect_uri once access has been granted.

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

state 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 get an access token. This is the only function that should not be called directly from a 3 rd party application but it should be opened in a browser and return a website where the user can grant access to the 3 rd
party application.

Example
Request:
GET /api/v1/oauth2/authorize?response_type=code&client_id=12333133Ea4Hdf3e9ec0543fX&redirect_uri=https%3A%2F%2F2.zoppoz.workers.dev%3A443%2Fhttps%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1

3.1.5

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 authorization code and one using a refresh token.
Authorization-Code Grant:

grant_type Must be authorization_code.

code Authorization code acquired from the /oauth2/authorize page.

redirect_uri (optional) Must be the same value as in the previous call to /oauth2/authorize. If no redirect_uri was given none should be added here as well.

client_id Client ID, a unique string that identifies the application.

client_secret The client secret, which is known only to the creator of the application.

Refresh-Token:

grant_type Must be refresh_token.

refresh_token Refresh-token from a previous call.

client_id Client ID, a unique string that identifies the application.

client_secret - The client secret, a unique string known only to the creator of the application.

TeamViewer API - Documentation

www.teamviewer.com

Page 17 of 60

API Functions

Return values

access_token Access token to use with all further API calls.

token_type Authentication-method used for this access token, currently only bearer is
used.

expires_in Time in seconds until the access token expires and needs to be refreshed.

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 CacheControl 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 specification), 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&redirect_uri=https%3A%2F%2F2.zoppoz.workers.dev%3A443%2Fhttps%2Fc
lient%2Eexample%2Ecom%2Fcb&client_id=12333-133Ea4Hdf3e9ec0543fX

Response (Authorization code grant):

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{"access_token":"54213-2YotnFZFEjr1zCsicMWp",
"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.

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.

TeamViewer API - Documentation

www.teamviewer.com

Page 18 of 60

API Functions

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.1.6

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.

Example
Request
POST /api/v1/oauth2/revoke HTTP/1.1
Host: https://webapi.teamviewer.com
Authorization: Bearer 54213-2YotnFZFEjr1zCsicMWp

Response
HTTP/1.1 200 OK

3.2

Ping

3.2.1

GET /api/v1/ping
Parameters
None

Return values

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.

TeamViewer API - Documentation

www.teamviewer.com

Page 19 of 60

API Functions

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}

3.3

Account Management

3.3.1

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

Parameters
None.

Return values

name The name of the user.

email The associated email address. Only returned if access token has the Account.ReadEmail scope.

userid The user ID.

company_name (optional) The name of the company that the user belongs to.

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

TeamViewer API - Documentation

www.teamviewer.com

Page 20 of 60

API Functions

Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"userid": "u1234567",
"email": "[email protected]",
"name": "John Doe",
"company_name": "Johns Company"
}

3.3.2

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

Parameters

name (optional) The name of the user.

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.

password (optional) - A new password for this account. If password is set, oldpassword must
be set to the correct value of the old password.

oldpassword (optional) - The old password of this account

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

TeamViewer API - Documentation

www.teamviewer.com

Page 21 of 60

API Functions

3.4

User Management

3.4.1

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

Parameters

email (optional) Lists the user that has an exact match of the given email address.

name (optional) List all users that have the given string as part of their user name.

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
2.1 for a list of possible values).

full_list (optional) true: list contains all info fields about the users, false (default): list
contains only minimal info about the users

Return values
For the minimal list:

id user ID, needed to access/modify that user

name name of the user

For the full list (additionally):

permissions (optional) Comma-separated list of permissions that this user has. (See 2.1 for
a list of possible values).

active true if the account is active, false otherwise.

custom_quicksupport_id (optional) The ID of the default custom QuickSupport module

for this user. Omitted if value is auto.

custom_quickjoin_id (optional) The ID of the default custom QuickJoin module for this
user. Omitted if value is auto.

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
HTTP/1.1 200 OK
Content-Type: application/json

TeamViewer API - Documentation

www.teamviewer.com

Page 22 of 60

API Functions

{ "users" : [
{ "id" : "u1234567",
"name" : "Mighty Administrator",
"permissions" : "ManageAdmins, ManageUsers, ShareOwnGroups, EditFullProfile,
ViewAllConnections, ViewOwnConnections, EditConnections, DeleteConnections,
ManagePolicies, AssignPolicies, AcknowledgeAllAlerts,AcknowledgeOwnAlerts,
ViewAllAssets, ViewOwnAssets, EditAllCustomModuleConfigs,
EditOwnCustomModuleConfigs",
"active": true
},
{ "id" : "u2345678",
"name" : "John Doe",
"permissions" : "EditFullProfile"
}]
}

3.4.2

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

Parameters

email Email of that user. Will be used for login.

password Password for the user. Will be used for login.

permissions (optional) Comma-separated list of permissions that this user has. See 2.2 for
valid values and combinations. If omitted the following default permissions will be set: ShareOwnGroups, ViewOwnConnections, EditConnections, EditFullProfile

name Name of the new user.

language Language code for the user. Will be used for the welcome email.

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.

custom_quicksupport_id (optional) The ID of the default custom QuickSupport module

for this user. Defaults to auto if omitted.

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.

TeamViewer API - Documentation

www.teamviewer.com

Page 23 of 60

API Functions

Example
Request
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"
}

3.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 .

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

name name of the user.

permissions (optional) String list of permissions that this user has. See 2.1 for valid values.

active true if the account is active, false otherwise.

custom_quicksupport_id (optional) The ID of the default custom QuickSupport module

for this user. Omitted if value is auto.

custom_quickjoin_id (optional) The ID of the default custom QuickJoin module for this
user. Omitted if value is auto.

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

TeamViewer API - Documentation

www.teamviewer.com

Page 24 of 60

API Functions

Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"id" : " u123",
"email" : "[email protected]",
"name" : "John Doe",
"permissions" : "EditFullProfile",
"active" : true
}

3.4.4

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

Parameters

email (optional) New Email of the user. A verification Email will be sent to the new address.

name (optional) Real name of the user.

permissions (optional) Comma-separated list of permissions that this user has. See 2.2 for
valid values and combinations.

password (optional) Assign a new password for this user.

active (optional) Activates or deactivates an account.

DEPRECATED license_key (optional) License key of the license that will be assigned to
the user. To assign a license to a user, it must have been added to the company first.

custom_quicksupport_id (optional) The ID of the default custom QuickSupport module

for this user. Set to auto if no specific module should be assigned.

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).

TeamViewer API - Documentation

www.teamviewer.com

Page 25 of 60

API Functions

Example
Request
PUT /api/v1/users/u123
Content-Type: application/json
{ "name" : "John Locke" }

Response
HTTP/1.1 204 No Content

3.5

Group Management

3.5.1

Accessing groups from different users in a company

Important 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. So "GET /groups" for example becomes "GET /users/<uID>/groups".

3.5.2

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

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

Parameters

name (optional) Group name or part of the group name

shared (optional) True: list only shared groups, i. e. groups where the current user is not the
owner. 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

groups List of groups.

id Group ID

name Name of the group.

shared_with (optional) List of users who this group is shared with. Can be omitted if
empty.

userid User ID of the user the group is shared with.

name Name of the user the group is shared with.

permissions Access-permissions of the user on this group. Either read or readwrite.

pending true if the user hasn't accepted the shared group yet, otherwise the field can
be omitted.

owner (optional) Owner of this group. Omitted if the owner is the current user.
o

userid User ID of the owner of this group.

name Name of the owner of this group.

permissions read, readwrite or owned.

TeamViewer API - Documentation

www.teamviewer.com

Page 26 of 60

API Functions

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"
}]
}

3.5.3

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

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

Parameters

name Name of the new group.

Return values

id Group ID of the newly created group.

name Name of the new group. This should be the same parameter as the input parameter.

permissions Will always be owned, because the group is not yet shared at this point.

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

Description
Creates a new group and returns its info.

TeamViewer API - Documentation

www.teamviewer.com

Page 27 of 60

API Functions

Example
Request
POST /api/v1/groups
Content-Type: application/json
{ "name" : "Test" }

Response
HTTP/1.1 200 OK
Content-Type: application/json
Location: https://webapi.teamviewer.com/groups/g425123356
{
"id" : "g425123356",
"name" : "Test",
"permissions" : "owned"
}

3.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

id Group ID

name Name of the group.

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.

userid User ID of the user the group is shared with.

permissions Access-permissions of the user on this group. Either read or readwrite.

owner (optional) Owner of this group. Will be omitted if the owner is the current user.

userid User ID of the owner of this group.

name Name of the owner of this group.

permissions Access permissions for the current user. read, readwrite or owned.

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

Description
Returns info for one group.

Example
Request
GET /api/v1/groups/g425123356

TeamViewer API - Documentation

www.teamviewer.com

Page 28 of 60

API Functions

Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"id" : "g425123356",
"name" : "Test",
"owner" : {
"userid" : "u814464403",
"name" : "Tester" },
"permissions" : "owned"
}

3.5.5

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

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

Parameters

name New name of the group.

Return values
HTTP status code 204 if change succeeded.

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

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" }

Response
HTTP/1.1 204 No Content

3.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.
TeamViewer API - Documentation

www.teamviewer.com

Page 29 of 60

API Functions

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

Response
HTTP/1.1 204 No Content

3.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

users List of users with whom the group will be shared.

userid User ID of one of the users you want to share the group with.

permissions Access-permissions of the user on this group. Either read or readwrite.

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 API - Documentation

www.teamviewer.com

Page 30 of 60

API Functions

Response
HTTP/1.1 204 No content

3.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

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

3.6

Session Management

3.6.1

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

Parameters

groupid (optional) Filter by group id.

assigned_userid (optional) Filter by assigned_userid.

state (optional) State of the session. Can be open or closed. By default only open sessions
will be selected. States can be combined with a comma.

full_list (optional) true: Return all information for the sessions. This is false by default.

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):
TeamViewer API - Documentation

www.teamviewer.com

Page 31 of 60

API Functions

sessions List of session codes.

code Session code.

state State of the session. Can be "open" or "closed".

online Online state of the session. Can be true or false.

groupid Group ID where this session is stored under.

sessions_remaining Number of session codes left after the ones returned here. Will be
omitted if there are no further session codes.

next_offset Offset that can be used to get the next 1000 session codes.

For the full list (full_list=true):

waiting_message Message displayed to the waiting end customer.

description Description for this session code.

end_customer End Customer info

o

name Name of the end customer.

email Email of the end customer.

assigned_userid User ID of the user this session is assigned to. If session is unassigned,
value is u0.
assigned_at Date when the last user was assigned.
end_customer_link Link for the end customer.
supporter_link Link for the supporter.
custom_api Custom field that can be used to store an arbitrary string but is only available to
API functions. It is limited to 4000 characters.
created_at Date when the session code was created.
valid_until Date until when the session code is/was valid.
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 sessions 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

TeamViewer API - Documentation

www.teamviewer.com

Page 32 of 60

API Functions

Response
HTTP/1.1 200 OK
Content-Type: application/json
{"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" : "[email protected]" },
"assigned_userid" : "u7254190",
"end_customer_link" : "https://get.teamviewer.com/...",
"supporter_link" : "https://get.teamviewer.com/...",
"custom_api" : "{ "ticket_id" : "535824" }"
}, ]
}

3.6.2

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

Parameters

valid_until (optional) Date when session code becomes invalid. Will default to 24h from
now when no date is given.

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 groupname must be
set. For applications with company level access, this parameter is required.

groupname (partially required) Name of the group that 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.

waiting_message (optional) Message displayed to the waiting end customer.

description (optional) Description for the new session code.

end_customer (optional) End customer info.

name (optional) Name of the end customer. Maximum length is 100 characters.

email (optional) Email of the end customer. Maximum length is 254 characters.

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.

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 4000 characters.

Return values

code Newly created session code.

state State of the session. Can be open or closed.

groupid Group ID where this session is stored in.

waiting_message Message displayed to the waiting end customer.

description Description for this session code.

end_customer End customer info

name Name of the end customer.

email Email of the end customer.

TeamViewer API - Documentation

www.teamviewer.com

Page 33 of 60

API Functions

assigned_userid User ID of the user this session code is assigned to. If the session code is
not assigned the value will be u0.

assigned_at Date when the last user last assigned.

end_customer_link Link for the end customer.

supporter_link Link for the supporter.

custom_api Custom field that stores any valid JSON/XML object (max 4000 characters) and
is only visible for API users.

created_at Date when the session code was created.

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)
POST /api/v1/sessions
Content-Type: application/json
{"groupid" : "g425123356",
"description" : " I have aproblemwith myspace bar.",
"end_customer" : { "name" : "Max" }
}

Response
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 aproblemwith myspace bar.",
"assigned_userid" : "u7254190",
"end_customer_link" : "https://get.teamviewer.com/s12345678",
"supporter_link" : "https://get.teamviewer.com/s12345678-asfg1234asfg",
"valid_until" : "2013-10-30T12:03:29Z"
}

3.6.3

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

Parameters
None

Return values

code Session code.

TeamViewer API - Documentation

www.teamviewer.com

Page 34 of 60

API Functions

state State of the session. Can be open or closed.

online Online-state of the session. Can be true or false.

groupid Group ID where this session is stored in.

waiting_message Message displayed to the waiting end customer.

description Description for this session code.

end_customer End customer info

name Name of the end customer. Maximum length is 100 characters.

email Email of the end customer. Maximum length is 254 characters.

assigned_userid User ID of the user this session code is assigned to.

end_customer_link Link for the end customer.

supporter_link Link for the supporter.

custom_api Custom fields, this stores any arbitrary string but is only available to API functions. It is limited to 4000 characters.

valid_until Date until when the session code is/was valid.

closed_at Date when the session was closed.

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" : "g425123356",
"waiting_message" : "",
"description" : "HELP!!!11",
"end_customer" : { "name" : "Max", "email" : "" },
"assigned_userid" : "u7254190",
"end_customer_link" : "https://get.teamviewer.com/...",
"supporter_link" : "https://get.teamviewer.com/...",
}

3.6.4

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

Parameters

groupid (optional) Group ID where this session will be moved to.

TeamViewer API - Documentation

www.teamviewer.com

Page 35 of 60

API Functions

groupname (optional) Group name where this session will be moved to. If both groupname
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.

waiting_message (optional) Message displayed to the waiting end customer.

description (optional) Description for this session code.

end_customer (optional) End customer info

name (optional) Name of the end customer.

email (optional) Email of the end customer.

assigned_userid (optional) User ID of the user to assign this session to. Set to u0 to unassign session.

custom_api (optional) Custom fields, this stores any arbitrary string but is only available to
API functions. It is limited to 4000 characters.

state (optional) State of the session. Can be "open" or "closed".

Return values
HTTP status 204 if changes succeeded.

Authentication
User or company access token. Scope: Sessions.ModifyAll or Sessions.ModifyOwn.

Description
Modifies an existing session code.

Example
Request
PUT /api/v1/sessions/s13-123-123
Content-Type: application/json
{"description" : "Still not working."}

Response
HTTP/1.1 204 No Content

3.7

Connection Reporting

3.7.1

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

Parameters

username (optional) Filter by user name of the person who started the connection.

userid (optional) Filter by user ID of the person who started the connection.

groupid (optional) Filter by group ID where the target device or user was in.

devicename (optional) Filter by target device name. Set to unnamed_device to only return
results for unnamed devices. Only available if you are using a user access token.

deviceid (optional) Filter by device ID.

TeamViewer API - Documentation

www.teamviewer.com

Page 36 of 60

API Functions

from_date (optional) First 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. Connections
with start_date equal to from_date are included in the results.

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. Connections
with start_date equal to to_date are excluded from the results.

offset_id (optional) All returned reports will follow the report-ID given in this field. The
given report-ID is excluded from the results.

has_code (optional) Filters out reports that have no session code if true or that have a session 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:

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

Return values

records List of remote control connections

id Report-ID

userid User ID of the person who started the connection.

username User name of the person who started the connection.

contact_id (optional) Contact ID of the target. The Contact ID is returned only for connections made to contacts.

deviceid TeamViewer ID of the target device.

devicename (optional) Device name of the target device. Only returned if you are using a
user access token.

groupid ID of the group where the device is currently located.

groupname Name of the group where the device is currently located.

start_date Start date and time of the connection.

end_date End date and time of the connection.

fee (optional) Costs for the connection.

currency (optional) Currency for the fee field.

billing_state Can be Bill, Billed or DoNotBill.

notes (optional) Notes for this connection.

records_remaining (optional) Number of records after the ones listed here. Can be omitted if there are no more reports left.

next_offset (optional) ID of the last returned report in this response. Can be used as offset_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

records

assigned_userid User ID of the user this session code is assigned to.

assigned_at Date when the session code was last assigned to another user.

session_code Session code.

session_created_at Date when the session code was created.

valid_until Date until when the session code is/was valid.

session_note Description of the Service Case.

TeamViewer API - Documentation

www.teamviewer.com

Page 37 of 60

API Functions

custom_api Custom fields, this stores any arbitrary string but is only available to API functions. It is limited to 4000 characters.

end_customer

name (optional) Name of the end customer.

email (optional) Email address of the end customer.

feedback (optional) If feedback was enabled but customer did not provide feedback, an
empty object is returned.
o

session_rating (optional) Session rating from customer (integer, higher is better).

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 1000 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

TeamViewer API - Documentation

www.teamviewer.com

Page 38 of 60

API Functions

Response
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"
}
]}

3.7.2

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

Parameters

billing_state (optional) Can be Bill, Billed or DoNotBill.

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.

TeamViewer API - Documentation

www.teamviewer.com

Page 39 of 60

API Functions

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

3.7.3

DELETE /api/v1/reports/connections/<rID> (delete a connection report)

Parameters
None.

Return values
HTTP status code 204.

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

3.8

Meetings

3.8.1

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

3.8.1.1 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 API - Documentation

www.teamviewer.com

Page 40 of 60

API Functions

3.8.1.2 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 participant link only appear in the
response of the POST request.

3.8.2

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

Parameters

from_date (optional) First 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.

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

id The unique meeting ID.

subject The subject of the meeting.

start The start date and time of the meeting.

end The end date and time for the meeting.

password (optional) The meeting password. Omitted if no password is set.

conference_call_information Information about the conference call-

type Type of the conference call information. Can be either None, TeamViewer or
Custom.

custom_data (optional) The custom text that is displayed when type is set to Custom. Omitted if empty.

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 /meetings/<mID> for each of
these users.

Example
Request
GET /api/v1/meetings

TeamViewer API - Documentation

www.teamviewer.com

Page 41 of 60

API Functions

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"
}
]
}

3.8.3

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

Parameters
None.

Return values

id The unique meeting ID.

subject The subject of the meeting.

start The start date and time of the meeting.

end The end date and time for the meeting.

password (optional) The meeting password. Omitted if no password is set.

conference_call_information Information about the conference call:

type Type of the conference call information. Can be either None, TeamViewer or
Custom.

custom_data (optional) The custom text that is displayed when type is set to Custom. Omitted if empty.

participant_web_link A web link to join the meeting.

Authentication
User access token. Scope: Meetings.Read.

TeamViewer API - Documentation

www.teamviewer.com

Page 42 of 60

API Functions

Description
Retrieve the details of one single meeting.

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

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": "1234",
"conference_call_information": {
"type": "Custom",
"custom_data": "Dial 555-4816-2342 to join the conference."
},
"participant_web_link": "https://go.teamviewer.com/m12345678"
}

3.8.4

GET /api/v1/meetings/<mID>/invitation (retrieve invitation information for a scheduled meeting)

Parameters

timezone The time zone for which the invitation is created. Specified as offset to UTC as defined by ISO 8061. Examples:
o

+0100 for the time zone 1 hour east of UTC, e.g. Central European Time (CET)

+0200 for the time zone 2 hours east of UTC, e.g. Central European Summer Time
(CEST)

-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");

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

TeamViewer API - Documentation

www.teamviewer.com

Page 43 of 60

API Functions

Return values

invitation_text An invitation text that can be used for emails, chat programs, etc. It contains 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.

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 meeting:\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"}

3.8.5

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

Parameters

instant (optional) Set true for an instant meeting, false for a scheduled meeting. See
3.8.1 for details about meeting types. Defaults to false.

subject (optional) Subject of the meeting. Required for scheduled meetings, must be left
empty for instant meetings.

start (optional) Start date and time. Required for scheduled meetings, must be left empty
for instant meetings.

end (optional) End date and time. Required for scheduled meetings, must be left empty for
instant meetings.

password (optional) A password that participants must enter to join the meeting.

conference_call_information (optional) Information about how to join a conference

for the meeting. Defaults to {"type" : "TeamViewer"} if omitted.
o

type Type of the conference call information. Can be either None, TeamViewer or
Custom.

custom_data (optional) The custom text that is displayed when type is set to Custom.

TeamViewer API - Documentation

www.teamviewer.com

Page 44 of 60

API Functions

Return values

id The unique meeting ID.

subject (optional) Subject of the meeting. Omitted for instant meetings.

start (optional) The start date and time of the meeting. Omitted for instant meetings.

end (optional) The end date and time for the meeting. Omitted for instant meetings.

password (optional) The meeting password. Omitted if no password is set.

conference_call_information Information about the conference call-

type Type of the conference call information. Can be either None, TeamViewer or
Custom.

custom_data (optional) The custom text that is displayed when type is set to Custom. Omitted if empty.

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
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"
}

TeamViewer API - Documentation

www.teamviewer.com

Page 45 of 60

API Functions

Example for an instant meeting

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

Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "m13-345-678",
"participant_web_link": "https://go.teamviewer.com/m13345678"
}

3.8.6

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

Parameters

subject (optional) Subject of the meeting.

start (optional) Start date and time.

end (optional) End date and time.

password (optional) A password that participants must enter to join the meeting.

conference_call_information (optional) Information about how to join a conference

for the meeting.
o

type (optional) Type of the conference call information. Can be either None,
TeamViewer or Custom.

custom_data (optional) The custom text that is displayed when type is set to Custom.

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.

TeamViewer API - Documentation

www.teamviewer.com

Page 46 of 60

API Functions

Example
Request
PUT /api/v1/meetings/m12-345-678
Content-Type: application/json
{"subject" : "Webinar: TeamViewer API Best Practices"}

Response
HTTP/1.1 204 No Content

3.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

3.9

Contacts

3.9.1

GET /api/v1/contacts (list all contacts from the computers & contacts list)
Parameters

name (optional) Return only contacts that contain the value of this parameter in their name.

TeamViewer API - Documentation

www.teamviewer.com

Page 47 of 60

API Functions

email (optional) Return only the contact or invite that 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 contacts with a single call.

online_state (optional) Return only contacts with the given online_state.

groupid (optional) Return only contacts that are in the specified group.

include_invitations (optional) Additionally returns a list of all pending invitations if

true.

Return values

contact_id The ID that is unique for this entry of the computers & contacts list. Values are
always prefixed with a c.

name The name of the contact.

email (optional) The email address of the contact. This is only returned if the parameter
email was provided when calling the function.

groupid The ID of the group that this contact is a member of.

description The description that the current user has entered for this contact.

online_state The current online state of the contact. Possible values are: online, busy,
away, offline.

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 placeholder 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.

supported_features The features supported by the contact. Possible values are: chat,
remote_control, meeting, videocall.

invitations (optional) List of all pending invitations.

o

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

email The email address of the invitee.

Authentication
User access token. Scope: ContactList.Read.

Description
Returns a list of contacts in the users 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 https://start.teamviewer.com. For
more information please see Appendix A, page 59.

TeamViewer API - Documentation

www.teamviewer.com

Page 48 of 60

API Functions

Example
Request
GET /api/v1/contacts

Response
HTTP/1.1 200 OK
Content-Type: application/json
{"contacts": [
{
"contact_id": "c123456789",
"name": "Jack",
"groupid": "g12345678",
"online_state": "Offline",
"profilepicture_url": "https://profilepicturedl.teamviewer.com/a35489836/81cae6b1-4acf-4138-bd14-f3c27716b400/[size]"
"supported_features": "remote_control, videocall, chat, meeting"
},
{
"contact_id": "c123456780",
"name": "John",
"groupid": "g12345678",
"online_state": "Offline"
}]
}

3.9.2

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

Parameters

email The unique email of the account that is to be added as a contact.

groupid (partially required) ID of the group the contact will be added to. Either this or
groupname parameter must be set.

groupname (partially required) Name of the group that 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.

description (optional) The description of the contact.

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

TeamViewer API - Documentation

www.teamviewer.com

Page 49 of 60

API Functions

the contact is already present in the computers & contact list in a group owned by the current
user.

an account with the specified email does not exist.

the user does not have sufficient rights to add a contact in the specified group.

Example
Request
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"
}

3.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

a contact with the given cID does not exist in the current users computers & contact list.

the user does not have sufficient rights to remove the specified contact from a shared group.

TeamViewer API - Documentation

www.teamviewer.com

Page 50 of 60

API Functions

Example
Request
DELETE /api/v1/contacts/c123456789

Response
HTTP/1.1 204 No Content

3.10 Devices
3.10.1 GET /api/v1/devices (list all devices from the computers & contacts list)
Parameters

online_state (optional) Return only devices with the given online_state.

groupid (optional) Return only devices that are in the specified group.

remotecontrol_id Return only devices with the specified remotecontrol_id

Return values

device_id The ID that is unique for this entry of the computers & contacts list. Values are
always prefixed with a d.

remotecontrol_id The ID that is unique to this device and can be used to start a remote
control session.

groupid The ID of the group that this device is a member of.

alias The alias that the current user has given to this device.

description The description that the current user has entered for this device.

online_state The current online state of the device. Possible values are: online, offline.

supported_features The features supported by the device. Possible values are: chat,
remote_control.

Authentication
User access token. Scope: ContactList.Read.

Description
Returns a list of devices in the users 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 https://start.teamviewer.com.
For more information please see Appendix A, page 59.

TeamViewer API - Documentation

www.teamviewer.com

Page 51 of 60

API Functions

Example
Request
GET /api/v1/devices

Response
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"
},
{
"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"
}
]

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

Parameters

alias (optional) A new alias for the device.

description (optional) A new description for the device.

password (optional) A password that will be used when connecting to the device.

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.

TeamViewer API - Documentation

www.teamviewer.com

Page 52 of 60

API Functions

Example
Request
PUT /api/v1/devices/d12345
Content-Type: application/json
{"description" : "Swan Terminal"}

Response
HTTP/1.1 204 No Content

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

Parameters

remotecontrol_id The TeamViewer ID of the device to be added.

groupid The group in which the device is to be added.

description (optional) The description of the device.

alias (optional) The alias of the device.

password (optional) A password that will be used when connecting to the device.

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

the device is already present in the computers & contact list in a group owned by the current
user.

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
}

TeamViewer API - Documentation

www.teamviewer.com

Page 53 of 60

API Functions

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

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

3.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

a device with the given dID does not exist in the current users computers & contact list.

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

TeamViewer API - Documentation

www.teamviewer.com

Page 54 of 60

Errors

4 Errors

4.1

HTTP response codes

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.

4.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:

error A short string describing the category of error.

error_description A longer string containing a human readable error message.

error_code A number that is unique for each type of error.

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:

invalid_request The request is missing a required parameter, includes an unsupported

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.

invalid_token The access token provided is revoked, malformed, or invalid. Should be

used with HTTP response code 401 (Unauthorized).

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).

blocked The request was blocked. That should only happen when the IP was blocked.

TeamViewer API - Documentation

www.teamviewer.com

Page 55 of 60

Errors

rate_limit_reached Too many calls to a single function with the same access token.

token_expired Access token is expired. A new access token needs to be requested.

invalid_client Client ID was invalid.

email_in_use Returned during account creation or when changing the email if the email is
already used by another account.

invalid_request and invalid_token are taken from http://self-issued.info/docs/draft-ietf-oauth-v2bearer.html#resource-error-codes (with the exception that they are not included in the WWW-Authenticate header field but the returned JSON).

TeamViewer API - Documentation

www.teamviewer.com

Page 56 of 60

Licensing

5 Licensing

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

Connection reporting and user management: TeamViewer 9 or above, Premium or Corporate

Functions with company level access: TeamViewer 9 or above, Premium or Corporate

Contacts and Devices: TeamViewer 10

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
requires any of the aforementioned functions.

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

TeamViewer API - Documentation

www.teamviewer.com

Page 57 of 60

Contact

6 Contact

If you have questions or feedback, please contact [email protected].

TeamViewer API - Documentation

www.teamviewer.com

Page 58 of 60

Appendix A

7 Appendix A

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.

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 3.10 Devices, page 51.

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 3.9 Contacts, page 47.

Please find a list of the available parameters below.

Parameter

Values

Default

device

<remotecontrol_id>

contact

<contact_id>

mode

control, present, videocall, filetransfer, sendfile, vpn, chat

control

authorization

prompt, password

password (if mode does not support a

password, prompt is default)

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

7.1

URLs for connections with devices

URL

Request

start.teamviewer.com/<remotecontrol_id>

Remote control (using password)

start.teamviewer.com/device/<remotecontrol_id>/autho
rization/password/mode/filetransfer

File transfer (using password)

TeamViewer API - Documentation

www.teamviewer.com

Page 59 of 60

Appendix A

7.2

URL

Request

start.teamviewer.com/device/<remotecontrol_id>/autho
rization/password/mode/control

Remote control (using password)

start.teamviewer.com/device/<remotecontrol_id>/autho
rization/password/mode/vpn

VPN (using password)

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

Chat

URLs for connections with contacts

URL

Request

start.teamviewer.com/contact/<contact_id>/authorizat
ion/password/mode/control

Remote control (using password)

start.teamviewer.com/contact/<contact_id>/authorizat
ion/password/mode/filetransfer

File transfer (using password)

start.teamviewer.com/contact/<contact_id>/authorizat
ion/password/mode/vpn

VPN (using password)

start.teamviewer.com/contact/<contact_id>/authorizat
ion/prompt/mode/present

Presentation (prompt for confirmation)

start.teamviewer.com/contact/<contact_id>/authorizat
ion/prompt/mode/control

Remote control (prompt for

confirmation)

start.teamviewer.com/contact/<contact_id>/authorizat
ion/prompt/mode/videocall

Video Call (prompt for confirmation)

start.teamviewer.com/contact/<contact_id>/authorizat
ion/prompt/mode/sendfile

Send file (prompt for confirmation)

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

Chat

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

TeamViewer API - Documentation

www.teamviewer.com

Page 60 of 60