API Documentation
Introduction

Introduction

API Root Endpoint

https://assist.zoho.eu/api/v2

Integrate Zoho Assist with third party applications and websites using Zoho Assist APIs. Built using REST API, requests made to resource's URI will elicit a response in JSON format. You can build on our programmatic base to develop new applications or to integrate Zoho Assist with existing websites.

A wide range of HTTP clients can be integrated as it is a HTTP based web API.

Every resource is exposed as a URL. The URL of each resource can be obtained by accessing the API Root Endpoint.

Getting Started

Example

$ curl -X GET 'https://assist.zoho.eu/api/v2/user' \ -H Authorization: Zoho-oauthtoken 1000.45928a488f1e453626a93e9816.384eb5e2d96c928a4fcff88f1e452be9

All Zoho Assist APIs require a minimum of one mandatory header.

Authorization - Authentication request URL parameter.

Authentication

All Zoho Assist APIs needs to be authenticated using an oauth token.

OAuth 2.0 is an open authorization protocol which grants third party applications limited access to user accounts on an HTTP service. The authentication and authorization process is facilitated only between the end-user and the HTTP service. Zoho APIs use OAuth 2.0 to provide dependable security for your application data. It delegates authorization and authentication for web and desktop applications, and mobile devices.

You can abtain an OAuth token by following the steps mentioned below:

  1. Register your application
  2. Get an authorization grant
  3. Get an access token

1. Register your application

Before integrating Zoho APIs with your application using OAuth, you must register your application with Zoho. This can be done through the developer console of your Zoho account, where you will have to provide details regarding your application like Name , Website , Redirect URI, or Callback URL. Once the authorization is approved or denied, the user will be redirected to the callback URL specified at the time of registration.

Once your application is registered, the service will issue a client ID and a client secret. Client ID is used by Zoho to verify the identity of the application and has a public visibility. Client secret is used to authorize the appropriate resources that can be accessed by the authenticated application. Client secret will be known only to Zoho APIs and the authenticated application.

Sample Response

On calling the api, it will redirect to the redirect uri given with the authorization grant appended to it like below:
https://app.example.com/oauth?state=tempstate&code=1000.47b8fa1a1676bda5da938decdf0cf0d6.d3f48797707de05fcac81d135dc7b6c0

2. Get an authorization grant

URL : https://accounts.zoho.eu/oauth/v2/auth

Params :

Available Scopes :

Scopes Scope operations available
userapi ZohoAssist.userapi.READ
sessionapi ZohoAssist.sessionapi.CREATE
unattended.computer ZohoAssist.unattended.computer.READ
ZohoAssist.unattended.computer.UPDATE
ZohoAssist.unattended.computer.DELETE
unattended.group ZohoAssist.unattended.group.READ
ZohoAssist.unattended.group.CREATE
ZohoAssist.unattended.group.UPDATE
ZohoAssist.unattended.group.DELETE
reportapi ZohoAssist.reportapi.READ

Actions under each scope :

1. userapi

2. sessionapi

3. unattended.computer

4. unattended.group

5. reportapi

Sample Response

{ "expires_in": 3000, "refresh_token": "1000.4038qw5a8a5af1234ce920a45sx388a6.a450db33ca9e80701b1a23c8fe98e62e", "access_token": "1000.c656b09869cfef3be0ca145e44143fa9.a11f43090a54d71dc0797ec92bf34b9e" }

3. Get an access token

After getting the authorization grant, post it to the below API to get the access token and the refresh token.

URL : https://accounts.zoho.eu/oauth/v2/token

Params :

HTTP Methods

Using GET method, you can retrieve data for a particular instance from the resource. To get a list of customers
$ curl -X GET 'https://assist.zoho.eu/api/v2/user' \ -H Authorization: Zoho-oauthtoken 1000.45928a488f1e453626a93e9816.384eb5e2d96c928a4fcff88f1e452be9

Zoho Assist API uses appropriate HTTP verbs for every action.

Method Description
GET Used for retrieving resources.
POST Used for creating resources and performing resource actions.
PUT Used for updating resources.
DELETE Used for deleting resources.

Response

Response Structure

The response structure for the assist API follows the below format.
{ "resource_type" : "/api/v2/user" "representation":{ "...":"..." } }

Request Example

