API Documentation
Pricing Resources Contact Us

Introduction

API Root Endpoint

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

API stands for Application Programming Interface. An API is a set of functions and procedures that help users to access the features or data of an application, service, or operating system directly from another application. Let's take a look at a simple example to understand it better.

When you’re booking a movie or flight ticket, you will often see an Add to your Google Calendar option on the booking website. When you hit this button, the booking website will talk to Google’s server directly in the background with a request to create an event schedule. The booking website’s server will process the response and display the confirmation message on your screen. In other words, you’re using a feature of an application without accessing its interface.

Zoho Sign APIs provides the option for users to perform user management, document management, and other operations directly, without accessing Zoho Sign’s web interface. We provide REpresentational State Transfer Application Programming Interface (REST API) to serve this purpose.

Why REST?

REST API’s architecture takes advantage of protocols that are already in place. For example it uses HTTP protocol for web APIS, which means it provides great flexibility for developers to use existing libraries while building their custom applications. It was originally developed by Dr. Roy Fielding in 2000 and adopted by developers across the globe for its ease of use and simplicity.

Every resource is exposed as a URL, which can be obtained by accessing the API root endpoint.

How secure are your APIs?

Zoho Sign REST APIs leverage the industry-standard OAuth 2.0 protocol for authorization. They authorizes applications to interact with them without actually giving away the password. In other words, they provide delegated access to the service and authorize third-party applications to access the user account securely.

What are the supported operations?

Zoho Sign APIs support a growing list of operations mentioned below. Over the next few months, we will support all the operations available in our web interface.

User Management
  • Retrieve user account details
  • Invite a user
  • Retrieve users list
  • Update user access
  • Update user role
  • Delete user
Document Management
  • Create document
  • Manage document
  • Send documents for signature
  • Get details of a particular document
  • Get documents list
  • Download PDF
  • Download Completion Certificate
  • Create new folder
  • Get folders list
  • Get Document type
  • Get field type
  • Create new document type
Template Management
  • Create template
  • Update template
  • Get template Details
  • Get template list
  • Send document for signature using template

Pre-requisite

All Zoho Sign APIs require this mandatory header. Authorization - Authentication request header.

Getting Started

Example

$ curl https://sign.zoho.com/api/v1/accounts \
    -H 'Authorization: Zoho-oauthtoken <Oauth Token>'
  1. Register a new client
  2. Generate grant token
  3. Generate access and refresh token
  4. Generate access token from refresh token
  5. Revoke refresh token
  6. Calling an API

Step 1: Register a new client

First, you need to register your application with Zoho’s developer console to get your Client ID and Client Secret.

  1. Log in to https://accounts.zoho.com/developerconsole
  2. Click on Add Client ID
  3. Provide the details and register your application

Upon successful authentication, you will be provided with Client ID and Client Secret. Do not share the Client ID and Client Secret with anyone

Step 2: Generate grant token

  1. Go to the below authorization URL with the given params 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)

Zoho will redirect to the given redirect_uri with code and state parameters. This code value is mandatory to get the access token in the next step, and will be valid for 60 seconds.

Request Example

https://accounts.zoho.com/oauth/v2/auth?scope=ZohoSign.documents.CREATE,ZohoSign.documents.READ,ZohoSign.documents.UPDATE,ZohoSign.documents.DELETE&client_id=[Client ID]&state=testing&response_type=code&redirect_uri=[Redirect URL]&access_type=offline

Arguments

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 given 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

Step 3: Generate Access and Refresh Token

After generating the code in the above step, make a POST request for the below URL with the given parameters 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.

Request Example

https://accounts.zoho.com/oauth/v2/token?code=[Code]&client_id=[Client ID]&client_secret=[Client Secret]&redirect_uri=[Redirect URL]&grant_type=authorization_code

Arguments

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, value will be passed back to you.

Step 4: Generate 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 parameters to get a new access token.

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

Request Example

https://accounts.zoho.com/oauth/v2/token?refresh_token=[Refresh Token]&client_id=[Client Id]&client_secret=[Client Secret]&redirect_uri=[Redirect URL]&grant_type=refresh_token

Arguments

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

Step 5: Revoke Refresh Token

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

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

Request Example

https://accounts.zoho.com/oauth/v2/token/revoke?refresh_token=[Refresh Token]

Arguments

refresh_token
required
Refresh Token which is obtained in the above step

Step 6: Calling An API

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

Header name should be Authorization Header value should be Zoho-oauthtoken {access_token}

Some tips

Zoho Sign API uses appropriate HTTP verbs for every action.

Method Description
GETused for retrieving resources
POSTused for creating resources and performing resource actions
PUTused for updating resources
DELETEused for deleting resources

Zoho Sign uses HTTP status codes to indicate the status of an API call. In general,

Status Code Description
200OK
400bad request
401unauthorized access or invalid auth token
404URL not found
405method not allowed or method you have called is not supported for the invoked API
500internal 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.

User Management

Users can be invited to be a part of your organization’s Zoho Sign account' and as an admin you control their access.

Oauthscopes

ZohoSign.account.CREATE,ZohoSign.account.READ,ZohoSign.account.UPDATE

Retrieve user account details

GET https://sign.zoho.com/api/v1/accounts

Get the details of your account.

Request Example

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

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
  "code": 0,
  "message": "User list retrieved successfully",
  "page_context": {
    "sort_column": "role",
    "has_more_rows": false,
    "start_index": 1,
    "sort_order": "ASC",
    "row_count": 0
  },
  "users": [
    {
      "user_email": "s********@***.com",
      "is_payment_owner": true,
      "role": "Admin",
      "user_id": "2000000002002",
      "user_name": "S********",
      "is_allowed": true
    },
    {
      "user_email": "v*********@***.com",
      "role": "User",
      "user_id": "2000000006077",
      "user_name": "V********",
      "is_allowed": true
    },
  ],
  "status": "success"
}

Invite a user

This will invite a user to join your account.

POST https://sign.zoho.com/api/v1/users/invite

Request Example

$ curl https://sign.zoho.com/api/v1/users/invite \
    -H "Authorization: Zoho-oauthtoken <Oauth Token>" \
    -d 'email_id=["v********@****"]'

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
  "code": 0,
  "invitations": [
    {
      "user_email": "v*******@*****",
      "is_invited": true
    }
  ],
  "message": "Invitation has been sent",
  "status": "success"
}

Arguments

email_id
Array
List of emails

Retrieve user list

This will retrieve the list of users who are part of your account.

GET https://sign.zoho.com/api/v1/users

Request Example

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

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
  "code": 0,
  "message": "User list retrieved successfully",
  "page_context": {
    "sort_column": "role",
    "has_more_rows": false,
    "start_index": 1,
    "sort_order": "ASC",
    "row_count": 0
  },
  "users": [
    {
      "user_email": "s********@***.com",
      "is_payment_owner": true,
      "role": "Admin",
      "user_id": "2000000002002",
      "user_name": "S********",
      "is_allowed": true
    },
    {
      "user_email": "V******@***.com",
      "role": "User",
      "user_id": "2000000006077",
      "user_name": "V********",
      "is_allowed": true
    },
  ],
  "status": "success"
}

