TeamViewer WebAPI Documentation

Transcription

1 TeamViewer WebAPI Dcumentatin Versin TeamViewer GmbH Jahnstr. 30 D Göppingen

2 Table f Cntents 1 Changelg Intrductin Definitins REST IDs Date frmat Number frmat User permissins Permissin names in API and Management Cnsle Permissin dependencies Rate limits OAuth 2.0 Authrizatin Rles & Terms Registering an applicatin in the Management Cnsle Client/Applicatin-Types Access Tken Permissins and Scpes The authrizatin prcess User level access Cmpany level access Authrizatin Endpint GET lgin.teamviewer.cm/auth2/authrize POST /api/v1/auth2/tken (tken endpint) POST /api/v1/auth2/revke API Functins Ping GET /api/v1/ping Accunt Management TeamViewer API - Dcumentatin Page 2 f 64

3 4.2.1 GET /api/v1/accunt (retrieve accunt data) PUT /api/v1/accunt (change accunt data) User Management GET /api/v1/users (retrieve list f users) POST /api/v1/users (create new cmpany member) GET /api/v1/users/<uid> (get infrmatin fr ne user) PUT /api/v1/users/<uid> (mdify user infrmatin) Grup Management Accessing grups frm different users in a cmpany GET /api/v1/grups (list all available grups) POST /api/v1/grups (create a new grup) GET /api/v1/grups/<gid> (get grup details) PUT /api/v1/grups/<gid> (change grup details) DELETE /api/v1/grups/<gid> (delete a grup) POST /api/v1/grups/<gid>/share_grup (share grup with ther user(s)) POST /api/v1/grups/<gid>/unshare_grup (unshare a grup frm certain users) Sessin Management GET /api/v1/sessins (list sessin cdes) POST /api/v1/sessins (create new sessin cde) GET /api/v1/sessins/<cde> (get inf abut a certain sessin cde) PUT /api/v1/sessins/<cde> (mdify inf fr a certain sessin cde) Reprting GET /api/v1/reprts/cnnectins (list cnnectin reprts) PUT /api/v1/reprts/cnnectins/<rid> (change cnnectin reprt) DELETE /api/v1/reprts/cnnectins/<rid> (delete a cnnectin reprt) GET /api/v1/reprts/devices (list device reprts) Meetings Meeting types Scheduled meetings Instant meetings GET /api/v1/meetings (list all scheduled meetings) GET /api/v1/meetings/<mid> (get details f a meeting) GET /api/v1/meetings/<mid>/invitatin (retrieve invitatin infrmatin fr a scheduled meeting) POST /api/v1/meetings (create a new meeting) PUT /api/v1/meetings/<mid> (change details f a meeting) DELETE /api/v1/meetings/<mid> (delete a meeting) Cntacts GET /api/v1/cntacts (list all cntacts frm the cmputers & cntacts list) POST /api/v1/cntacts (add a new cntact) DELETE /api/v1/cntacts/<cid> (Delete a cntact) Devices GET /api/v1/devices (list all devices frm the cmputers & cntacts list) PUT /api/v1/devices/<did> (change device details) POST /api/v1/devices (add a new device) DELETE /api/v1/devices/<did> (delete a device) Plicy Management TeamViewer API - Dcumentatin Page 3 f 64

4 GET /api/v1/teamviewerplicies GET /api/v1/teamviewerplicies/<plicy_id> PUT /api/v1/teamviewerplicies/<plicy_id> DELETE /api/v1/teamviewerplicies/<plicy_id> Errrs HTTP respnse cdes JSON errr respnses Licensing Cntact Appendix A URLs fr cnnectins with devices URLs fr cnnectins with cntacts TeamViewer API - Dcumentatin Page 4 f 64

5 Changelg 1 Changelg Added new parameter ss_custmer_id t POST /api/v1/users (create new cmpany member) Added new parameter _language t PUT /api/v1/accunt (change accunt data) Added supprted languages t POST /api/v1/users (create new cmpany member) Versin scheme f API dcumentatin changed t align with the TeamViewer client releases. Last versin with ld scheme: First versin with new scheme: Rate limit fr Business, Premium and Crprate custmers changed frm 1 hur sliding windw t 24 hurs sliding windw. See 2.7 Rate limits. Added new user permissin AllwPasswrdChange. See Permissin names in API and Management Cnsle. Added return value t GET /api/v1/users (retrieve list f users). Added return value last_seen t GET /api/v1/devices (list all devices frm the cmputers & cntacts list) Added return value " _validated" t GET /api/v1/accunt (retrieve accunt data) Added return value user_id t GET /api/v1/cntacts (list all cntacts frm the cmputers & cntacts list) TeamViewer API - Dcumentatin Page 5 f 64

6 Intrductin 2 Intrductin 2.1 Definitins Name Supprter A user wh prvides supprt t the end custmer. This user must have a TeamViewer accunt. End Custmer A user wh des nt need t have a TeamViewer accunt. The user is in mst cases a custmer f the cmpany wh is using the API. Client The applicatin (r user, if the HTTP requests are typed in manually) that uses the API. 2.2 REST The TeamViewer API is a REST API which uses the already existing HTTP methds t create (POST), read (GET), change (PUT) r delete (DELETE) single items r a cllectin f items. The fllwing table shws the general use cases fr these HTTP methds. GET POST PUT DELETE Cllectin retrieve list f items in this cllectin create new item in this cllectin - - Single item retrieve item data - changes the item deletes this item The basic URI scheme fr all API functins is: The TeamViewer API can be fund at in the URI are nly allwed fr GET and DELETE. Generally there shuld be n need fr any parameters fr DELETE, thugh. POST and PUT need t have the parameters in the bdy frmatted as JSON r XML. TeamViewer API - Dcumentatin Page 6 f 64

