Pre-requisite

All Zoho Sign APIs require this mandatory header.

  • Authorization - Authentication request header.

Getting Started

There are six steps to access Zoho Sign APIs using OAuth:

  1. Registering a new client
  2. Generating grant token
  3. Generating access and refresh token
  4. Generating access token from refresh token
  5. Revoking refresh token
  6. Calling an API

Registering a new client

  1. First, you need to register your application with Zoho's developer console to get your Client ID and Client Secret.
  2. Log in to https://accounts.zoho.com/developerconsole
  3. Click on Add Client ID
  4. Provide the details and register your application
  5. On successful authentication, you will be provided with Client ID and Client Secret
  6. Do not share the Client ID and Client Secret with anyone

Generating grant token

  1. Go to the authorization URL with the given param: https://accounts.zoho.com/oauth/v2/auth?
  2. On this request, you be will taken to the user consent page.
  3. Click Accept (clicking Deny will throw an error)
  4. Zoho will redirect to the given redirect_uri with code and state param. This code value is mandatory to get the access token in the next step
  5. The code value will be valid for 60 seconds
scope                             required             Scope for which the token to be generated. Multiple scopes can be given which has to be separated by commas. Ex: ZohoSign.documents.all   
client_idrequiredClient ID obtained during client registration
staterequiredAn opaque string that is round-tripped in the protocol; ie., whatever value given to this will be passed back to you.
response_typerequiredcode
redirect_urirequiredOne of the redirect URI gave in above step. This param should be same redirect URL mentioned while registering the client
access_typerequiredThe allowed values are offline and online
promptrequiredPrompts for user consent each time your app tries to access user credentials. Ex: consent

Generating access and refresh token

After generating the code in the above step, make a POST request for the below URL with given params, to generate the access_token.

  1. https://accounts.zoho.com/oauth/v2/token?
  2. In the response, you will get both access_token and refresh_token.
  3. The access_token will expire after a particular period (as configured in the expires_in param).
  4. The refresh_token is permanent and will be used to regenerate new access_token, if the current access token has expired.
  5. Each time a re-consent page is accepted, a new refresh token is generated. The maximum limit is 20 refresh tokens per user. If this limit is reached, the first refresh token will be automatically deleted to accommodate the latest one. This is done irrespective of whether the first refresh token is in use or not.
code                  required       code which is obtained in the above step
client_idrequiredClient ID obtained during client registration
client_secretrequiredClient secret obtained during client registration
redirect_urirequiredThis param should be same redirect URL mentioned while adding client
grant_typerequiredauthorization_code
scoperequiredScope for which the token to be generated. Multiple scopes can be given which has to be separated by commas. Ex: ZohoSign.documents.all  
staterequiredAn opaque string that is round-tripped in the protocol; that is to say, the value will be passed back to you.

Generating access token from refresh token

Access tokens have a limited validity. In most cases, the access tokens will expire in one hour. Until then, the access token has unlimited usage. Once it expires, your application should use the refresh token to request for a new access token. Redirect to the following POST URL with the given params to get a new access token.

refresh_token   required    Refresh token which is obtained in the above step
client_idrequiredClient ID obtained during client registration
client_secretrequiredClient secret obtained during client registration
redirect_urirequiredThis param should be same redirect URL mentioned while adding client   
grant_typerequiredrefresh_token

Revoking refresh token

To revoke a refresh token, call the following POST URL with the given params.

https://accounts.zoho.com/oauth/v2/token/revoke?

refresh_token   required   Refresh token which is obtained in the above step    

Calling an API

Access token can be passed only in the header and cannot be passed in the request param.

  • Header name should be Authorization Header value should be Zoho OAuth token {access_token}

Some tips

Zoho Sign API uses appropriate HTTP verbs for every action.

  • GET - used for retrieving resources
  • POST - used for creating resources and performing resource actions
  • PUT - used for updating resources
  • DELETE - used for deleting resources

Zoho Sign uses HTTP status codes to indicate the status of an API call. In general, status codes in the 2xx range mean 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.

  • 200 - OK
  • 400 - bad request
  • 401 - unauthorized access or invalid auth token
  • 404 - URL not found
  • 405 - method not allowed or method you have called is not supported for the invoked API
  • 500 - internal error

Zoho Sign APIs retrieves documents, templates, users and other resources - paginated to 100 items by default. The pagination information will be included in the list API response under the node name page_context.

By default, the first page will be listed. For navigating through pages, use the start_index parameter.

The row_count parameter can be used to set the number of records that you want to receive in the response.

Example

Copied$ curl https://sign.zoho.com/api/v1/accounts \
    -H 'Authorization: Zoho-oauthtoken <Oauth Token>'

Generating grant token - Request example

Copiedhttps://accounts.zoho.com/oauth/v2/auth?scope=ZohoSign.documents.CREATE,ZohoSign.documents.READ,ZohoSign.documents.UPDATE,ZohoSign.documents.DELETE&client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V&state=testing&response_type=code&redirect_uri=http://www.zoho.com/sign&access_type=offline

Generating access and refresh token - Request example

Copiedhttps://accounts.zoho.com/oauth/v2/token?code=1000.dd7e47321d48b8a7e312e3d6eb1a9bb8.b6c07ac766ec11da98bf6a261e24dca4&client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V&client_secret=fb0196010f2b70df8db2a173ca2cf59388798abf&redirect_uri=http://www.zoho.com/sign&grant_type=authorization_code

Generating access token from refresh token - Request example

Copiedhttps://accounts.zoho.com/oauth/v2/token?refresh_token=1000.8ecd474019e31d52d2f94aad6c5cb7.4638677ebc14f2f2ee0b6dfb6cebdc&client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V&client_secret=fb0196010f2b70df8db2a173ca2cf59388798abf&redirect_uri=http://www.zoho.com/sign&grant_type=refresh_token

Revoking refresh token - Request example

Copiedhttps://accounts.zoho.com/oauth/v2/token/revoke?refresh_token=1000.8ecd474019e31d522f94aad6c5cb7.4638677ebc14f2f2ee0b6dfb6cebdc

HTTP Methods

CopiedUsing GET method, you can get the list of resources or details of a particular instance of a resource.

To get a list of users

$ curl https://sign.zoho.com/api/v1/users \
    -H 'Authorization: Zoho-oauthtoken <Oauth Token>' \

Response structure

CopiedThe response structure for the Documents API follows the below format.

{
    "code" : 0,
    "message" : "success",
    "requests" : {
        "request_id" : "..."
    }
}

Responses will be in the JSON format.

Node Name|Description
------|-----------
code|Zoho Sign error code. This will be zero for a success response and non-zero in case of an error.
message|Message for the invoked API.
resource name|Comprises the invoked API’s Data.

##Errors

>Request Example

```shell

$ curl https://sign.zoho.com/api/v1/requests/[Request Id] \
    -H 'Authorization: Zoho-oauthtoken <Oauth Token>' \

Response Example


HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8

{
    "code": 1002,
    "message": "Document does not exist."
}

Pagination - Example

Copied$ curl https://sign.zoho.com/api/v1/requests?data={"page_context":{"row_count":10,"start_index":1,"search_columns":{},"sort_column":"created_time","sort_order":"DESC"}}
    -H 'Authorization: Zoho-oauthtoken <Oauth Token>'

{
    "code": 0,
    "message": "success",
    "requests": [
            {...},
            {...}
    ],
    "page_context": {
        "has_more_rows":true,
        "row_count":10,
        "sort_column":"created_time",
        "sort_order":"DESC",
        "start_index":1,
    }
}