Update user access

PUT https://sign.zoho.com/api/v1/users/[User Id]

This will help you either grant or revoke user access.

Request Example

$ curl https://sign.zoho.com/api/v1/users/[User Id] \
    -X PUT \
    -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
    -H "Authorization: Zoho-oauthtoken <Oauth Token>" \
    -d 'allowed_access=true'

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{"code":0,"message":"Access has been changed for the selected user","status":"success"}

Arguments

allowed_access
boolean
Allow access to user [true/false].

Update user role

PUT https://sign.zoho.com/api/v1/users/[User Id]

This will help you to modify the role of a user in your account.

Request Example

$ curl https://sign.zoho.com/api/v1/users/[User Id] \
    -X PUT \
    -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
    -H "Authorization: Zoho-oauthtoken <Oauth Token>" \
    -d 'role=User'

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{"code":0,"message":"Role has been changed for the selected user","status":"success"}

Arguments

role
string
Role of the user [User/Admin].

Delete a User

PUT https://sign.zoho.com/api/v1/users/[User Id]/delete

This will help you to delete a user from your account.

Request Example

$ curl https://sign.zoho.com/api/v1/users/[User Id]/delete \
    -X PUT \
    -H "Authorization: Zoho-oauthtoken <Oauth Token>"

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{"code":0,"message":"User has been deleted","status":"success"}

Document Management

Create documents, update documents, send documents out for signatures and get the list of all documents related to your account.

Oauthscopes

ZohoSign.documents.CREATE,ZohoSign.documents.READ,ZohoSign.documents.UPDATE

Creating and sending a document involves the following steps : 

  1. Create Document
  2. Get field types
  3. Add fields and send document for signature

Create document

POST https://sign.zoho.com/api/v1/requests

This will create a new document. 

Request Example

$ curl https://sign.zoho.com/api/v1/requests \
    -H "Authorization: Zoho-oauthtoken <Oauth Token>"\
    -F 'file=@Path to file' \
    -F 'data={
  "requests": {
    "request_type_id": "2000000322040",
    "request_name": "NDA ",
    "actions": [
      {
        "recipient_name": "S**********",
        "recipient_email": "s*******@***.com",
        "recipient_phonenumber": "",
        "recipient_countrycode": "",
        "action_type": "SIGN",
        "private_notes": "Please get back to us for further queries",
        "signing_order": 0,
        "verify_recipient": true,
        "verification_type": "EMAIL",
        "verification_code": ""
      }
    ],
    "expiration_days": 1,
    "is_sequential": true,
    "email_reminders": true,
    "reminder_period": 8,
    "folder_id": "2000000489161"
  }
}'

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
  "code": 0,
  "requests": {
    "request_status": "draft",
    "owner_email": "v*******@***.com",
    "created_time": 1522739606981,
    "document_ids": [
      {
        "image_string": "<BASE 64 Image String>",
        "document_name": "4page170kbsquared file testrotated.pdf",
        "pages": [
          {
            "image_string": "<BASE 64 Image String>",
            "page": 0,
            "is_thumbnail": true
          }
        ],
        "document_size": 174307,
        "document_order": "0",
        "total_pages": 4,
        "document_id": "2000000489185"
      }
    ],
    "notes": "",
    "self_sign": false,
    "owner_id": "2000000002002",
    "description": "",
    "folder_name": "NDA",
    "request_name": "NDA ",
    "modified_time": 1522739606981,
    "is_deleted": false,
    "expiration_days": 1,
    "in_process": false,
    "is_sequential": true,
    "request_type_name": "NDA document",
    "owner_first_name": "V******",
    "folder_id": "2000000489161",
    "request_id": "2000000489191",
    "request_type_id": "2000000322040",
    "owner_last_name": "",
    "actions": [
      {
        "verify_recipient": true,
        "action_type": "SIGN",
        "private_notes": "Please get back to us for further queries",
        "recipient_name": "S**********",
        "recipient_email": "s*******@***.com",
        "verification_type": "EMAIL",
        "allow_signing": true,
        "recipient_phonenumber": "",
        "action_id": "2000000489194",
        "signing_order": 0,
        "fields": [],
        "action_status": "NOACTION",
        "recipient_countrycode": ""
      }
    ],
    "sign_percentage": 0
  },
  "message": "Document has been added",
  "status": "success"
}

Arguments

file
File
File that needs to be uploaded
JSONObject
JSONObject
request_name
string
name to be given to the signature request
request_type_id
string
Document Category Id
notes
string
Message to be sent to all recipients in common
expiration_days
int
No of days after which the document will expire.
is_sequential
Boolean
Sequential signing / Parallel Signing[true/false]
email_reminders
boolean
Send automatic reminders
reminder_period
int
Send automatic reminders once in [n] days
folder_id
string
Folder
JSONArray
List of recipients

Update document

PUT https://sign.zoho.com/api/v1/requests/[Request Id]

This will help you to update an existing document.

Request Example

$ curl https://sign.zoho.com/api/v1/requests/[Request Id] \
    -X PUT \
    -H "Authorization: Zoho-oauthtoken <Oauth Token>" \
    -d 'data={
  "requests": {
    "actions": [
      {
        "verify_recipient": true,
        "action_type": "SIGN",
        "private_notes": "Please get back to us for further queries",
        "verification_type": "EMAIL",
        "recipient_phonenumber": "",
        "recipient_name": "S**********",
        "recipient_email": "s*******@***.com",
        "action_id": "2000000489194",
        "signing_order": 0,
        "fields": {
          "text_fields": [
            {
              "document_id": "2000000489185",
              "field_name": "Company",
              "abs_width": 16,
              "abs_height": 5,
              "x_coord": 9,
              "y_coord": 6,
              "page_no": 0,
              "is_mandatory": true,
              "text_property": {
                "font": "Arial",
                "font_size": 11,
                "font_color": "000000",
                "is_bold": false,
                "is_italic": false
              },
              "field_type_id": "2000000000155"
            },
            {
              "document_id": "2000000489185",
              "field_name": "Full name",
              "abs_width": 16,
              "abs_height": 5,
              "x_coord": 50,
              "y_coord": 6,
              "page_no": 0,
              "is_mandatory": true,
              "text_property": {
                "font": "Arial",
                "font_size": 11,
                "font_color": "000000",
                "is_bold": false,
                "is_italic": false
              },
              "name_format": "FULL_NAME",
              "field_type_id": "2000000000153"
            },
            {
              "document_id": "2000000489185",
              "field_name": "Email",
              "abs_width": 31,
              "abs_height": 5,
              "x_coord": 22,
              "y_coord": 11,
              "page_no": 0,
              "is_mandatory": true,
              "text_property": {
                "font": "Arial",
                "font_size": 11,
                "font_color": "000000",
                "is_bold": false,
                "is_italic": false
              },
              "field_type_id": "2000000000149"
            }
          ],
          "image_fields": [
            {
              "document_id": "2000000489185",
              "field_name": "Signature",
              "abs_width": 22,
              "abs_height": 5,
              "is_mandatory": true,
              "x_coord": 6,
              "y_coord": 0,
              "page_no": 0,
              "field_type_id": "2000000000141"
            },
            {
              "document_id": "2000000489185",
              "field_name": "Initial",
              "abs_width": 8,
              "abs_height": 5,
              "is_mandatory": true,
              "x_coord": 50,
              "y_coord": 0,
              "page_no": 0,
              "field_type_id": "2000000000143"
            }
          ],
          "date_fields": [
            {
              "document_id": "2000000489185",
              "field_name": "Sign Date",
              "abs_width": 16,
              "abs_height": 1,
              "x_coord": 62,
              "y_coord": 11,
              "page_no": 0,
              "is_mandatory": true,
              "date_format": "MMM dd yyyy",
              "text_property": {
                "font": "Arial",
                "font_size": 11,
                "font_color": "000000",
                "is_bold": false,
                "is_italic": false
              },
              "field_type_id": "2000000000151"
            }
          ],
          "check_boxes": [
            {
              "document_id": "2000000489185",
              "field_name": "Checkbox_1",
              "abs_width": 12,
              "abs_height": 5,
              "is_mandatory": false,
              "default_value": false,
              "x_coord": 9,
              "y_coord": 10,
              "page_no": 0,
              "is_read_only": false,
              "field_label": "Checkbox_1",
              "field_type_id": "2000000000137"
            }
          ],
          "radio_groups": []
        },
        "recipient_countrycode": "",
        "deleted_fields": []
      },
    ],
    "deleted_actions": [],
    "request_name": "NDA "
  }
}'

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8