7 Intrductin 2.3 IDs IDs are prefixed with a type in rder t make them mre distinguishable. The fllwing types are used: "u" - user ID "g" grup ID "m" meeting ID "s" sessin cde c cntact ID d device ID r remte cntrl ID, als referred t as TeamViewer ID in ther dcumentatins Reprts use a GUID and are nt prefixed. 2.4 Date frmat All dates and times fllw the ISO They shuld have the fllwing frmat: YYYY-MM- DD"T"HH:MM:SS"Z". Times are always in UTC unless stated therwise T13:42:55Z = 21st February 2013, 13:42:55 UTC 2.5 Number frmat Decimal numbers are returned in US English frmat, using a pint as decimal separatr. Digits are never gruped by a delimiter User permissins Permissin names in API and Management Cnsle The fllwing table shws the relatin between user permissins as they can be set in the Management Cnsle and the technical name that is used fr the API. Name in API Name in Management Cnsle ManageAdmins Manage administratrs and cmpany settings ManageUsers Manage users ShareOwnGrups Allw grup sharing TeamViewer API - Dcumentatin Page 7 f 64

8 Intrductin Name in API Name in Management Cnsle ViewAllCnnectins View all cnnectins ViewOwnCnnectins View wn cnnectins EditCnnectins Edit lgged cnnectins DeleteCnnectins Delete lgged cnnectins EditFullPrfile Allw full prfile mdificatin AllwPasswrdChange Allw passwrd change nly ManagePlicies Manage & Assign plicies AssignPlicies Assign plicies AcknwledgeAllAlerts View & acknwledge all alerts AcknwledgeOwnAlerts View & acknwledge wn alerts ViewAllAssets View all assets ViewOwnAssets View assets EditAllCustmMduleCnfigs Manage all custmizatins EditOwnCustmMduleCnfigs Manage wn custmizatins Nne <n permissin is set in cnsle> Permissin dependencies Sme permissins are depending n each ther and cannt be set individually, e. g. if a user has the permissin t ManageAdmins he als must have the permissin t ManageUsers. When these permissins are set in the Management Cnsle, the ther permissins are set autmatically. When setting permissins thrugh the API using a PUT r POST cmmand, all permissins must be included explicitly. The fllwing table shws the dependencies. TeamViewer API - Dcumentatin Page 8 f 64

9 Intrductin Name in API T set this right thrugh the API, these rights als have t be set Nne - ManageAdmins ManageUsers, ShareOwnGrups, EditFullPrfile, ViewAllCnnectins, ViewOwnCnnectins, EditCnnectins, DeleteCnnectins, ManagePlicies, AssignPlicies, Acknwledge- AllAlerts,AcknwledgeOwnAlerts, ViewAllAssets, ViewOwnAssets, EditAllCustmMduleCnfigs, EditOwnCustmMduleCnfigs ManageUsers ShareOwnGrups, EditFullPrfile, ViewAllCnnectins, ViewOwnCnnectins, EditCnnectins, DeleteCnnectins, ManagePlicies, AssignPlicies, AcknwledgeAllAlerts, Acknwledge- OwnAlerts, ViewAllAssets, ViewOwnAssets, EditAllCustmMdule- Cnfigs, EditOwnCustmMduleCnfigs ShareOwnGrups - ViewAllCnnectins ViewOwnCnnectins ViewOwnCnnectins - EditCnnectins - DeleteCnnectins - EditFullPrfile - AllwPasswrdChange - ManagePlicies AssignPlicies, AcknwledgeAllAlerts, AcknwledgeOwnAlerts AssignPlicies AcknwledgeAllAlerts, AcknwledgeOwnAlerts AcknwledgeAllAlerts AcknwledgeOwnAlerts AcknwledgeOwnAlerts - ViewAllAssets ViewOwnAssets ViewOwnAssets - EditAllCustmMduleCnfigs EditOwnCustmMduleCnfigs EditOwnCustmMduleCnfigs - TeamViewer API - Dcumentatin Page 9 f 64

10 Intrductin 2.7 Rate limits Rate limits apply per Accunt per API call and are based n the TeamViewer license. License Rate limit per API call Free 300 requests per hur Business 7,200 requests per 24 hurs Premium 14,400 requests per 24 hurs Crprate 36,000 requests per 24 hurs TeamViewer API - Dcumentatin Page 10 f 64

11 OAuth 2.0 Authrizatin 3 OAuth 2.0 Authrizatin 3.1 Rles & Terms Fr mre infrmatin abut OAuth 2.0, see and the fficial specificatin at Names used by the RFC and their meaning fr the TeamViewer API: resurce wner The user behind a TeamViewer accunt wh wants t access their resurces thrugh the API. resurce server Our servers where the API runs. client The applicatin, plug-in, script r user wh is making the API HTTP requests. authrizatin server In ur case that's the same servers that run the rest f the API. client ID A unique ID t identify the applicatin that wants t use the TeamViewer API. client secret A unique string nly knwn t the creatr f the client ID. authrizatin cde Cde used during the OAuth prcess t prve that an authrizatin request was granted in the Management Cnsle. access tken A tken that has t be used t access any API functin (except thse explicitly marked as nt requiring any access tkens). refresh tken A tken that can be used nce t btain a new access tken and a new refresh tken. 3.2 Registering an applicatin in the Management Cnsle Befre using any API functinality, yu need t register an applicatin in the Management Cnsle. When yu register the applicatin yu have t specify if yu want t use it fr yur wn accunt nly (private applicatin, als referred t as Script ) r if yu want t create an applicatin t be used by any TeamViewer user (public applicatin, als referred t as App ). In bth cases yu als specify if the applicatin will have access t the data f ne single accunt r t the data f the entire cmpany. TeamViewer API - Dcumentatin Page 11 f 64

