NAV Navbar
WRITER API Docs

Getting Started

API Endpoint:

 https://writer.zoho.com/api/v1/

Writer is an online word processor that lets users create, edit and format documents and work with other people simultaneously. We have now organized the our APIs (Application Programming Interface) around REST, so that developers can integrate their existing apps or build new apps that can be integrated with Writer.

OAuth 2.0

Introduction

The Writer API is authenticated using OAuth2.0 protocol that allows you to share specific data with any application while keeping your usernames and passwords private. For example, a web application can use OAuth 2.0 in order to obtain permission from end users to create documents in their Writer account.

There are different types of tokens used in OAuth 2.0. Please take a look at the following basic terminologies before you get started with the authorization process.

Protected resources

The Writer's resources, say a list of documents and folders.

Resource server

The Writer's server that hosts the protected resources.

Resource owner

Any end user who will grant access to the protected resources of your Writer account.

Authorization server

The server that provides the required credentials, such as, access and refresh tokens to the client. In our case, it will be the Writer's server.

Client

Client is the user application that sends request to the resource server to access the resources.

Authorization code

temporary token created by the authorization server. This token will be sent to the client through the browser to get the access and refresh tokens.

access_token

The token sent to the resource server to access the user's protected resources. The access_token will provide a secure access to Writer APIs and is used by applications to send requests to the connected app. An access_token is valid only for an hour and can be used only for the set of operations specified in the scope.

Refresh Token

Refresh token is used to obtain new access_token. This has unlimited lifetime and is valid until it is revoked by the end user. Each refresh token can create up to 15 access_tokens.

Scopes

You need to authenticate your application with appropriate key and scope. Scope is a variable parameter that controls access to a set of resources and operations that is allowed by an access_token. Your application can send one or more values in the scope parameter, during the access-token request. The access and refresh tokens are created with various specified scopes to ensure secure data access.

Authorizing OAuth Requests

This section explains how web applications can use Writer APIs and access the API endpoints to implement OAuth 2.0 and access our APIs. All requests sent and received via the Writer API will be authorized to ensure better security. The steps involved in the authentication process and the OAuth flow is explained in the following sections.


Step 1: Register your application with Zoho

To connect with the Writer API, you need an account with Zoho. Before you get started with the authentication process and start making API requests, please register your application.

To register your app,

  1. Go to accounts.zoho.com/developerconsole.
  2. Click Add Client ID.
  3. Enter a valid Client Name and Client Domain
  4. Enter Authorized redirect URIs. It is the callback URL that should be given while registering your app with Zoho. This determines where the API server has to redirect the user after completing the authorization flow. The value of this parameter must exactly match with one of the redirect_uri values that is listed for your project in the Zoho's Developer Console.
    Please note that, the redirect_uri should be character perfect i.e., the http or https, case, and trailing slash ('/') of the redirect URLs must all match. (Read more)
  5. Click Create.

    Once your app is registered, you will receive the following details:

    • client_id- It is the id generated from Zoho's Developer Console . For applications that use the OAuth 2.0 protocol to call Writer APIs, this client ID will be used to generate an access_token.
    • client_secret - The client secret code that is generated from the Zoho's Developer Console.

Now, please note down the above details, these will be used to generate new access_token.

Step 2: Authorization request

Once the registration process is complete, you need to authenticate your application. After login, our servers will call the redirect URI along with an authorization code.

To authenticate, redirect the user of the client app to the Authorization Endpoint.

Enter the authorization URL as shown below:

https://accounts.zoho.com/oauth/v2/auth?
&scope=ZohoWriter.documenteditor.ALL&client_id={client_id}
&response_type=code&access_type={access_type}
&redirect_uri={redirect_uri}

Now authorize yourself using the following parameters:

scopestring Required. Choose what data can be accessed by your application.
client_idstring Required. The client_id generated during app registration.
client_secretstring Required. The client_secret generated during app registration.
redirect_uristring Required. The Callback URL that was provided during the app registration.
response_typestring Required. response_type = code.
access_typestring

Recommended. Enter access_type as online or offline.

In case, if you want to generate the refresh token, set the access_type value as "offline".

Once you send the above parameters, you need to provide permission to Zoho to access the user data. Login with your Zoho account credentials.
Click Accept.