{
  "code": 0,
  "requests": {
    "request_status": "draft",
    "notes": "Hi\nA note\nMr. Tester\nHow ar eyouuu ?",
    "owner_id": "2000000002002",
    "description": "",
    "request_name": "Leave a note test",
    "modified_time": 1522745916988,
    "action_time": 1522745917015,
    "is_deleted": false,
    "expiration_days": 1,
    "is_sequential": true,
    "sign_submitted_time": 1522745917015,
    "owner_first_name": "V****",
    "sign_percentage": 33.34,
    "expire_by": 1522866540000,
    "is_expiring": true,
    "owner_email": "v*******@***.com",
    "created_time": 1522745900919,
    "document_ids": [
      {
        "image_string": "<BASE 64 Image String>",
        "document_name": "Employee NDA.pdf",
        "pages": [
          {
            "image_string": "<BASE 64 Image String>",
            "page": 0,
            "is_thumbnail": true
          }
        ],
        "document_size": 27059,
        "document_order": "0",
        "total_pages": 2,
        "document_id": "2000000493003"
      }
    ],
    "self_sign": false,
    "in_process": false,
    "request_type_name": "Others",
    "request_id": "2000000493009",
    "request_type_id": "2000000000135",
    "owner_last_name": "",
    "actions": [
      {
        "verify_recipient": false,
        "action_id": "2000000493012",
        "action_type": "SIGN",
        "private_notes": "",
        "recipient_name": "S**********",
        "recipient_email": "s*******@***.com",
        "signing_order": 0,
        "fields": [
          {
            "field_id": "2000000493016",
            "field_type_id": "2000000000141",
            "field_category": "image",
            "field_label": "Signature",
            "is_mandatory": true,
            "page_no": 0,
            "document_id": "2000000493003",
            "field_name": "Signature",
            "y_coord": 5,
            "action_id": "2000000493012",
            "abs_width": 22,
            "field_type_name": "Signature",
            "description_tooltip": "",
            "x_coord": 42,
            "abs_height": 2
          },
          {
            "field_id": "2000000493017",
            "field_type_id": "2000000000143",
            "field_category": "image",
            "field_label": "Initial",
            "is_mandatory": true,
            "page_no": 0,
            "document_id": "2000000493003",
            "field_name": "Initial",
            "y_coord": 3,
            "action_id": "2000000493012",
            "abs_width": 18,
            "field_type_name": "Initial",
            "description_tooltip": "",
            "x_coord": 71,
            "abs_height": 5
          },
          {
            "field_id": "2000000493015",
            "field_type_id": "2000000000149",
            "text_property": {
              "is_italic": false,
              "is_underline": false,
              "font_color": "000000",
              "font_size": 11,
              "is_read_only": false,
              "is_bold": false,
              "font": "Arial"
            },
            "field_category": "textfield",
            "field_label": "Email",
            "is_mandatory": true,
            "default_value": "",
            "page_no": 0,
            "document_id": "2000000493003",
            "field_name": "Email",
            "y_coord": 3,
            "action_id": "2000000493012",
            "abs_width": 30,
            "field_type_name": "Email",
            "description_tooltip": "",
            "x_coord": 4
            "abs_height": 5
          },
          {
            "field_id": "2000000493014",
            "field_type_id": "2000000000137",
            "field_category": "checkbox",
            "field_label": "Checkbox_1",
            "is_mandatory": false,
            "default_value": false,
            "page_no": 0,
            "document_id": "2000000493003",
            "field_name": "Checkbox_1",
            "y_coord": 10,
            "action_id": "2000000493012",
            "abs_width": 10,
            "is_read_only": false,
            "field_type_name": "Checkbox",
            "description_tooltip": "",
            "x_coord": 80,
            "abs_height": 10
          }
        ],
        "allow_signing": true,
        "action_status": "UNOPENED",
        "recipient_phonenumber": "",
        "recipient_countrycode": ""
      }
    ]
  },
  "status": "success"
}

Arguments

JSONObject
JSONObject
request_name
string
name to be given to the signature request
request_type_id
string
Document Category Id
notes
string
Message to be sent to all recipients in common
expiration_days
int
No of days after which the document will expire.
is_sequential
Boolean
Sequential signing / Parallel Signing[true/false]
email_reminders
boolean
Send automatic reminders
reminder_period
int
Send automatic reminders once in [n] days
folder_id
string
Folder
JSONArray
List of recipients

Send document for signature

POST https://sign.zoho.com/api/v1/requests/[Request Id]/submit

This will help you to send a document to your recipients for signature.

Request Example