12 OAuth 2.0 Authrizatin 3.3 Client/Applicatin-Types Script App User Access Access tken is created that can nly be used t access the user wh created the applicatin. Client ID is created when creating the applicatin. The Client ID can be used with OAuth t create an access tken fr the user granting access. Cmpany Access Access tken is created that can be used t access the cmpany f the user (=cmpany admin) wh created the applicatin. Client ID is created when creating the applicatin. The Client ID can be used with OAuth t create an Access-Tken t access the cmpany f the user (=cmpany admin) granting access. When yu register an applicatin fr yur wn use nly, yu will get an access tken that can be used directly fr any API functin that requires it. When yu register the applicatin fr thers t use as well, yu will get a Client ID. This Client ID is used in the OAuth prcess described belw. At the end f this prcess the applicatin will als have an access tken that must be used by the ther API functins. This access tken is tied t the accunt/cmpany that uses the applicatin, nt the cmpany that created the applicatin. If yu are using OAuth in yur applicatin and the applicatin was registered fr cmpany use, the user wh grants access t yur applicatin needs t be an administratr. The user wh registered the applicatin des nt have t be in a cmpany hwever. 3.4 Access Tken Permissins and Scpes Access tkens can be either issued fr a single user r fr a whle cmpany. Cmpany access tkens have t be created by an administratr f that cmpany. Besides this distinctin access tkens als have a number f permissins attached t them. This is called the scpe f the access tken. The fllwing table shws all available scpes. API functin Scpes Accunt (user level access nly) Accunt.Create, Accunt.Read, Accunt.Read , Accunt.Mdify, Accunt.Mdify , Accunt.MdifyPasswrd Grups Grups.Create, Grups.Read, Grups.Mdify, Grups.Share, Grups.Delete Users Users.CreateUsers, Users.CreateAdministratrs, Users.Read, Users.MdifyUsers, Users.MdifyAdministratrs Sessins Sessins.Create, Sessins.ReadAll, Sessins.ReadOwn, Sessins.MdifyAll, Sessins.MdifyOwn TeamViewer API - Dcumentatin Page 12 f 64

13 OAuth 2.0 Authrizatin Cnnectins Cnnectins.Read, Cnnectins.Mdify, Cnnectins.Delete Meetings (user level access nly) Meetings.Create, Meetings.Read, Meetings.Mdify, Meetings.Delete Devices & Cntacts (user level access nly) CntactList.Create, CntactList.Read, CntactList.Mdify, CntactList.Delete 3.5 The authrizatin prcess When using private Script Tkens, there is n need fr an authrizatin prcess. Access t the accunt/cmpany data thrugh the TeamViewer API is defined when creating the tken. The data that is accessed is the accunt r cmpany data f the user creating the tken. Nte that a Script Tken is still valid after changing the user s passwrd. Fr public Apps the case is different. Because these applicatins can be used by ther TeamViewer users, access t their data is cntrlled via OAuth 2.0. We distinguish between applicatin with access t user level data and cmpany level data. 3.6 User level access If a user starts an app that requires user level access fr the first time, TeamViewer will ask the user t grant a set f permissins t the app. This set f permissins was specified when creating the applicatin. The permissins are checked against the rights f the current user. If the applicatin asks fr permissins that exceed the rights f the user (e. g. the applicatin wants t edit cnnectin reprt entries whereas the user is nly allwed t view them), the permissins in questin are highlighted and a warning is displayed that sme parts f the applicatin may nt behave as intended because f the lacking user rights. In any case, the user may either chse t deny r t grant access t the applicatin. If access is granted, the app can access the user s data, as lng as the user s permissins allw. If user rights are changed later, the applicatin may be able t access mre data. 3.7 Cmpany level access T grant cmpany level access t an applicatin the user needs t have all required permissins. Unlike user level access it is nt pssible t grant access when sme permissins are missing. Als unlike user level access the rights f the user are nt relevant fr the app any mre after granting access. TeamViewer API - Dcumentatin Page 13 f 64

14 OAuth 2.0 Authrizatin 3.8 Authrizatin Endpint GET lgin.teamviewer.cm/auth2/authrize s t the authrizatin endpint must be made via HTTPS. The authrizatin endpint is used t interact with the resurce wner and therefre must be viewed in a brwser. Security best practice is t pen the authrizatin endpint in a ppup with address bar visible. respnse_type Must be cde. client_id Client ID, a unique string that identifies the applicatin. redirect_uri URI f the redirectin endpint. The client is redirected t this URI nce access has been granted. The value f this parameter must match the registered redirect URI. state (ptinal) Can be set if needed, and will be returned t the callback URI if it was set here. display Must be ppup. Redirectin Endpint The client is redirected t the redirectin endpint, which is specified when creating an applicatin in Management Cnsle, after the interactin with the authrizatin endpint is cmpleted. Values added t the redirect_uri: cde Cde that can be used t get an access tken. state (ptinal) same as the ne prvided as parameter. s an authrizatin cde frm the server. This cde is nly valid fr 10 minutes and shuld be used t btain an access tken. This is the nly functin that shuld nt be called directly frm a 3 rd party applicatin but it shuld be pened in a brwser where the user can grant access t the 3 rd party applicatin. : GET lgin.teamviewer.cmauth2/authrize?respnse_type=cde&client_id= ea4hdf3e9ec0543fx&redirect_uri=https%3a%2f%2fclient%2eexample%2ecm%2fcb POST /api/v1/auth2/tken (tken endpint) must be inside the bdy f the request and encded with the "applicatin/x-www-frm-urlencded" frmat. This is the nly exceptin where the bdy is nt JSON r XML. There are tw different requests fr this URI, ne t retrieve an access tken using an authrizatin cde and ne using a refresh tken. Authrizatin-Cde Grant: grant_type Must be authrizatin_cde. cde Authrizatin cde acquired frm the /auth2/authrize page. redirect_uri Must be the same value as in the previus call t /auth2/authrize. TeamViewer API - Dcumentatin Page 14 f 64