$ curl -X GET 'https://assist.zoho.eu/api/v2/user' \ -H Authorization: Zoho-oauthtoken 1000.45928a488f1e453626a93e9816.384eb5e2d96c928a4fcff88f1e452be9

Responses will be in the JSON format.

Node Name Description
representation Response of the invoked API.
resource_type Resource type of invoked API.




















Errors

Request Example

$ curl -X GET 'https://assist.zoho.eu/api/v2/user' \ -H Authorization: Zoho-oauthtoken 1000.45928a488f1e453626a93e9816.384eb5e2d96c928a4fcff88f1e452be9

Response Example

HTTP/1.1 404 Not Found Content-Type: application/json;charset=UTF-8 { "error":{ code:1009, message:"error message" } }

Zoho Assist uses HTTP status codes to indicate success or failure of an API call. In general, status codes in the 2xx range means success, 4xx range means there was an error in the provided information, and those in the 5xx range indicate server side errors. Commonly used HTTP status codes are listed below.

HTTP Status Codes

Status Code Description
200 OK
201 Created
400 Bad request
401 Unauthorized (Invalid AuthToken)
404 URL not found
405 Method not allowed (Method you have called is not supported for the invoked API)
429 Rate limit exceeded (API usage limit exceeded)
500 Internal error

Pagination

Example

$ curl -X GET 'https://assist.zoho.eu/api/v2/reports?index=1&count=25' \ -H Authorization: Zoho-oauthtoken 1000.45928a488f1e453626a93e9816.384eb5e2d96c928a4fcff88f1e452be9 { "representation": [ {...}, {...} ], "page": { "next": "next_page_url", "first": "first_page_url", "last": "last_page_url" }, "total_count": 150, "resource_type": "module" }

Zoho Assist provides APIs to retrieve lists of reports, computers and other resources. The resources will be paginated using index and count.By default, index will be 1 and count will be 20. The pagination information will be included in the listed API response under the node name page.

Users

Users

Users are the technicians that are a part of an organization in Zoho Assist.

Example

{ "request_params": {}, "response_params": { "zuid": 4231895, "zsoid": 4528561, "org_name": "Zoho Assist", "license_type": "FREE|TRIAL|LICENSED", "edition": "FREE|STANDARD|PROFESSIONAL", "count": 5, "is_enabled": true, "features": [ {} ] } }

Attribute

request_params
object
response_params
object
zuid
long
Zoho unique ID of the particular User.
zsoid
long
Organization ID of the user.
org_name
string
Organization name of the user.
license_type
string
License type of the user.
edition
string
License edition of the user.
count
long
License count of the user.
is_enabled
boolean
Whether support or access is enabled.
features
list
Features enabled for user according to license and edition.

Get User Info

Get User Info

This API fetches the details of an existing user in Zoho Assist.

GET /user

Request Example

  
$ curl https://assist.zoho.eu/api/v2/user -X GET -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "zuid": 4231895, "org_details": { "zsoid": 4528561, "org_name": "Zoho Assist" }, "remote_support_license": { "license_type": "FREE|TRIAL|LICENSED", "edition": "FREE|STANDARD|PROFESSIONAL", "count": 5, "is_enabled": true, "features": [ {...} ] }, "remote_access_license": { "license_type": "FREE|TRIAL|LICENSED", "edition": "FREE|STANDARD|PROFESSIONAL", "count": 5, "is_enabled": true, "features": [ {...} ] } }

Session

Session

This API allows you to create a remote support or screen sharing session.

Example

{ "request_params": { "customer_email": "john@zylker.com" }, "response_params": { "customer_url": "https://assist.zoho.eu/join?role=A&key=880567893", "technician_url": "https://assist.zoho.eu/assist-start?key=880567893&viewer=html", "session_id": "880567893" } }

Attribute

request_params
object
customer_email
string
Customer Email to whom the join invitation is to be sent.
type
string
Session type for which session key havs to be created.
computer_id
string
Urs Key to create unattended session key.
response_params
object
customer_url
string
Join URL that will be received in response.
technician_url
string
Session start URL for technician.
session_id
string
Session ID created.

Create a session

Create a session

This API allows you to create a remote support or screen sharing session.

POST /session

Request Example

  
$ curl https://assist.zoho.eu/api/v2/session -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d 'customer_email=john@zylker.com&type=rs';