$ curl https://sign.zoho.com/api/v1/requests/[Request Id]/submit \
    -X POST \
    -H "Authorization: Zoho-oauthtoken <Oauth Token>"\
    -d 'data={
  "requests": {
    "actions": [
      {
        "verify_recipient": false,
        "action_id": "2000000493012",
        "action_type": "SIGN",
        "private_notes": "",
        "signing_order": 0,
        "fields": {
          "text_fields": [
            {
              "field_id": "2000000493015",
              "field_type_id": "2000000000149",
              "text_property": {
                "is_italic": false,
                "is_underline": false,
                "font_color": "000000",
                "font_size": 11,
                "is_read_only": false,
                "is_bold": false,
                "font": "Arial"
              },
              "field_category": "textfield",
              "field_label": "Email",
              "is_mandatory": true,
              "default_value": "",
              "page_no": 0,
              "document_id": "2000000493003",
              "field_name": "Email",
              "y_coord": 3,
              "action_id": "2000000493012",
              "abs_width": 30,
              "description_tooltip": "",
              "x_coord": 4,
              "abs_height": 2
            }
          ],
          "image_fields": [
            {
              "field_id": "2000000493016",
              "field_type_id": "2000000000141",
              "field_category": "image",
              "field_label": "Signature",
              "is_mandatory": true,
              "page_no": 0,
              "document_id": "2000000493003",
              "field_name": "Signature",
              "y_coord": 3,
              "action_id": "2000000493012",
              "abs_width": 22,
              "description_tooltip": "",
              "x_coord": 42,
              "abs_height": 2
            },
            {
              "field_id": "2000000493017",
              "field_type_id": "2000000000143",
              "field_category": "image",
              "field_label": "Initial",
              "is_mandatory": true,
              "page_no": 0,
              "document_id": "2000000493003",
              "field_name": "Initial",
              "y_coord": 3,
              "action_id": "2000000493012",
              "abs_width": 18,
              "description_tooltip": "",
              "x_coord": 71,
              "abs_height": 5
            }
          ],
          "date_fields": [],
          "check_boxes": [
            {
              "field_id": "2000000493014",
              "field_type_id": "2000000000137",
              "field_category": "checkbox",
              "field_label": "Checkbox_1",
              "is_mandatory": false,
              "default_value": false,
              "page_no": 0,
              "document_id": "2000000493003",
              "field_name": "Checkbox_1",
              "y_coord": 10,
              "action_id": "2000000493012",
              "abs_width": 18,
              "is_read_only": false,
              "description_tooltip": "",
              "x_coord": 80,
              "abs_height": 5
            }
          ],
          "radio_groups": []
        },
        "recipient_phonenumber": "",
        "recipient_countrycode": "",
        "deleted_fields": []
      }
    ],
    "deleted_actions": [],
    "request_name": "Leave a note test"
  }
}'

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
  "code": 0,
  "requests": {
    "request_status": "inprogress",
    "notes": "Hi\nA note\nMr. Tester\nHow ar eyouuu ?",
    "owner_id": "2000000002002",
    "description": "",
    "request_name": "Leave a note test",
    "modified_time": 1522745916988,
    "action_time": 1522745917015,
    "is_deleted": false,
    "expiration_days": 1,
    "is_sequential": true,
    "sign_submitted_time": 1522745917015,
    "owner_first_name": "V****",
    "sign_percentage": 33.34,
    "expire_by": 1522866540000,
    "is_expiring": true,
    "owner_email": "v********@***.com",
    "created_time": 1522745900919,
    "document_ids": [
      {
        "image_string": "<BASE 64 Image String>",
        "document_name": "Employee NDA.pdf",
        "pages": [
          {
            "image_string": "<BASE 64 Image String>",
            "page": 0,
            "is_thumbnail": true
          }
        ],
        "document_size": 27059,
        "document_order": "0",
        "total_pages": 2,
        "document_id": "2000000493003"
      }
    ],
    "self_sign": false,
    "in_process": false,
    "request_type_name": "Others",
    "request_id": "2000000493009",
    "request_type_id": "2000000000135",
    "owner_last_name": "",
    "actions": [
      {
        "verify_recipient": false,
        "action_id": "2000000493012",
        "action_type": "SIGN",
        "private_notes": "",
        "recipient_name": "S**********",
        "recipient_email": "s*******@***.com",
        "signing_order": 0,
        "fields": [
          {
            "field_id": "2000000493016",
            "field_type_id": "2000000000141",
            "field_category": "image",
            "field_label": "Signature",
            "is_mandatory": true,
            "page_no": 0,
            "document_id": "2000000493003",
            "field_name": "Signature",
            "y_coord": 3,
            "action_id": "2000000493012",
            "abs_width": 22,
            "field_type_name": "Signature",
            "description_tooltip": "",
            "x_coord": 42,
            "abs_height": 5
          },
          {
            "field_id": "2000000493017",
            "field_type_id": "2000000000143",
            "field_category": "image",
            "field_label": "Initial",
            "is_mandatory": true,
            "page_no": 0,
            "document_id": "2000000493003",
            "field_name": "Initial",
            "y_coord": 3,
            "action_id": "2000000493012",
            "abs_width": 18,
            "field_type_name": "Initial",
            "description_tooltip": "",
            "x_coord": 71,
            "abs_height": 5
          },
          {
            "field_id": "2000000493015",
            "field_type_id": "2000000000149",
            "text_property": {
              "is_italic": false,
              "is_underline": false,
              "font_color": "000000",
              "font_size": 11,
              "is_read_only": false,
              "is_bold": false,
              "font": "Arial"
            },
            "field_category": "textfield",
            "field_label": "Email",
            "is_mandatory": true,
            "default_value": "",
            "page_no": 0,
            "document_id": "2000000493003",
            "field_name": "Email",
            "y_coord": 3,
            "action_id": "2000000493012",
            "abs_width": 30,
            "field_type_name": "Email",
            "description_tooltip": "",
            "x_coord": 4,
            "abs_height": 5
          },
          {
            "field_id": "2000000493014",
            "field_type_id": "2000000000137",
            "field_category": "checkbox",
            "field_label": "Checkbox_1",
            "is_mandatory": false,
            "default_value": false,
            "page_no": 0,
            "document_id": "2000000493003",
            "field_name": "Checkbox_1",
            "y_coord": 10,
            "action_id": "2000000493012",
            "abs_width": 18,
            "is_read_only": false,
            "field_type_name": "Checkbox",
            "description_tooltip": "",
            "x_coord": 80,
            "abs_height": 5
          }
        ],
        "allow_signing": true,
        "action_status": "UNOPENED",
        "recipient_phonenumber": "",
        "recipient_countrycode": ""
      }
    ]
  },
  "status": "success"
}

Arguments

JSONObject
JSONObject
request_name
string
name to be given to the signature request
request_type_id
string
Document Category Id
notes
string
Message to be sent to all recipients in common
expiration_days
int
No of days after which the document will expire.
is_sequential
Boolean
Sequential signing / Parallel Signing[true/false]
email_reminders
boolean
Send automatic reminders
reminder_period
int
Send automatic reminders once in [n] days
folder_id
string
Folder
JSONArray
List of recipients

Get details of a particular document

GET https://sign.zoho.com/api/v1/requests/[Request Id]

Get the details of a particular document which tells the details of the document including the status of the document. Use the key “request_status” to check for document completion