15 OAuth 2.0 Authrizatin Refresh-Tken: client_id Client ID, a unique string that identifies the applicatin. client_secret The client secret, which is knwn nly t the creatr f the applicatin. grant_type Must be refresh_tken. refresh_tken Refresh-tken frm a previus call. client_id Client ID, a unique string that identifies the applicatin. client_secret - The client secret, a unique string knwn nly t the creatr f the applicatin. access_tken Access tken t use with all further API calls. tken_type -methd used fr this access tken, currently nly bearer is used. expires_in Time in secnds until the access tken expires and needs t be refreshed. refresh_tken Refresh-Tken that needs t be used t get a new access tken when the ld access tken expires. ing a new access tken will als create a new refresh tken. The refresh tken becmes invalid after use r if the access tken is revked. s a new access tken, either by using the cde frm a previus authrizatin step r by using an existing refresh tken. Access tkens have a limited lifetime f 1 day. The respnse always has the Cache- Cntrl and Pragma fields (see example belw). Refresh tkens can nly be used nce. Fr this request the Cntent-Type header shuld be set t applicatin/x-www-frm-urlencded (as per OAuth 2 specificatin), hwever JSON/XML als wrks. (Authrizatin cde grant): POST /api/v1/auth2/tken HTTP/1.1 Hst: webapi.teamviewer.cm Cntent-Type: applicatin/x-www-frm-urlencded grant_type=authrizatin_cde&cde=splxlobezqqybys6wxsb&redirect_uri=https%3a%2f%2fc lient%2eexample%2ecm%2fcb&client_id= ea4hdf3e9ec0543fx (Authrizatin cde grant): HTTP/ OK Cache-Cntrl: n-stre Pragma: n-cache {"access_tken":" ytnfzfejr1zcsicmwp", "tken_type":"bearer", "expires_in":3600, "refresh_tken":"12854-zv3jokf0xg5qx2tlkwia" s using the access tken All API requests need t include the "Authrizatin" header if the API functin requires an access tken. TeamViewer API - Dcumentatin Page 15 f 64

16 OAuth 2.0 Authrizatin GET /api/v1/users HTTP/1.1 Hst: webapi.teamviewer.cm Authrizatin: Bearer YtnFZFEjr1zCsicMWp All examples in the fllwing sectins will have this header mitted but if an access tken is required the Authrizatin header field needs t be added t the request. If n access tken is given in the header, r the access tken is past its expiratin date, the return will have a WWW-Authenticate header field. fr n access tken, but access tken required: HTTP/ Unauthrized WWW-Authenticate: Bearer fr expired access tken: HTTP/ Unauthrized WWW-Authenticate: Bearer { "errr" : "tken_expired", "errr_cde" : 1, "errr_descriptin" : "The access tken expired" POST /api/v1/auth2/revke Nne Nne Revkes an access tken that was created using auth. The access tken has t be included in the header Authrizatin field. After revking it, it and its attached refresh tken cannt be used any lnger. POST /api/v1/auth2/revke HTTP/1.1 Hst: Authrizatin: Bearer YtnFZFEjr1zCsicMWp HTTP/ OK TeamViewer API - Dcumentatin Page 16 f 64

17 4 API Functins 4.1 Ping GET /api/v1/ping Nne tken_valid Is set t true if the prvided access tken is OK and the message is signed crrectly. In all ther cases the value is set t false. Access tkens are ptinal but will be verified if prvided. Scpe: Nne required. This functin can be used t check if the API is available. It can als be used t verify if the tken is valid. GET /api/v1/ping HTTP/ OK {"tken_valid":false 4.2 Accunt Management GET /api/v1/accunt (retrieve accunt data) Nne TeamViewer API - Dcumentatin Page 17 f 64

18 name The name f the user. The assciated address. Only returned if access tken has the Accunt.Read scpe. userid The user ID. cmpany_name (ptinal) The name f the cmpany that the user belngs t. _validated The validatin status f the accunt s address. Can be true r false. Only returned if access tken has the Accunt.Read scpe. _language The selected language f the user. User access tken. Scpe: Accunt.Read and (ptinally) Accunt.Read . Retrieves accunt infrmatin f the accunt assciated with the access tken. GET /api/v1/accunt HTTP/ OK { "userid": "u ", " ": "jde@example.cm", "name": "Jhn De", "cmpany_name": "Jhn s Cmpany" " _validated": true PUT /api/v1/accunt (change accunt data) name (ptinal) The name f the user. (ptinal) The assciated address. Nte that changing the address needs t be cnfirmed in the Management Cnsle first befre changes take effect. passwrd (ptinal) - A new passwrd fr this accunt. If passwrd is set, ldpasswrd must be set t the crrect value f the ld passwrd. ldpasswrd (ptinal) - The ld passwrd f this accunt _language (ptinal) Allws t set the language f the based n these values: aut, da, de, es, fr, it, nl, pt, en, bg, cs, el, fi, hr, hu, id, ja, k, lt, n, pl, r, ru, sk, sr, sv, th, tr, uk, vi, zh_cn, zh_tw. TeamViewer API - Dcumentatin Page 18 f 64

19 Nne. User access tken. Scpe:Accunt.Mdify, Accunt.Mdify r Accunt.MdifyPasswrd.. Changes accunt infrmatin f the accunt assciated with the access tken. PUT /api/v1/accunt { "name" : "Jhn Lcke" HTTP/ N Cntent 4.3 User Management License restrictins apply. Please see chapter Licensing fr further infrmatin GET /api/v1/users (retrieve list f users) (ptinal) Lists the user that has an exact match f the given address. This may als cntain a cmma separated list f addresses, allwing t query multiple users with a single call. name (ptinal) List all users that have the given string as part f their user name. permissins (ptinal) List all users with certain permissins. Multiple permissins can be separated by cmma and nly users having all the permissins will be listed in that case. (See fr a list f pssible values). full_list (ptinal) true: list cntains all inf fields abut the users, false (default): list cntains nly minimal inf abut the users Fr the minimal list: id user ID, needed t access/mdify that user. name Name f the user. address f the user. Fr the full list (additinally): permissins (ptinal) Cmma-separated list f permissins that this user has. (See fr a list f pssible values). TeamViewer API - Dcumentatin Page 19 f 64

20 active true if the accunt is active, false therwise. custm_quicksupprt_id (ptinal) The ID f the default custm QuickSupprt mdule fr this user. Omitted if value is aut. custm_quickjin_id (ptinal) The ID f the default custm QuickJin mdule fr this user. Omitted if value is aut. User r cmpany access tken. Scpe: Users.Read Lists all users in a cmpany. The list can be filtered with additinal parameters. The functin can als return a list cntaining all infrmatin abut the users. This data is the same as when using GET /users/uid fr each f these users. GET /api/v1/users?full_list=true HTTP/ OK { "users" : [ { "id" : "u ", "name" : "Mighty Administratr", "permissins" : "ManageAdmins, ManageUsers, ShareOwnGrups, EditFullPrfile, ViewAllCnnectins, ViewOwnCnnectins, EditCnnectins, DeleteCnnectins, ManagePlicies, AssignPlicies, AcknwledgeAllAlerts,AcknwledgeOwnAlerts, ViewAllAssets, ViewOwnAssets, EditAllCustmMduleCnfigs, EditOwnCustmMduleCnfigs", "active": true, " ": "admin@example.cm", { "id" : "u ", "name" : "Jhn De", "permissins" : "EditFullPrfile", " ": "user@example.cm" ] POST /api/v1/users (create new cmpany member) f that user. Will be used fr lgin. passwrd (ptinal) Predefined passwrd fr the user. Will be used fr lgin. The predefined passwrd is ptinal. If Single Sign-On is used, the passwrd parameter shuld be empty. ss_custmer_id (ptinal) The Custmer Identifier that is needed fr Single Sign-On. If the parameter is specified, newly created users are SSO-enabled and d nt need a TeamViewer accunt passwrd. Using this parameter requires a user access tken. TeamViewer API - Dcumentatin Page 20 f 64

21 permissins (ptinal) Cmma-separated list f permissins that this user has. See fr valid values and cmbinatins. If mitted the fllwing default permissins will be set: ShareOwnGrups, ViewOwnCnnectins, EditCnnectins, EditFullPrfile name Name f the new user. language Language cde fr the user. Will be used fr the welcme . Valid languages are: id, cs, da, de, en, es, fr, hr, it, lt, hu, nl, n, pl, pt, r, sk, sr, fi, sv, vi, tr, el, bg, uk, ru, th, k, zh_tw, zh_cn, ja DEPRECATED license_key (ptinal) License key f the license that will be assigned t the new user. If mitted, yur default license will be set. T assign a license t a user, it must have been added t the cmpany first. custm_quicksupprt_id (ptinal) The ID f the default custm QuickSupprt mdule fr this user. Defaults t aut if mitted. custm_quickjin_id (ptinal) The ID f the default custm QuickJin mdule fr this user. Defaults t aut if mitted. HTTP status cde 200 n success and a JSON cntaining the same data as GET /users/uid. The new URI fr that user will als be returned as part f the HTTP header. User r cmpany access tken. Scpe: Users.CreateUsers r Users.CreateAdministratrs. Creates a new user fr the cmpany. The data fr the new user will be returned as respnse t the POST. This shuld be the same as GET /users/uid, except that it will include the id as well. Yu will need t have the scpe Users.CreateAdministratrs t set the permissins ManageUsers r ManageAdmins. POST /api/v1/users { " " : "f@example.cm", "passwrd" : "abc!de#f3g2h3", "name" : "Jhn Michael Drian", "language" : "en", "permissins" : "EditFullPrfile" HTTP/ OK { "id" : "u456789", "name" : "Ted", "permissins" : "EditFullPrfile" TeamViewer API - Dcumentatin Page 21 f 64

22 4.3.3 GET /api/v1/users/<uid> (get infrmatin fr ne user) Nne This is the same as the full list fr GET /users. id User ID. Shuld be the same as in the URL. name Name f the user. permissins (ptinal) String list f permissins that this user has. See fr valid values. active true if the accunt is active, false therwise. custm_quicksupprt_id (ptinal) The ID f the default custm QuickSupprt mdule fr this user. Omitted if value is aut. custm_quickjin_id (ptinal) The ID f the default custm QuickJin mdule fr this user. Omitted if value is aut. address f the user. User r cmpany access tken. Scpe: Users.Read. Returns the infrmatin fr a single user. The infrmatin is the same as when using GET /users?full_list=true. GET /api/v1/users/u123 HTTP/ OK { "id" : " u123", " " : "user@example.cm", "name" : "Jhn De", "permissins" : "EditFullPrfile", "active" : true PUT /api/v1/users/<uid> (mdify user infrmatin) (ptinal) New f the user. A verificatin will be sent t the new address. name (ptinal) Real name f the user. TeamViewer API - Dcumentatin Page 22 f 64

23 permissins (ptinal) Cmma-separated list f permissins that this user has. See fr valid values and cmbinatins. passwrd (ptinal) Assign a new passwrd fr this user. active (ptinal) Activates r deactivates an accunt. DEPRECATED license_key (ptinal) License key f the license that will be assigned t the user. T assign a license t a user, it must have been added t the cmpany first. custm_quicksupprt_id (ptinal) The ID f the default custm QuickSupprt mdule fr this user. Set t aut if n specific mdule shuld be assigned. custm_quickjin_id (ptinal) The ID f the default custm QuickJin mdule fr this user. Set t aut if n specific mdule shuld be assigned. HTTP status cde 204 (N Cntent) n success. User r cmpany access tken. Scpe: Users.MdifyUsers r Users.MdifyAdministratrs. Changes infrmatin fr a selected user. Only the parts that need t be changed are needed in the request bdy. Security-Warning: An attacker can gain access t a user accunt either by changing the (+passwrd reset) r by changing the passwrd if he can steal the cmpany access tken. This makes the cmpany access tken equivalent t and passwrd fr ALL cmpany accunts with which an attacker can get the full Cmputer & Cntacts list (and nt just what is available ver the API). PUT /api/v1/users/u123 { "name" : "Jhn Lcke" HTTP/ N Cntent 4.4 Grup Management Accessing grups frm different users in a cmpany Imprtant nte: If yu are using a cmpany access tken, yu can use all the functins belw but have t prefix them with a user-lcatin. S "GET /grups" fr example becmes "GET /users/<uid>/grups". TeamViewer API - Dcumentatin Page 23 f 64

24 4.4.2 GET /api/v1/grups (list all available grups) (GET /api/v1/users/<uid>/grups fr cmpany access tken) name (ptinal) Grup name r part f the grup name shared (ptinal) True: list nly shared grups, i. e. grups where the current user is nt the wner. False: list nly nt shared grups, i. e. grups wned by the current user. If left ut bth types will be in the list. grups List f grups. id Grup ID name Name f the grup. shared_with (ptinal) List f users wh this grup is shared with. Can be mitted if empty. userid User ID f the user the grup is shared with. name Name f the user the grup is shared with. permissins Access-permissins f the user n this grup. Either read r readwrite. pending true if the user hasn't accepted the shared grup yet, therwise the field can be mitted. wner (ptinal) Owner f this grup. Omitted if the wner is the current user. userid User ID f the wner f this grup. name Name f the wner f this grup. permissins read, readwrite r wned. plicy_id (ptinal) ID f the plicy that is assigned t the grup. License restrictins apply, see chapter Licensing. User r cmpany access tken. Scpe: Grups.Read. Returns a list f grups. GET /api/v1/grups?name=test TeamViewer API - Dcumentatin Page 24 f 64

25 HTTP/ OK { "grups" : [ { "id" : "g53235", "name" : "Testing", "shared_with" : [ { "userid" : "u631645", "name" : "Ted", "permissins" : "read"], "permissins" : "wned", { "id" : "g ", "name" : "Test", "wner" : { "userid" : "u ", "name" : "Tester", "permissins" : "readwrite" ] POST /api/v1/grups (create a new grup) (POST /api/v1/users/<uid>/grups fr cmpany access tken) name Name f the new grup. plicy_id (ptinal) ID f the plicy that will be assigned t the grup. Must be a plicy ID. id Grup ID f the newly created grup. name Name f the new grup. This shuld be the same parameter as the input parameter. permissins Will always be wned, because the grup is nt yet shared at this pint. plicy_id (ptinal) ID f the plicy that is assigned t the grup. License restrictins apply, see chapter Licensing. User r cmpany access tken. Scpe: Grups.Create. Creates a new grup and returns its inf. POST /api/v1/grups { "name" : "Test", "plicy_id": "5d93f008-3b1f d5a68092" TeamViewer API - Dcumentatin Page 25 f 64

26 HTTP/ OK Lcatin: { "id" : "g ", "name" : "Test", "permissins" : "wned", "plicy_id": "5d93f008-3b1f d5a68092" GET /api/v1/grups/<gid> (get grup details) (GET /api/v1/users/<uid>/grups/<gid> fr cmpany access tken) Nne. id Grup ID name Name f the grup. shared_with (ptinal) List f users wh this grup is shared with. Only available if the user is wner f the grup. Will be mitted if empty. userid User ID f the user the grup is shared with. permissins Access-permissins f the user n this grup. Either read r readwrite. wner (ptinal) Owner f this grup. Will be mitted if the wner is the current user. userid User ID f the wner f this grup. name Name f the wner f this grup. permissins Access permissins fr the current user. read, readwrite r wned. plicy_id (ptinal) ID f the plicy that is assigned t the grup. License restrictins apply, see chapter Licensing. User r cmpany access tken. Scpe: Grups.Read. Returns inf fr ne grup. GET /api/v1/grups/g TeamViewer API - Dcumentatin Page 26 f 64

27 HTTP/ OK { "id" : "g ", "name" : "Test", "wner" : { "userid" : "u ", "name" : "Tester", "permissins" : "wned", "plicy_id": "5d93f008-3b1f d5a68092" PUT /api/v1/grups/<gid> (change grup details) (PUT /api/v1/users/<uid>/grups/<gid> fr cmpany access tken) name New name f the grup. plicy_id (ptinal) ID f the new plicy that will be assigned t the grup. Must be a plicy ID. License restrictins apply, see chapter Licensing. HTTP status cde 204 if change succeeded. User r cmpany access tken. Scpe: Grups.Mdify. Changes a grup. Right nw nly the name can be changed. PUT /api/v1/grups/g { "name" : "Test 123", "plicy_id": "5d93f008-3b1f d5a68092" HTTP/ N Cntent DELETE /api/v1/grups/<gid> (delete a grup) (DELETE /api/v1/users/<uid>/grups/<gid> fr cmpany access tken) TeamViewer API - Dcumentatin Page 27 f 64

28 Nne HTTP status cde 204 n success. User r cmpany access tken. Scpe: Grups.Delete Deletes an existing grup. If the grup is nt wned, but nly shared with the user's accunt it will just be unshared. DELETE /api/v1/grups/g HTTP/ N Cntent POST /api/v1/grups/<gid>/share_grup (share grup with ther user(s)) (POST /api/v1/users/<uid>/grups/<gid>/share_grup fr cmpany access tken) users List f users with whm the grup will be shared. userid User ID f ne f the users yu want t share the grup with. permissins Access-permissins f the user n this grup. Either read r readwrite. HTTP status cde 204. User r cmpany access tken. Scpe: Grups.Share. Shares a grup with the given users. Will nt change the share state with ther users, but it is pssible t verwrite the permissins fr existing shares. TeamViewer API - Dcumentatin Page 28 f 64

29 POST /api/v1/grups/g /share_grup { "users" : [ { "userid" : "u ", "permissins" : "read", { "userid" : "u51235", "permissins" : "readwrite" ] HTTP/ N cntent POST /api/v1/grups/<gid>/unshare_grup (unshare a grup frm certain users) (POST /api/v1/users/<uid>/grups/<gid>/unshare_grup fr cmpany access tken) users List f User IDs that this grup shuld nt lnger be shared with. HTTP status cde 204. User r cmpany access tken. Scpe: Grups.Share. Unshares a grup frm certain users. POST /api/v1/grups/g /unshare_grup { "users" : [ "u ", "u51235" ] HTTP/ N cntent TeamViewer API - Dcumentatin Page 29 f 64

30 4.5 Sessin Management GET /api/v1/sessins (list sessin cdes) grupid (ptinal) Filter by grup id. assigned_userid (ptinal) Filter by assigned_userid. state (ptinal) State f the sessin. Can be pen r clsed. By default nly pen sessins will be selected. States can be cmbined with a cmma. full_list (ptinal) true: Return all infrmatin fr the sessins. This is false by default. ffset (ptinal) Can cntain a sessin cde frm a previus request. The returned list will cntain sessin cdes after the ne specified as ffset. Fr the minimalistic list (full_list=false): sessins List f sessin cdes. cde Sessin cde. state State f the sessin. Can be "pen" r "clsed". nline Online state f the sessin. Can be true r false. grupid Grup ID where this sessin is stred under. sessins_remaining Number f sessin cdes left after the nes returned here. Will be mitted if there are n further sessin cdes. next_ffset Offset that can be used t get the next 1000 sessin cdes. Fr the full list (full_list=true): waiting_message Message displayed t the waiting end custmer. descriptin fr this sessin cde. end_custmer End Custmer inf name Name f the end custmer. f the end custmer. assigned_userid User ID f the user this sessin is assigned t. If sessin is unassigned, value is u0. assigned_at Date when the last user was assigned. end_custmer_link Link fr the end custmer. supprter_link Link fr the supprter. custm_api Custm field that can be used t stre an arbitrary string but is nly available t API functins. It is limited t 4000 characters. created_at Date when the sessin cde was created. valid_until Date until when the sessin cde is/was valid. clsed_at Date when the sessin was clsed. User r cmpany access tken. Scpe: Sessins.ReadAll r Sessins.ReadOwn. TeamViewer API - Dcumentatin Page 30 f 64

31 Lists sessins. If n filters are given it will list all sessins in the active accunt (user access tken) r all sessins frm all accunts (cmpany access tken). A single request will return a maximum f 1000 sessin cdes. T get the next 1000 sessin cdes, repeat the same request with the ffset parameter set t the value frm next_ffset. Sessin cdes will be srted by the created_at date frm new t ld. GET /api/v1/sessins?grupid=g &full_list=true HTTP/ OK {"sessins" : [ {"cde" : "s ", "grupid" : "g ", "descriptin" : "Hell, I have an issue with my printer, can yu please assist?", "end_custmer" : { "name" : "Peter Niedhelp", " " : "helpme@example.cm", "assigned_userid" : "u ", "end_custmer_link" : " "supprter_link" : " "custm_api" : "{ "ticket_id" : "535824" ", ] POST /api/v1/sessins (create new sessin cde) valid_until (ptinal) Date when sessin cde becmes invalid. Will default t 24h frm nw when n date is given. grupid (partially required) ID f the grup the sessin will be inserted int. The grup can be in a different accunt when the API user has access t it. Either this r grupname must be set. Fr applicatins with cmpany level access, this parameter is required. grupname (partially required) Name f the grup the sessin cde will be inserted int. Either this r the grupid parameter must be set. If n grup exists with that name a new grup will be created. If bth grupid and grupname are set, bth have t pint t the same grup. Otherwise an errr is returned. waiting_message (ptinal) Message displayed t the waiting end custmer. descriptin (ptinal) fr the new sessin cde. end_custmer (ptinal) End custmer inf. name (ptinal) Name f the end custmer. Maximum length is 100 characters. (ptinal) f the end custmer. Maximum length is 254 characters. assigned_userid (ptinal) User ID f the user this sessin cde will be assigned t. If nt set, sessin cde will be assigned t the user wh created the sessin cde. If set t u0, sessin is unassigned. custm_api (ptinal) Custm field that stres any arbitrary string (such as JSON r XML) but is nly available t API functins. It is limited t 4000 characters. TeamViewer API - Dcumentatin Page 31 f 64

32 cde Newly created sessin cde. state State f the sessin. Can be pen r clsed. grupid Grup ID where this sessin is stred in. waiting_message Message displayed t the waiting end custmer. descriptin fr this sessin cde. end_custmer End custmer inf name Name f the end custmer. f the end custmer. assigned_userid User ID f the user this sessin cde is assigned t. If the sessin cde is nt assigned the value will be u0. assigned_at Date when the last user last assigned. end_custmer_link Link fr the end custmer. supprter_link Link fr the supprter. custm_api Custm field that stres any valid JSON/XML bject (max 4000 characters) and is nly visible fr API users. created_at Date when the sessin cde was created. valid_until Date when sessin cde becmes invalid. User r cmpany access tken. Scpe: Sessins.Create. Creates a new sessin cde. A sessin cde will always be stred in a grup, s either the grupid r grupname parameter must be set. Sessin cdes will expire after 24h if n valid_until date is set. (with user/cmpany access tken) POST /api/v1/sessins {"grupid" : "g ", "descriptin" : " I have aprblemwith myspace bar.", "end_custmer" : { "name" : "Max" TeamViewer API - Dcumentatin Page 32 f 64

33 HTTP/ OK Lcatin: {"cde" : "s ", "state" : "pen", "grupid" : "g ", "end_custmer" : { "name" : "Max", "descriptin" : "I have aprblemwith myspace bar.", "assigned_userid" : "u ", "end_custmer_link" : " "supprter_link" : " "valid_until" : " T12:03:29Z" GET /api/v1/sessins/<cde> (get inf abut a certain sessin cde) Nne cde Sessin cde. state State f the sessin. Can be pen r clsed. nline Online-state f the sessin. Can be true r false. grupid Grup ID where this sessin is stred in. waiting_message Message displayed t the waiting end custmer. descriptin fr this sessin cde. end_custmer End custmer inf name Name f the end custmer. Maximum length is 100 characters. f the end custmer. Maximum length is 254 characters. assigned_userid User ID f the user this sessin cde is assigned t. end_custmer_link Link fr the end custmer. supprter_link Link fr the supprter. custm_api Custm fields, this stres any arbitrary string but is nly available t API functins. It is limited t 4000 characters. valid_until Date until when the sessin cde is/was valid. created_at Date when the sessin cde was created. assigned_at Date when the last user last assigned. clsed_at Date when the sessin was clsed. User r cmpany access tken. Scpe: Sessins.ReadAll r Sessins.ReadOwn. Returns infrmatin fr ne sessin cde. It will return exactly the same data that a POST t /sessins wuld return except that sme f the fields may have changed values. TeamViewer API - Dcumentatin Page 33 f 64

34 GET /api/v1/sessins/s HTTP/ OK {"cde" : "s ", "state" : "pen", "grupid" : "g ", "waiting_message" : "", "descriptin" : "HELP!!!11", "end_custmer" : { "name" : "Max", " " : "", "assigned_userid" : "u ", "end_custmer_link" : " "supprter_link" : " PUT /api/v1/sessins/<cde> (mdify inf fr a certain sessin cde) grupid (ptinal) Grup ID where this sessin will be mved t. grupname (ptinal) Grup name where this sessin will be mved t. If bth grupname and grupid are set, the grup with the specified ID must have the specified name. Otherwise an errr is returned. This parameter can nly be used by applicatins with user-level access. waiting_message (ptinal) Message displayed t the waiting end custmer. descriptin (ptinal) fr this sessin cde. end_custmer (ptinal) End custmer inf name (ptinal) Name f the end custmer. (ptinal) f the end custmer. assigned_userid (ptinal) User ID f the user t assign this sessin t. Set t u0 t unassign sessin. custm_api (ptinal) Custm fields, this stres any arbitrary string but is nly available t API functins. It is limited t 4000 characters. state (ptinal) State f the sessin. Can be "pen" r "clsed". HTTP status 204 if changes succeeded. User r cmpany access tken. Scpe: Sessins.MdifyAll r Sessins.MdifyOwn. Mdifies an existing sessin cde. TeamViewer API - Dcumentatin Page 34 f 64

35 PUT /api/v1/sessins/s {"descriptin" : "Still nt wrking." HTTP/ N Cntent 4.6 Reprting License restrictins apply. Please see chapter Licensing fr further infrmatin GET /api/v1/reprts/cnnectins (list cnnectin reprts) username (ptinal) Filter by user name f the persn wh started the cnnectin. userid (ptinal) Filter by user ID f the persn wh started the cnnectin. grupid (ptinal) Filter by grup ID where the target device r user was in. devicename (ptinal) Filter by target device name. Set t unnamed_device t nly return results fr unnamed devices. Only available if yu are using a user access tken. deviceid (ptinal) Filter by device ID. frm_date (ptinal) First start_date fr all listed cnnectins. Parameter must cntain a date and can als cntain a time. If n time is specified it defaults t 00:00:00Z. Cnnectins with start_date equal t frm_date are included in the results. t_date (ptinal) Last start_date fr all listed cnnectins. Parameter must cntain a date and can als cntain a time. If n time is specified it defaults t 00:00:00Z. Cnnectins with start_date equal t t_date are excluded frm the results. ffset_id (ptinal) All returned reprts will fllw the reprt-id given in this field. The given reprt-id is excluded frm the results. has_cde (ptinal) Filters ut reprts that have n sessin cde if true r that have a sessin cde if false. If the parameter is left ut bth types will be returned. Additinal parameters fr cnnectins that were dne with a sessin cde: sessin_cde (ptinal) If specified the respnse will cntain nly cnnectins fr this sessin cde. recrds List f remte cntrl cnnectins id Reprt-ID userid User ID f the persn wh started the cnnectin. username User name f the persn wh started the cnnectin. cntact_id (ptinal) Cntact ID f the target. The Cntact ID is returned nly fr cnnectins made t cntacts. TeamViewer API - Dcumentatin Page 35 f 64

36 deviceid TeamViewer ID f the target device. devicename (ptinal) Device name f the target device. Only returned if yu are using a user access tken. grupid ID f the grup where the device is currently lcated. grupname Name f the grup where the device is currently lcated. start_date Start date and time f the cnnectin. end_date End date and time f the cnnectin. fee (ptinal) Csts fr the cnnectin. currency (ptinal) Currency fr the fee field. billing_state Can be Bill, Billed r DNtBill. ntes (ptinal) Ntes fr this cnnectin. recrds_remaining (ptinal) Number f recrds after the nes listed here. Can be mitted if there are n mre reprts left. next_ffset (ptinal) ID f the last returned reprt in this respnse. Can be used as ffset_id in a fllw-up request t get the next set f cnnectin reprts. Additinal return parameters when the cnnectin was dne with a sessin cde recrds assigned_userid User ID f the user this sessin cde is assigned t. assigned_at Date when the sessin cde was last assigned t anther user. sessin_cde Sessin cde. sessin_created_at Date when the sessin cde was created. valid_until Date until when the sessin cde is/was valid. sessin_nte f the Service Case. custm_api Custm fields, this stres any arbitrary string but is nly available t API functins. It is limited t 4000 characters. end_custmer name (ptinal) Name f the end custmer. (ptinal) address f the end custmer. feedback (ptinal) If feedback was enabled but custmer did nt prvide feedback, an empty bject is returned. sessin_rating (ptinal) Sessin rating frm custmer (integer, higher is better). user_cmment (ptinal) Cmment n the sessin frm custmer. User r cmpany access tken. Scpe: Cnnectins.Read. Returns a list f cnnectin reprts. The list is limited t 1000 reprts per request. If there are mre reprts the reprts_remaining field will tell yu hw many. The next_ffset field will cntain the ffset ID t get the next 1000 (r less) reprts and shuld be used as ffset_id parameter fr the next request. If yu want t get cnnectins fr a single day r multiple days, use the first day at 0:00 fr the frm_date parameter and the day after the last day at 0:00 fr the t_date parameter. TeamViewer API - Dcumentatin Page 36 f 64

37 GET /api/v1/reprts/cnnectins?username=adam HTTP/ OK {"recrds" : [ { "id" : "B144268F-5A3A A8F4598B0125", "username" : "Adam", "userid" : "u ", "devicename" : "Server 15", "deviceid" : " ", "start_date" : " T19:20:30Z", "end_date" : " T194014Z", "bill" : "0.00", "currency" : "EUR", "billing_state" : "Bill", "ntes" : "fixed webserver", { "id" : "CAB5E30E-7A51-4F74-A9AE-089EE206D220", "username" : "Adam", "userid" : "u ", "devicename" : "Server 12", "deviceid" : " ", "start_date" : " T144011Z", "end_date" : " T151324Z", "bill" : "0.00", "currency" : "EUR", "billing_state" : "DNtBill", "ntes" : "installed Windws updates", { "id" : "F846B F00-BEC0-258D12A6C0BE", "username" : "Adam", "userid" : "u ", "devicename" : "Server 12", "deviceid" : " ", "start_date" : " T152004Z", "end_date" : " T152351Z", "bill" : "0.00", "currency" : "EUR", "billing_state" : "DNtBill", "ntes" : "server rebted and running again" ] PUT /api/v1/reprts/cnnectins/<rid> (change cnnectin reprt) billing_state (ptinal) Can be Bill, Billed r DNtBill. ntes (ptinal) Ntes fr this cnnectin. HTTP status cde 204. TeamViewer API - Dcumentatin Page 37 f 64