Response Example

  
HTTP/1.1 200 OK For Remote Support, Content-Type:application/json;charset=UTF-8 { "resourse_type": "session", "representation": { "customer_url": "https://assist.zoho.eu/join?role=A&key=880567893", "technician_url": "https://assist.zoho.eu/assist-start?key=880567893&viewer=html", "session_id": "880567893" } } For Screen Sharing, Content-Type:application/json;charset=UTF-8 { "resourse_type": "session", "representation": { "customer_url": "https://assist.zoho.eu/demo-viewer.do?role=A&key=880567893&d=7bc42c06b0d76ff8b81dfa0b6bedb6a17aa542c918371", "technician_url": "https://assist.zoho.eu/presenter/880567893", "session_id": "880567893" } }

ARGUMENTS

customer_email
Optional
Customer Email to whom the join invitation is to be sent.
type
Optional
Default value will be rs. Allowed Values [rs | dm], where rs is Remote Support and dm is Screen Sharing.
computer_id
Optional
URS(unattended remote support) key to initiate an unattended access session.

Unattended Computers

Unattended Computers

Unattended computers are those computers you can take control of even if the customer isn't present at the remote end.

Example

{ "request_params": { "index": 1, "count": 20, "urs_key": "5FLO904GT32E655C", "sort": true, "field": "status", "q": "dell", "status": "offline", "group_id": "c956bdrtfyguhijn7a32c84d256789ba6", "group": "London", "nick_name": "Dell-5" }, "response_params": { "key": "5F262A29CE655C", "computer_name": "zmeeting-w7-32-2", "nick_name": "EditedName", "status": "offline", "last_online": 1490205071269, "created_time": 1495522736423, "os_name": "windows", "os_fullname": "windows", "os_version": "6.3", "mac_address": "F48E38D3FF79", "serial_number": "00110-12370-75555-AAAEM", "computer_fullname": "Dell-097623", "last_accessed_time": 1490203351681, "last_accessed_by": "naveenkumar.ds@zohocorp.com", "creator_email": "malcolm.h@zylker.com", "owner": true } }

Attribute

request_params
object
index
long
Position of computer in the list.
count
long
Total number of computers in the list.
urs_key
string
Unattended computer key
sort
boolean
Whether sorting needed. Allowed values: [true | false]
field
string
Sorting field. Allowed Values:[ computer | status ]
q
string
Search string for unattended computer
status
string
Get status of unattended computer. Allowed Values:[online|offline|waiting|busy|blocked|deleted]
group_id
string
Get unattended computer in group.
group
boolean
To get unattended group details in response.
nick_name
string
Nick name of unattended computers
response_params
object
key
string
URS key
computer_name
string
Computer name
nick_name
string
Nick name of unattended computers
status
string
Get status of unattended computer. Allowed Values:[online|offline|waiting|busy|blocked|deleted]
last_online
long
Last access time
created_time
long
Created time of group
os_name
string
OS name for unattended computers. Allowed Values:[windows|mac]
os_fullname
string
OS Full name of unattended computers
mac_address
string
Mac address of unattended computers
serial_number
string
Serial number of unattended computers
computer_fullname
string
Full name of computer
last_accessed_time
long
Last access time
last_accessed_by
string
Email id of techinician who accessed the unattended computer last.
creator_email
string
Email id of techinician who added the unattended computer.
owner
boolean
Owner of unattended computer

Get Unattended Computer

Get Unattended Computer

This API fetches the details of unattended computers configured in Zoho Assist.

GET /unattended_computer

Request Example

  
$ curl https://assist.zoho.eu/api/v2/unattended_computer -X GET -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d 'index=1&count=20&sort=true&field=status&group=true'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "representation": { "computer": [ { "key": "5F262A29CE655C", "computer_name": "zmeeting-w7-32-2", "nick_name": "EditedName", "status": "offline", "last_online": 1490205071269, "created_time": 1495522736423, "os_name": "windows", "os_fullname": "windows", "service_pack": "Service Pack", "serial_number": "122ed4qwff56782fvvfs7878", "computer_fullname": "Dell-097623", "last_accessed_time": 1490203351681, "creator_email": "malcolm.h@zylker.com", "owner": true } ], "groups": [ { "created_time": 1495522736423, "group_name": "London", "group_id": "c956bdrtfyguhijn7a32c84d256789ba6", "computer_count": 5, "created_by": "malcolm.h@zylker.com" } ] }, "page": { "next": "https://assist.zoho.eu/api/v2/unattended_computer?count=100&all=true&sort=true&field=status&os_type=all&status=&group=true", "first": "https://assist.zoho.eu/api/v2/unattended_computer?count=100&all=true&sort=true&field=status&os_type=all&status=&group=true", "last": "https://assist.zoho.eu/api/v2/unattended_computer?count=100&all=true&sort=true&field=status&os_type=all&status=&group=true" }, "resource_type": "unattended_computer" }