Request Example

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

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
  "code": 0,
  "requests":
    {
      "request_status": "inprogress",
      "notes": "Hi\nA note\nMr. Tester\nHow ar eyouuu ?",
      "owner_id": "2000000002002",
      "description": "",
      "request_name": "Leave a note test",
      "modified_time": 1522746018025,
      "action_time": 1522746018310,
      "is_deleted": false,
      "expiration_days": 1,
      "is_sequential": true,
      "sign_submitted_time": 1522746018310,
      "owner_first_name": "V********",
      "sign_percentage": 33.34,
      "expire_by": 1522866540000,
      "is_expiring": true,
      "owner_email": "v******@***.com",
      "created_time": 1522746018025,
      "document_ids": [
        {
          "document_name": "Employee NDA.pdf",
          "document_size": 26591,
          "document_order": "0",
          "total_pages": 2,
          "document_id": "2000000492171"
        }
      ],
      "self_sign": false,
      "in_process": false,
      "request_type_name": "Others",
      "request_id": "2000000492177",
      "request_type_id": "2000000000135",
      "owner_last_name": "",
      "actions": [
        {
          "verify_recipient": false,
          "action_id": "2000000492180",
          "action_type": "SIGN",
          "private_notes": "",
          "recipient_name": "S**********",
          "recipient_email": "s*******@***.com",
          "signing_order": 0,
          "allow_signing": true,
          "action_status": "UNOPENED",
          "recipient_phonenumber": "",
          "recipient_countrycode": ""
        }
      ]
    },
  "message": "Document has been retrieved",
  "status": "success"
}

Get documents list

GET https://sign.zoho.com/api/v1/requests

This will help you to fetch the list of documents in your account.

Request Example

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

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
  "code": 0,
  "requests": [
    {
      "request_status": "inprogress",
      "notes": "Hi\nA note\nMr. Tester\nHow ar eyouuu ?",
      "owner_id": "2000000002002",
      "description": "",
      "request_name": "Leave a note test",
      "modified_time": 1522746018025,
      "action_time": 1522746018310,
      "is_deleted": false,
      "expiration_days": 1,
      "is_sequential": true,
      "sign_submitted_time": 1522746018310,
      "owner_first_name": "V********",
      "sign_percentage": 33.34,
      "expire_by": 1522866540000,
      "is_expiring": true,
      "owner_email": "v******@***.com",
      "created_time": 1522746018025,
      "document_ids": [
        {
          "document_name": "Employee NDA.pdf",
          "document_size": 26591,
          "document_order": "0",
          "total_pages": 2,
          "document_id": "2000000492171"
        }
      ],
      "self_sign": false,
      "in_process": false,
      "request_type_name": "Others",
      "request_id": "2000000492177",
      "request_type_id": "2000000000135",
      "owner_last_name": "",
      "actions": [
        {
          "verify_recipient": false,
          "action_id": "2000000492180",
          "action_type": "SIGN",
          "private_notes": "",
          "recipient_name": "S**********",
          "recipient_email": "s*******@***.com",
          "signing_order": 0,
          "allow_signing": true,
          "action_status": "UNOPENED",
          "recipient_phonenumber": "",
          "recipient_countrycode": ""
        }
      ]
    }
  ],
  "message": "Document list retrieved successfully",
  "page_context": {
    "sort_column": "created_time",
    "has_more_rows": true,
    "start_index": 1,
    "total_count": 1,
    "sort_order": "DESC",
    "row_count": 10
  },
  "status": "success"
}

Arguments

JSONObject
Display Name of the contact. Max-length [200]
page_context
JSONObject
Display Name of the contact. Max-length [200]
row_count
int
No of rows to be retrieved [10,25,50,100]
start_index
int
Start Index
sort_column
string
Sort Column
sort_order
string
Sort By [ASC/DESC]

Download Pdf

GET https://sign.zoho.com/api/v1/requests/[Request ID]/pdf

Retrieves the PDF content that can be downloaded.

Request Example

$ curl https://sign.zoho.com/api/v1/requests/[Request ID]/pdf \
    -X GET \
    -H "Authorization: Zoho-oauthtoken <Oauth Token>"

Response Example

HTTP/1.1 200 OK
Content-Type:application/pdf;
            OR
Content-Type:application/zip; (In case of multiple documents)

Download completion certificate

GET https://sign.zoho.com/api/v1/requests/[Request ID]/completioncertificate

Retrieves the Completion certificate pdf content.

Request Example

$ curl https://sign.zoho.com/api/v1/requests/[Request ID]/completioncertificate \
    -X GET \
    -H "Authorization: Zoho-oauthtoken <Oauth Token>"

Response Example

HTTP/1.1 200 OK
Content-Type:application/pdf;

Recall Document

POST https://sign.zoho.com/api/v1/requests/[Request ID]/recall

Recalling a document cancels the signing process. Once you recall a document, recipients can no longer view or sign it. You can recall a document if you send an incorrect document, or if you send it to an incorrect email address.

Request Example

$ curl https://sign.zoho.com/api/v1/requests/[Request ID]/recall \
    -X POST \
    -H "Authorization: Zoho-oauthtoken <Oauth Token>"

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
    "code": 0,
    "action_time": 1546600722216,
    "message": "Document has been recalled",
    "status": "success"
}

Create new Folder

POST https://sign.zoho.com/api/v1/folders

This will help you to create a new folder.

Request Example

$ curl https://sign.zoho.com/api/v1/folders \
    -H "Authorization: Zoho-oauthtoken <Oauth Token>"\
    -d 'data={
  "folders": {
    "folder_name": "Quote Folder"
  }
}'

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
  "code": 0,
  "folders": {
    "folder_name": "Quote Folder",
    "folder_id": "2000000495005"
  },
  "message": "Folder added successfully",
  "status": "success"
}

Arguments

JSONObject
JSONObject
folder_name
string
Name of the folder

Get folder list

GET https://sign.zoho.com/api/v1/folders

This will fetch the list of folders in your account.

Request Example

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

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
  "code": 0,
  "folders": [
    {
      "folder_name": "Quote Folder",
      "folder_id": "2000000495005"
    },
    {
      "folder_name": "NDA",
      "folder_id": "2000000489161"
    }
  ],
  "message": "Folder(s) retrieved successfully",
  "status": "success"
}

Retrieve field type

GET https://sign.zoho.com/api/v1/fieldtypes

This will help you to retrieve field type.

Request Example

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

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
  "field_types": [
    {
      "field_type_id": "2000000000137",
      "field_category": "checkbox",
      "is_mandatory": false,
      "field_type_name": "Checkbox"
    },
    {
      "field_type_id": "2000000000139",
      "field_category": "radiogroup",
      "is_mandatory": false,
      "field_type_name": "Radiogroup"
    },
    {
      "field_type_id": "2000000000141",
      "field_category": "image",
      "is_mandatory": true,
      "field_type_name": "Signature"
    },
    {
      "field_type_id": "2000000000143",
      "field_category": "image",
      "is_mandatory": true,
      "field_type_name": "Initial"
    },
    {
      "field_type_id": "2000000000147",
      "field_category": "textfield",
      "is_mandatory": false,
      "field_type_name": "Textfield"
    },
    {
      "field_type_id": "2000000000149",
      "field_category": "textfield",
      "is_mandatory": true,
      "field_type_name": "Email"
    },
    {
      "field_type_id": "2000000000151",
      "field_category": "datefield",
      "is_mandatory": true,
      "field_type_name": "Date"
    },
    {
      "field_type_id": "2000000000153",
      "field_category": "textfield",
      "is_mandatory": true,
      "field_type_name": "Name"
    },
    {
      "field_type_id": "2000000000155",
      "field_category": "textfield",
      "is_mandatory": true,
      "field_type_name": "Company"
    },
    {
      "field_type_id": "2000000000157",
      "field_category": "textfield",
      "is_mandatory": true,
      "field_type_name": "Jobtitle"
    }
  ],
  "code": 0,
  "message": "Field types retrieved successfully",
  "status": "success"
}