You will be redirected to the redirect_uri that you specified during the app registration.

Now, note down the code={grant_token} parameter after you are redirected to the "redirect_uri".

(grant_token - A short-lived token that is used to generate the access_token and refresh token.)

Step 3: Create access and refresh tokens

The API requests that you make via OAuth2.0 are usually authenticated with an access_token, which is passed as bearer token.

In order to use this access_token, you must to construct a normal HTTP request and include it in the Authorization header along with the value of Bearer.

To generate access_token, do the following:

1. Make a POST request with the following URL:

https://accounts.zoho.com/oauth/v2/token?
code={grant_token}&=https://www.zoho.com/&client_id={client_id} &client_secret={client_secret}
&grant_type=authorization_code

2. On successful request, you will receive the following:

 

{
"access_token" : "{access_token}",
"refresh_token" : "{refresh_token}",
"expires_in_sec": 3600,
"api_domain" : "https://writer.zoho.com" ,
"token_type" : "Bearer",
"expires_in" : 3600000
}

This completes the authorization process. Once your app receives the access_token, send it via the HTTP authorization header to Writer's API with value as "Zoho-oauthtoken {access_token}" for each endpoint.

Now generate access and refresh tokens using the following parameters:

grant_typestring Required. Enter grant_type = authorization_code.
client_idstring Required. Your client_id that is found in Zoho Developer console.
client_secretstring Required. Your client_secret that is found in Zoho Developer console.
redirect_uristring Required. The Callback URL that was provided during the app registration.
response_typestring Required. Enter response_type as code.
access_typestring

Required. Enter access_type as online or offline.

In case, if you want to generate the refresh token, set the access_type value as "offline".

Step 4: Requesting new access_token

If your access_token is expired, create new token using the "refresh_token".

Construct the following URL to regenerate your access_token:

 

https://accounts.zoho.com/oauth/v2/token? client_id={client_id} &client_secret={client_secret} &grant_type=refresh_token& refresh_token={refresh_token} On successful request, you will get the following output:

{
"access_token" : "{new_access_token}", "expires_in_sec" : 3600, "api_domain" : "https://writer.zoho.com", "token_type" : "Bearer", "expires_in" :3600000
}


API Collection

You can use Postman to try out Writer API. Postman is a widely used REST Client for API development and testing.

Once you import the Postman collection, you need to configure the API environment. You can try it yourself manually or download our sample environment by following the steps below:

  1. Install the Postman application from Chrome web store.
  2. Download the sample postman collection here. Import this environment in your Postman extension.
  3. Now complete the registration process and generate the client_id and client_secret as shown below:
    • Log in to your Zoho account and go to https://accounts.zoho.com/developerconsole
    • Click Add Client ID.
    • Enter the following details
      - Client Name
      - Client Domain
      - Authorized redirect URIs as https://www.getpostman.com/oauth2/callback
    • Click Create. Your registration will be completed. Note down the client_id and client_secret.
      Note: You can log in to your Zoho Developer console anytime to get the client_id and client_secret values for any of your applications.
  4. Now, in your Postman extension, click on the Authorization tab and select Oauth 2.0 from the dropdown. Click Get New Access Token .
  5. Now enter the following parameters:
    • Token Name: Enter any name for reference
    • Auth URL: Enter Auth URL as
      https://accounts.zoho.com/oauth/v2/auth?access_type=offline&prompt=consent
    • access_token URL: Enter the access_token endpoint as https://accounts.zoho.com/oauth/v2/token
    • Client ID: Enter the client_id generated while registration.
    • Client Secret: Enter the client_secret generated while registration.
    • Scope (Optional): ZohoWriter.documenteditor.ALL
    • Grant type: Grant type = Authorization Code

  6. After clicking Request Token, you will be redirected to authorization page and now enter your Zoho login credentials and click Sign In. You can also sign in using your Google accounts.

  7. Now click on the generated key and copy your access_token value from your postman application.
  8. Update the access_token key with value in headers.
    Key:Authorization
    Value:Zoho-oauthtoken
  9. Now click the Send button and check the sample response within the Postman app.

 

HTTP Methods

GET To get data from a given server.
POST To upload data to the server.
DELETE Request to remove the resource.

HTTP status code summary