ARGUMENTS

index
Optional
Position of computer in the list.
count
Optional
Count for number of computers in response.
urs_key
Optional
Unattended computer key
sort
Optional
Whether sorting needed. Allowed values: [true | false].
field
Optional
Sorting field. Allowed Values:[ computer | status ].
q
Optional
Search string for unattended computer.
status
Optional
Get status of unattended computer. Allowed Values:[online|offline|waiting|busy|blocked|deleted].
group_id
Optional
Get unattended computer in group.
group
Optional
Get unattended computer in group.
os_type
Optional
OS type for unattended computers. Allowed Values:[all|windows|mac].

Update Unattended Computer

Update Unattended Computer

Using this API, you can update the existing computer details.

PUT /unattended_computer

Request Example

  
$ curl https://assist.zoho.eu/api/v2/unattended_computer -X PUT -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d '{"urs_key": "5FLO904GT32E655C","nick_name": "EditedName"}'

Response Example

  
HTTP/1.1 200 OK

ARGUMENTS

urs_key
Required
Unattended computer key
nick_name
Optional
Nick name of unattended computers

Delete Unattended Computer

Delete Unattended Computer

Delete unattended computers using this API.

DELETE /unattended_computer

Request Example

  
$ curl https://assist.zoho.eu/api/v2/unattended_computer -X DELETE -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d "urs_key=5FLO904GT32E655C";

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "representation": { "undo_code": "3d110e20e5ca737d28aa8f7f80bb68829916027bb4845bb7b57db23dae4820b1" }, "resource_type": "unattended_computer" }

ARGUMENTS

urs_key
Required
Unattended computer key

Unattended Groups

Unattended Groups

Unattended computers in your organization can be categorized into various groups in Zoho Assist.

Example

{ "request_params": { "name": "London", "id": "f489c9ef73ce0d4823fb6747d41c1d60", "q": "Dell-42810" }, "response_params": { "created_time": 1495522736423, "created_by": "malcolm.h@zylker.com", "group_id": "f412c9ef74567vy23fb6747fghvbd78d60", "group_name": "London" } }

Attribute

request_params
object
name
string
Unattended group name
id
string
Unattended group ID
q
string
Unattended computer name in that group
response_params
object
created_time
long
Created time of group
created_by
string
group_id
string
Group ID
group_name
string
Group name

Get Unattended Group

Get Unattended Group

This API fetches the details of existing groups in Zoho Assist.

GET /unattended_computer/group

Request Example

  
$ curl https://assist.zoho.eu/api/v2/unattended_computer/group -X GET -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d "q=Dell-42810";

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "resource_type": "group", "representation": [ { "created_time": 1495522736423, "created_by": "malcolm.h@zylker.com", "group_id": "f412c9ef74567vy23fb6747fghvbd78d60", "group_name": "London", "computer_count": 5 }, { "created_time": 1595522736423, "created_by": "john.m@zylker.com", "group_id": "12410c9bf74vv7vl23fff747fghtuv78d60", "group_name": "US", "computer_count": 25 } ] }

ARGUMENTS

q
Optional
Unattended computer name in that group

Create Unattended Group

Create Unattended Group

This API allows you to create a new group in Zoho Assist.

POST /unattended_computer/group

Request Example

  
$ curl https://assist.zoho.eu/api/v2/unattended_computer/group -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d "name=London"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "resource_type": "group", "representation": { "created_time": 1495522736423, "created_by": "malcolm.h@zylker.com", "group_id": "f412c9ef74567vy23fb6747fghvbd78d60", "group_name": "London" } }

ARGUMENTS

name
Required
Unattended group name

Update Unattended Group

Edit Unattended Group

Using this API, you can update the existing group details.

PUT /unattended_computer/group

Request Example

  
$ curl https://assist.zoho.eu/api/v2/unattended_computer/group -X PUT -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d '{"id": "f489c9ef73ce0d4823fb6747d41c1d60","name": "EditedName"}'