Get document type

GET https://sign.zoho.com/api/v1/requesttypes

This will help you to find the document type.

Request Example

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

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8

{
  "code": 0,
  "message": "Document types retrieved successfully",
  "request_types": [
    {
      "request_type_description": "Others",
      "request_type_name": "Others",
      "request_type_id": "2000000000135"
    },
    {
      "request_type_description": "",
      "request_type_name": "NDA document",
      "request_type_id": "2000000322040"
    }
  ],
  "status": "success"
}

Create new document type

POST https://sign.zoho.com/api/v1/requesttypes

This will help you to create a new document type.

Request Example

$ curl https://sign.zoho.com/api/v1/requesttypes \
    -H "Authorization: Zoho-oauthtoken <Oauth Token>"\
    -d 'data={
  "request_types": {
    "request_type_name": "Quote",
    "request_type_description": ""
  }
}'

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
  "code": 0,
  "message": "Document type added successfully",
  "request_types": [
    {
      "request_type_description": "",
      "request_type_name": "Quote",
      "request_type_id": "2000000495001"
    }
  ],
  "status": "success"
}

Arguments

JSONObject
request_type
JSONObject
request_type_name
String
Document Category Name
request_type_description
string
Document Category Description

Template Management

Create customizable templates based on your needs in Zoho Sign. Templates can be used any number of times.

Oauthscopes

ZohoSign.templates.CREATE,ZohoSign.templates.READ,ZohoSign.templates.UPDATE

Create template

POST https://sign.zoho.com/api/v1/templates

This will help you to create a new template.

Request Example

$ curl https://sign.zoho.com/api/v1/templates \
    -H "Authorization: Zoho-oauthtoken <Oauth Token>"\
    -F 'file=@Path to file' \
    -F 'data={
  "templates": {
    "template_name": "Template 1",
    "request_type_id": "2000000000135",
    "expiration_days": 1,
    "is_sequential": true,
    "reminder_period": 8,
    "email_reminders": false,
    "actions": [
      {
        "action_type": "SIGN",
        "signing_order": 0,
        "recipient_name": "",
        "role": "1",
        "recipient_email": "",
        "recipient_phonenumber": "",
        "recipient_countrycode": "",
        "private_notes": "Please get back to us for further queries",
        "verify_recipient": true,
        "verification_type": "EMAIL",
        "verification_code": ""
      }
    ]
  }
}'

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
  "code": 0,
  "templates": {
    "owner_email": "v****@***.com",
    "created_time": 1522746328987,
    "email_reminders": false,
    "document_ids": [
      {
        "image_string": "<BASE 64 Image String>",
        "pages": [
          {
            "image_string": "<BASE 64 Image String>",
            "page": 0,
            "is_thumbnail": true
          }
        ],
        "document_size": 174307,
        "document_order": "0",
        "total_pages": 4,
        "document_id": "2000000493029"
      }
    ],
    "notes": "",
    "reminder_period": 8,
    "owner_id": "2000000002002",
    "document_fields": [
      {
        "document_id": "2000000493029",
        "fields": []
      }
    ],
    "description": "",
    "template_name": "Template 1",
    "modified_time": 1522746328987,
    "is_deleted": false,
    "expiration_days": 1,
    "is_sequential": true,
    "template_id": "2000000493035",
    "request_type_name": "Others",
    "owner_first_name": "V*******",
    "request_type_id": "2000000000135",
    "owner_last_name": "",
    "actions": [
      {
        "verify_recipient": true,
        "role": "1",
        "action_id": "2000000493038",
        "action_type": "SIGN",
        "private_notes": "Please get back to us for further queries",
        "recipient_email": "",
        "signing_order": 0,
        "verification_type": "EMAIL",
        "fields": [],
        "recipient_name": "",
        "recipient_phonenumber": "",
        "recipient_countrycode": ""
      }
    ]
  },
  "message": "Template has been added ",
  "status": "success"
}

Arguments

file
File
File that needs to be uploaded
JSONObject
templates
JSONObject
template_name
string
Name of the template
notes
string
Note for the template
request_type_id
string
Document Category Id
notes
string
Message to be sent to all recipients in common
expiration_days
int
No of days after which the document will expire when converted from template
is_sequential
Boolean
Sequential signing / Parallel Signing[true/false]
email_reminders
boolean
Send automatic reminders
reminder_period
int
Send automatic reminders once in [n] days
folder_id
string
Folder
JSONArray
List of recipients

Update template

PUT https://sign.zoho.com/api/v1/templates/[Template Id]

This will help you to update an existing template.

Request Example

$ curl https://sign.zoho.com/api/v1/requests/[Template Id] \
    -X PUT \
    -H "Authorization: Zoho-oauthtoken <Oauth Token>" \
    -d 'data={
  "templates": {
    "document_fields": [
      {
        "fields": {
          "image_fields": [
            {
              "field_type_id": "2000000000141",
              "field_name": "Signature",
              "document_id": "2000000493029",
              "is_mandatory": true,
              "page_no": 0,
              "x_coord": 17,
              "y_coord": 12,
              "abs_width": 22,
              "abs_height": 5
            },
            {
              "field_type_id": "2000000000143",
              "field_name": "Initial",
              "document_id": "2000000493029",
              "is_mandatory": true,
              "page_no": 0,
              "x_coord": 59,
              "y_coord": 14,
              "abs_width": 8,
              "abs_height": 5
            }
          ],
          "date_fields": [],
          "check_boxes": [],
          "radio_groups": [],
          "text_fields": []
        },
        "document_id": "2000000493029",
        "deleted_fields": []
      }
    ],
    "actions": [
      {
        "action_id": "2000000493038",
        "action_type": "SIGN",
        "signing_order": 0,
        "recipient_name": "",
        "role": "1",
        "recipient_email": "",
        "recipient_phonenumber": "",
        "recipient_countrycode": "",
        "private_notes": "Please get back to us for further queries",
        "verify_recipient": true,
        "verification_type": "EMAIL",
        "deleted_fields": [],
        "deleted_radio_fields": [],
        "fields": {
          "text_fields": [
            {
              "field_type_id": "2000000000155",
              "field_name": "Company",
              "document_id": "2000000493029",
              "is_mandatory": true,
              "page_no": 0,
              "x_coord": 31,
              "y_coord": 1,
              "abs_width": 16,
              "abs_height": 5,
              "text_property": {
                "font": "Arial",
                "font_size": 11,
                "font_color": "000000",
                "is_bold": false,
                "is_italic": false
              }
            },
            {
              "field_type_id": "2000000000149",
              "field_name": "Email",
              "document_id": "2000000493029",
              "is_mandatory": true,
              "page_no": 0,
              "x_coord": 56,
              "y_coord": 1,
              "abs_width": 31,
              "abs_height": 5,
              "text_property": {
                "font": "Arial",
                "font_size": 11,
                "font_color": "000000",
                "is_bold": false,
                "is_italic": false
              }
            }
          ],
          "image_fields": [
            {
              "field_type_id": "2000000000141",
              "field_name": "Signature",
              "document_id": "2000000493029",
              "is_mandatory": true,
              "page_no": 0,
              "x_coord": 2,
              "y_coord": 1,
              "abs_width": 22,
              "abs_height": 5
            }
          ],
          "date_fields": [],
          "check_boxes": [
            {
              "field_type_id": "2000000000137",
              "field_name": "Checkbox_1",
              "document_id": "2000000493029",
              "is_mandatory": false,
              "page_no": 0,
              "x_coord": 50,
              "y_coord": 1,
              "abs_width": 20,
              "abs_height": 5,
              "default_value": false
            }
          ],
          "radio_groups": []
        }
      }
    ]
  }
}'

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8