Error Code Description
200 OK
Successful API request.
400 BAD REQUEST
User error. This is due an an invalid parameter or combination of parameters provided is invalid.
401 UNAUTHORIZED
Invalid authorization error. The access_token you provided is either invalid or expired.
403 FORBIDDEN
The user does not have access to perform the required access.
404 NOT FOUND
The user does not have read access to the file, or the requested file does not exist.
405 METHOD NOT ALLOWED
The HTTP method used is not supported by the URL endpoint.
429 TOO MANY REQUESTS
You application is trying to use more than the available API limit. In that case, additional requests will fail.
500 INTERNAL SERVER ERROR
This is a backend error encountered due to an unexpected server behavior.

Document API

Writer provides a set of APIs, which you can use to create new add-ons that interact with the document content and meta data. You can get the list of your documents, create/upload new documents, delete and download your documents via Writer's Document API. The supported APIs are explained in sections below.

Create/Upload Documents

You can use the create document API to create a new blank document or a document with content. Also, provide a filename parameter in your API request to create a document with the required name. A blank untitled document will be created if you don't specify any params.

Sample request

curl "http://writer.zoho.com/api/v1/documents"
-X POST -H "Authorization: Zoho-oauthtoken f92d01c803988c5ch49d0b4215f52"

Sample response

Purpose

To create or upload documents. The document that is created can be accessed in the recent files of your Writer account.

HTTP Request URL

POST https://writer.zoho.com/api/v1/documents

Create with content

Sample request

curl "http://writer.zoho.com/api/v1/documents"
-X POST -H "Authorization: Zoho-oauthtoken f92d01c803988c5ch49d0b4215f52"

Sample response

Purpose

To create document with content parameter. The document will be created along with the content that you provided in the request body.

HTTP Request URL

POST https://writer.zoho.com/api/v1/documents

Parameters

contentstring Provide the required content in your API request body.

Create with text

Sample request

curl "http://writer.zoho.com/api/v1/documents?
text=This is the sample text for creating document"

-X POST -H "Authorization: Zoho-oauthtoken f92d01c803988c5ch49d0b4215f52"

Sample response

Purpose

To create a document with specified content through simple text (string) param.

HTTP Request URL

POST https://writer.zoho.com/api/v1/documents

Parameters

textstring Provide the required text and your document with the specified text will be created.

Create through web URL

Sample request

curl "http://writer.zoho.com/api/v1/documents?
url=http://cashboardapp.com/downloads/InvoiceTemplate.docx

-X POST -H "Authorization: Zoho-oauthtoken f92d01c803988c5ch49d0b4215f52"

Sample response

Purpose

To create a document via web URL.

HTTP Request URL

POST https://writer.zoho.com/api/v1/documents

Parameters

URLstring Specify the web URL, through which the document will be created.

For error handling cases in Create document, refer here.

Get list of documents

Sample Request

curl "http://writer.zoho.com/api/v1/documents"
-X GET -H "Authorization: Zoho-oauthtoken f92d01c803988c5ch49d0b4215f52"

Sample Response

Purpose

To get the list of all documents.

HTTP Request URL

GET https://writer.zoho.com/api/v1/documents

Get the list documents with specified params.

Sample Request

curl "https://writer.zoho.com/writer/api/v1/documents?limit=7&from_index=5
&sortby=created_time" 
-X GET -H "Authorization: Zoho-oauthtoken f92d01c803988c5ch49d0b4215f52"

Sample Response

Parameters

limitinteger Set document limit and retrieve the list of documents within the specified limit.
from_indexinteger Set the from_index parameter to get the list of documents from the respective page
sortbystring

created_time
Get the list of documents with respect to the document created time.
modified_time
Get the list of documents with respect to the last modified time of the document.
lastopened_time
Get the list of documents with respect to the last opened time.
Default date format: IS08601

For error handling cases, click here.

Download document

The Writer API allows to download docs that are stored in your Writer account. You can download files in docx, odt, rtf, txt, html, pdf formats. To download document, you should make an authorized HTTP GET request by including the document_id and format parameters. The document will be downloaded in docx format by default if you don't specify this parameter in your API request.

Sample Request

curl "http://writer.zoho.com/api/v1/documents?0k1457c4737fac1b787eaf&format=html"
-X GET -H "Authorization: Zoho-oauthtoken f92d01c803988c5ch49d0b4215f52"