Response Example

  
HTTP/1.1 200 OK

ARGUMENTS

id
Required
Unattended Group ID/div>
name
Required
Unattended Group Name

Delete Unattended Group

Delete Unattended Group

Delete existing unattended computer groups using this API.

DELETE /unattended_computer/group

Request Example

  
$ curl https://assist.zoho.eu/api/v2/unattended_computer/group -X DELETE -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d "id=f489c9ef73ce0d4823fb6747d41c1d60"

Response Example

  
HTTP/1.1 204 No Content

ARGUMENTS

id
Required
Unattended group ID

Reports

Reports

Reports gives you an account of all remote support, screen sharing and unattended access sessions conducted from Zoho Assist. 

Example

{ "request_params": { "type": "all", "fromdate": "1518546600000", "todate": "1519151400000", "email": "john@zohcorp.com", "index": 1, "count": 20 }, "response_params": { "total_count": 29, "viewer_os": "Mac", "viewer_ipaddress": "121.244.91.19", "viewer_email": "david.w@zylker.com", "agent_os": "Mac", "agent_ipaddress": "45.123.3.250", "agent_email": "david.w@zylker.com", "start_time": 1481369000053, "end_time": 1481369155546, "duration": "155493", "display_name": "Frida", "session_id": 706174884, "session_type": "Remote Support", "session_owner_email": "frida.m@zylker.com" } }

Attribute

request_params
object
type
string
Session type. Allowed values:[rs|URS|DM|all].
fromdate
long
Unix Timestamp
todate
long
Unix Timestamp
email
string
To fetch reports conducted by specific technician.
index
long
Page count
count
long
Number of rows per page.
response_params
object
total_count
long
Total count of session reports.
viewer_os
string
OS type of the viewer.
viewer_ipaddress
string
IP address of viewer.
viewer_email
string
Email id of viewer.
agent_os
string
OS type of agent.
agent_ipaddress
string
IP address of agent.
agent_email
string
Email id of the agent.
start_time
long
Start time of session.
end_time
long
End time in long (Unix Timestamp).
duration
string
Duration of session.
display_name
string
Display name
session_id
long
Session key
session_type
string
Session type
session_owner_email
string
Owner of session

Get Session Reports

Get Session Reports

This API fetches you the reports of previously conducted sessions.

GET /reports

Request Example

  
$ curl https://assist.zoho.eu/api/v2/reports -X GET -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d "index=1&count=20&type=all&fromdate=1518546600000&todate=1519151400000&email=john@zohcorp.com"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "total_count": 29, "resource_type": "report", "representation": [ { "viewer_os": "Mac", "viewer_ipaddress": "121.244.91.19", "viewer_email": "david.w@zylker.com", "agent_os": "Mac", "agent_ipaddress": "45.123.3.250", "agent_email": "mark.k@gmail.com", "start_time": 1481369000053, "end_time": 1481369155546, "duration": "155493", "display_name": "Mark", "session_id": 706174884, "session_type": "Remote Support", "session_owner_email": "frida.m@zylker.com" }, { "viewer_os": "Windows", "viewer_ipaddress": "122.144.72.18", "viewer_email": "john.f@zylker.com", "agent_os": "Windows", "agent_ipaddress": "95.345.1.50", "agent_email": "hayley.c@gmail.com", "start_time": 1581299000053, "end_time": 1681378199946, "duration": "1553", "display_name": "Hayley", "session_id": 937974381, "session_type": "Screen Sharing", "session_owner_email": "john.f@zylker.com" } ], "page": { "next": "https://assist.zoho.eu/api/v2/reports?todate=1495132200000&count=20&index=21&type=all&fromdate=1463596200000", "first": "https://assist.zoho.eu/api/v2/reports?todate=1495132200000&count=20&index=1&type=all&fromdate=1463596200000", "last": "https://assist.zoho.eu/api/v2/reports?todate=1495132200000&count=20&index=10&type=all&fromdate=1463596200000" } }

ARGUMENTS

type
Required
Session type.Allowed Values: [rs|URS|all]
fromdate
Required
long (Unix Timestamp).
todate
Required
long (Unix Timestamp).
email
Optional
To fetch reports conducted by specific technician.
index
Optional
Index of the record.
count
Optional
Number of rows per page