{
  "code": 0,
  "templates": {
    "owner_email": "v****@***.com",
    "created_time": 1522746328987,
    "email_reminders": false,
    "document_ids": [
      {
        "image_string": "<BASE 64 Image String>",
        "document_name": "4page170kbsquared file testrotated.pdf",
        "pages": [
          {
            "image_string": "<BASE 64 Image String>",
            "page": 0,
            "is_thumbnail": true
          }
        ],
        "document_size": 174307,
        "document_order": "0",
        "total_pages": 4,
        "document_id": "2000000493029"
      }
    ],
    "notes": "",
    "reminder_period": 8,
    "owner_id": "2000000002002",
    "document_fields": [
      {
        "document_id": "2000000493029",
        "fields": [
          {
            "field_id": "2000000493047",
            "field_type_id": "2000000000141",
            "field_category": "image",
            "field_label": "Signature",
            "is_mandatory": true,
            "page_no": 0,
            "document_id": "2000000493029",
            "field_name": "Signature",
            "y_coord": 12,
            "abs_width": 22,
            "field_type_name": "Signature",
            "description_tooltip": "",
            "x_coord": 17,
            "abs_height": 5
          },
          {
            "field_id": "2000000493048",
            "field_type_id": "2000000000143",
            "field_category": "image",
            "field_label": "Initial",
            "is_mandatory": true,
            "page_no": 0,
            "document_id": "2000000493029",
            "field_name": "Initial",
            "y_coord": 14,
            "abs_width": 18,
            "field_type_name": "Initial",
            "description_tooltip": "",
            "x_coord": 59,
            "abs_height": 5
          }
        ]
      }
    ],
    "description": "",
    "template_name": "Template 1",
    "modified_time": 1522746467719,
    "is_deleted": false,
    "expiration_days": 1,
    "is_sequential": true,
    "template_id": "2000000493035",
    "request_type_name": "Others",
    "owner_first_name": "V*******",
    "request_type_id": "2000000000135",
    "owner_last_name": "",
    "actions": [
      {
        "verify_recipient": true,
        "role": "1",
        "action_id": "2000000493038",
        "action_type": "SIGN",
        "private_notes": "Please get back to us for further queries",
        "recipient_email": "",
        "signing_order": 0,
        "verification_type": "EMAIL",
        "fields": [
          {
            "field_id": "2000000493043",
            "field_type_id": "2000000000137",
            "field_category": "checkbox",
            "field_label": "Checkbox_1",
            "is_mandatory": false,
            "default_value": false,
            "page_no": 0,
            "document_id": "2000000493029",
            "field_name": "Checkbox_1",
            "y_coord": 1,
            "action_id": "2000000493038",
            "abs_width": 20,
            "is_read_only": false,
            "field_type_name": "Checkbox",
            "description_tooltip": "",
            "x_coord": 50,
            "abs_height": 5
          },
          {
            "field_id": "2000000493044",
            "field_type_id": "2000000000155",
            "text_property": {
              "is_italic": false,
              "is_underline": false,
              "font_color": "000000",
              "font_size": 11,
              "is_read_only": false,
              "is_bold": false,
              "font": "Arial"
            },
            "field_category": "textfield",
            "field_label": "Company",
            "is_mandatory": true,
            "default_value": "",
            "page_no": 0,
            "document_id": "2000000493029",
            "field_name": "Company",
            "y_coord": 1,
            "action_id": "2000000493038",
            "abs_width": 16,
            "field_type_name": "Company",
            "description_tooltip": "",
            "x_coord": 31,
            "abs_height": 5
          },
          {
            "field_id": "2000000493045",
            "field_type_id": "2000000000149",
            "text_property": {
              "is_italic": false,
              "is_underline": false,
              "font_color": "000000",
              "font_size": 11,
              "is_read_only": false,
              "is_bold": false,
              "font": "Arial"
            },
            "field_category": "textfield",
            "field_label": "Email",
            "is_mandatory": true,
            "default_value": "",
            "page_no": 0,
            "document_id": "2000000493029",
            "field_name": "Email",
            "y_coord": 1,
            "action_id": "2000000493038",
            "abs_width": 31,
            "field_type_name": "Email",
            "description_tooltip": "",
            "x_coord": 56,
            "abs_height": 5
          },
          {
            "field_id": "2000000493046",
            "field_type_id": "2000000000141",
            "field_category": "image",
            "field_label": "Signature",
            "is_mandatory": true,
            "page_no": 0,
            "document_id": "2000000493029",
            "field_name": "Signature",
            "y_coord": 1,
            "action_id": "2000000493038",
            "abs_width": 22,
            "field_type_name": "Signature",
            "description_tooltip": "",
            "x_coord": 2,
            "abs_height": 5
          }
        ],
        "recipient_name": "",
        "recipient_phonenumber": "",
        "recipient_countrycode": ""
      }
    ]
  },
  "status": "success"
}

Arguments

JSONObject
templates
JSONObject
template_name
string
Name of the template
notes
string
Note for the template
request_type_id
string
Document Category Id
notes
string
Message to be sent to all recipients in common
expiration_days
int
No of days after which the document will expire when converted from template
is_sequential
Boolean
Sequential signing / Parallel Signing[true/false]
email_reminders
boolean
Send automatic reminders
reminder_period
int
Send automatic reminders once in [n] days
folder_id
string
Folder
JSONArray
List of recipients

Get template list

GET https://sign.zoho.com/api/v1/templates

This will help you to fetch the list of templates in your account.

Request Example

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

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
  "code": 0,
  "templates": [
    {
      "owner_email": "v******@***.com",
      "created_time": 1522746328987,
      "email_reminders": false,
      "document_ids": [
        {
          "document_name": "4page170kbsquared file testrotated.pdf",
          "document_size": 174307,
          "document_order": "0",
          "total_pages": 4,
          "document_id": "2000000493029"
        }
      ],
      "notes": "",
      "reminder_period": 8,
      "owner_id": "2000000002002",
      "description": "",
      "template_name": "Template 1",
      "modified_time": 1522747039504,
      "is_deleted": false,
      "expiration_days": 1,
      "is_sequential": true,
      "template_id": "2000000493035",
      "request_type_name": "Others",
      "owner_first_name": "V*******",
      "request_type_id": "2000000000135",
      "owner_last_name": "",
      "actions": [
        {
          "verify_recipient": true,
          "role": "1",
          "action_id": "2000000493038",
          "action_type": "SIGN",
          "private_notes": "Please get back to us for further queries",
          "recipient_email": "",
          "signing_order": 0,
          "verification_type": "EMAIL",
          "recipient_name": "",
          "recipient_phonenumber": "",
          "recipient_countrycode": ""
        }
      ]
    }
  ],
  "message": "Template list retrieved successfully",
  "page_context": {
    "sort_column": "created_time",
    "has_more_rows": true,
    "start_index": 1,
    "total_count": 12,
    "sort_order": "DESC",
    "row_count": 10
  },
  "status": "success"
}