Your document will be downloaded.

Purpose

To download the document in the specified format.

HTTP Request URL

GET https://writer.zoho.com/api/v1/documents

Parameters

formatstring Specify the format of the document to be downloaded.
Supported file formats - docx odt rtf txt html pdf
document_idstring Specify the unique id of the document to be downloaded.

Refer here to check the possible error cases when using the download document API.

Delete Document

To delete document via API, make an authorized HTTP DELETE request. You need to specify the document_id of the file to be deleted.

Request:

curl "http://writer.zoho.com/api/v1/documents/0k1457c4737fac1b787eaf"
-X DELETE
-H "Authorization: Zoho-oauthtoken f92d01c803988c5ch49d0b4215f52"

Response:

Purpose

To delete the document specified in the API request. You need to specify the unique id of the document that you want to delete. Please click here for possible error handing cases.

HTTP Request URL

DELETE https://writer.zoho.com/api/v1/documents/document_id

Parameters

document_idstring Required. Specify the document id that has to be deleted.

Errors

Writer API returns error information as a collection of JSON object that includes two fields basically:

code A unique error code.
message An error description.

In the following sections, you can find the JSON representation of every possible error and a suggested action that can be taken to handle these errors.

General errors

Invalid method

Error response

Error code

R5006

Error description

The API method you used in your request is invalid. For example, you might have selected GET method in a POST request.

Suggested action

Please use a valid method name and try again.

Unsupported params

Error response

Error code

R5012

Error description

Your request has param types that are not supported in Writer API.

Suggested action

Please enter valid parameter value and try again.

URL rule not configured

Error response

Error description

The specified web URL is not configured properly.

Error code

R2008

Invalid OAuthtoken

Error response

Error code

R5011

Error description

Invalid authorization header provided. The access_token you're using is either invalid or expired.

Suggested action

Create new access_token and try again.

Get List of Documents - possible errors

Invalid param values

Error response

Error code

R2000

Error description

The value specified for the params is invalid or you have used the params that are not configured properly.

Suggested action

Please set the value with respect to the available limit and try again.

Invalid data type

Error response

Error code

R2010

Error description

The data type of the parameter is invalid.

Suggested action

Set a valid param data type in your API request and try again

Common error

Error response

Error code

R3003

Error description

Unable to fetch the list of documents.

Suggested action

This may due to an internal error. Please try again after sometime.

Create Document - possible errors

Document conversion failure

Error response

Error code

R1010

Error description

The above error occurs when the file that you're trying to upload could not be converted to any of the available formats.

Suggested action

Set a valid document format supported by Writer and try again.

File size exceeded

Error response

Error code

R1007

Error description

The size of the file you're trying to download exceeded the maximum size.

Unsupported file extension

Error response

Error code

R1002

Error description

The file you're trying to import has an unsupported extension.

Suggested action

Please change the extension and try again.

Virus detected

Error response

Error code

R1009

Error description

File you're trying to import via the web URL seems to contain a virus.

Invalid import URL

Error response

Error code

R1000

Error description

Unable to import the required file. This may occur when you're trying to import a file from an invalid web URL.

Unsupported content type

Error response

Error code

R1008

Error description

You get the above error when the file you're trying to import has an unsupported content-type.

Suggested action

Change the content-type/file format and try importing your file.

Filename is too large

Error response

Error code

R2005

Error description

The length of the filename provided exceeded the allowed limit.

Suggested action

Please enter a valid name and try again.

Download Document - possible errors

No permission

Error response

Error code

R5010

Error description

The user might not have enough permission to download the document.

Suggested action

Downloading could be restricted if the user does not access to the document or they have only read-only permissions. Make sure you change the permissions and try again.

No sufficient privileges

Error response

Error code

R3001

Error description

The user does not have sufficient privileges to download the document. This may be due to the org policy restriction.

Suggested action

Please contact your organization administrator.

Common error

Error response

Error code

R3002

Error description

Unable to download your document. This may be due to an internal server error.

Suggested action

Please try again after sometime.

Delete Document - possible errors

No permission

Error response

Error code

R5010

Error description

The user does not have enough permission to delete the document.

Suggested action

Please change the user permission settings and try again.