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:
- Registering a new client
- Generating grant token
- Generating access and refresh token
- Generating access token from refresh token
- Revoking refresh token
- Calling an API
Registering a new client
- First, you need to register your application with Zoho's developer console to get your Client ID and Client Secret.
- Log in to https://accounts.zoho.com/developerconsole
- Click on Add Client ID
- Provide the details and register your application
- On successful authentication, you will be provided with Client ID and Client Secret
- Do not share the Client ID and Client Secret with anyone
Generating grant token
- Go to the authorization URL with the given param: https://accounts.zoho.com/oauth/v2/auth?
- On this request, you be will taken to the user consent page.
- Click Accept (clicking Deny will throw an error)
- 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
- 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_id | required | Client ID obtained during client registration |
| state | required | An opaque string that is round-tripped in the protocol; ie., whatever value given to this will be passed back to you. |
| response_type | required | code |
| redirect_uri | required | One of the redirect URI gave in above step. This param should be same redirect URL mentioned while registering the client |
| access_type | required | The allowed values are offline and online |
| prompt | required | Prompts 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.
- https://accounts.zoho.com/oauth/v2/token?
- In the response, you will get both access_token and refresh_token.
- The access_token will expire after a particular period (as configured in the expires_in param).
- The refresh_token is permanent and will be used to regenerate new access_token, if the current access token has expired.
- 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_id | required | Client ID obtained during client registration |
| client_secret | required | Client secret obtained during client registration |
| redirect_uri | required | This param should be same redirect URL mentioned while adding client |
| grant_type | required | authorization_code |
| 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 |
| state | required | An 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_id | required | Client ID obtained during client registration |
| client_secret | required | Client secret obtained during client registration |
| redirect_uri | required | This param should be same redirect URL mentioned while adding client |
| grant_type | required | refresh_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
$ curl https://sign.zoho.com/api/v1/accounts \
-H 'Authorization: Zoho-oauthtoken <Oauth Token>'Generating grant token - Request example
https://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
https://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
https://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
https://accounts.zoho.com/oauth/v2/token/revoke?refresh_token=1000.8ecd474019e31d522f94aad6c5cb7.4638677ebc14f2f2ee0b6dfb6cebdc
HTTP Methods
Using 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
The 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
$ 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,
}
}