Arguments

JSONObject
page_context
JSONObject
row_count
int
No of rows to be retrieved [10,25,50,100]
start_index
int
Start Index
sort_column
string
Sort Column
sort_order
string
Sort By [ASC/DESC]

Get template details

GET https://sign.zoho.com/api/v1/templates[Template ID]

Get the details of a particular template using its id - specifically lists the pre fill fields that need to be sent in order to convert the template into a document.

Request Example

$ curl https://sign.zoho.com/api/v1/templates/[Template ID] \
    -X GET \
    -H "Authorization: Zoho-oauthtoken <Oauth Token>"

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
  "code": 0,
  "templates":
    {
      "owner_email": "v******@***.com",
      "created_time": 1522746328987,
      "email_reminders": false,
      "document_ids": [
        {
          "document_name": "4page170kbsquared file testrotated.pdf",
          "document_size": 174307,
          "document_order": "0",
          "total_pages": 4,
          "document_id": "2000000493029"
        }
      ],
      "notes": "",
      "reminder_period": 8,
      "owner_id": "2000000002002",
      "description": "",
      "template_name": "Template 1",
      "modified_time": 1522747039504,
      "is_deleted": false,
      "expiration_days": 1,
      "is_sequential": true,
      "template_id": "2000000493035",
      "request_type_name": "Others",
      "owner_first_name": "V*******",
      "request_type_id": "2000000000135",
      "owner_last_name": "",
      "actions": [
        {
          "verify_recipient": true,
          "role": "1",
          "action_id": "2000000493038",
          "action_type": "SIGN",
          "private_notes": "Please get back to us for further queries",
          "recipient_email": "",
          "signing_order": 0,
          "verification_type": "EMAIL",
          "recipient_name": "",
          "recipient_phonenumber": "",
          "recipient_countrycode": ""
        }
      ]
    },
  "message": "Template list retrieved successfully",
  "status": "success"
}

Send document out for signature using templates

POST https://sign.zoho.com/api/v1/templates/[Template Id]/createdocument

In order to use the template, the recipient details need to be given. In previous call the actions array contains number of recipients. It may or may not have an email address. When using the template, the actions need to be sent along with email id and name for all. Number of actions cannot be changed. In case there are document fields to be filled (document_fields array) then the value for those also needs to be filled. If the “is_mandatory” is true for a field then it must have a value. Else value need not be sent.

Request Example

$ curl https://sign.zoho.com/api/v1/templates/[Template Id]/createdocument \
    -X POST \
    -H "Authorization: Zoho-oauthtoken <Oauth Token>"\
    -d 'data={
  "templates": {
    "field_data": {
      "field_text_data": {},
      "field_boolean_data": {}
    },
    "actions": [
      {
        "action_id": "2000000468052",
        "action_type": "SIGN",
        "recipient_name": "S********",
        "role": "ts1",
        "recipient_email": "s********@***.com",
        "recipient_phonenumber": "",
        "recipient_countrycode": "",
        "private_notes": "",
        "verify_recipient": true,
        "verification_type": "EMAIL"
      }
    ],
    "notes": ""
  }
}&is_quicksend=true'

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
  "code": 0,
  "requests": {
    "request_status": "inprogress",
    "notes": "Hi\nA note\nMr. Tester\nHow ar eyouuu ?",
    "owner_id": "2000000002002",
    "description": "",
    "request_name": "Leave a note test",
    "modified_time": 1522746018025,
    "action_time": 1522746018310,
    "is_deleted": false,
    "expiration_days": 1,
    "is_sequential": true,
    "sign_submitted_time": 1522746018310,
    "owner_first_name": "V*******",
    "sign_percentage": 33.34,
    "expire_by": 1522866540000,
    "is_expiring": true,
    "owner_email": "v**********@***.com",
    "created_time": 1522746018025,
    "document_ids": [
      {
        "image_string": "<BASE 64 Image String>",
        "document_name": "Employee NDA.pdf",
        "pages": [
          {
            "image_string": "<BASE 64 Image String>",
            "page": 0,
            "is_thumbnail": true
          }
        ],
        "document_size": 26591,
        "document_order": "0",
        "total_pages": 2,
        "document_id": "2000000492171"
      }
    ],
    "self_sign": false,
    "in_process": false,
    "request_type_name": "Others",
    "request_id": "2000000492177",
    "request_type_id": "2000000000135",
    "owner_last_name": "",
    "actions": [
      {
        "verify_recipient": false,
        "action_id": "2000000492180",
        "action_type": "SIGN",
        "private_notes": "",
        "recipient_email": "s***********@***.com",
        "signing_order": 0,
        "fields": [
          {
            "field_id": "2000000492182",
            "field_type_id": "2000000000141",
            "field_category": "image",
            "field_label": "Signature",
            "is_mandatory": true,
            "page_no": 0,
            "document_id": "2000000492171",
            "field_name": "Signature",
            "y_coord": 3,
            "action_id": "2000000492180",
            "abs_width": 22,
            "field_type_name": "Signature",
            "description_tooltip": "",
            "x_coord": 42,
            "abs_height": 5
          },
          {
            "field_id": "2000000492183",
            "field_type_id": "2000000000143",
            "field_category": "image",
            "field_label": "Initial",
            "is_mandatory": true,
            "page_no": 0,
            "document_id": "2000000492171",
            "field_name": "Initial",
            "y_coord": 3,
            "action_id": "2000000492180",
            "abs_width": 18,
            "field_type_name": "Initial",
            "description_tooltip": "",
            "x_coord": 71,
            "abs_height": 5
          }
        ],
        "recipient_name": "s***********",
        "allow_signing": true,
        "action_status": "UNOPENED",
        "recipient_phonenumber": "",
        "recipient_countrycode": ""
      }
    ]
  },
  "status": "success"
}

Arguments

JSONObject
templates
JSONObject
request_name
string
Name in which the document needs to be created by default same as template name.
notes
string
Message to be sent to all recipients in common
field_data
JSONObject
Prefill field data
field_text_data
JSONObject {“field_label”:“field_value”}
Text field data
field_boolean_data
JSONObject {“field_label”:“field_value”}
Checkbox data
JSONArray
List of recipients
recipient_name
string
Recipient name
recipient_email
string
Recipient email
private_notes
string
Private notes for each recipient
verify_recipient
boolean
Authentication needs be done or not
verification_type
string
Verification Mode [EMAIL]
is_quicksend
boolean
Quick Send