Add Signature Details

Purpose

To add and configure signature details, such as organization and counterparty representatives, receivers, in-person signer hosts, signing order, authentication type, language, stamp paper type, e-Stamp settings, completion duration, and reminders.

Endpoints

POST /contracts/{contractApiName}/signers

Request Details

Request URL

https://contracts.zoho.com/api/v1/contracts/{contractApiName}/signers

Authorization

Authorization: Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6

Scope

contracts.contracts.CREATE, contracts.contracts.ALL

Possible Operation Types

ALL - Full access to contract information
CREATE - Add signature information

Sample Request

Copiedcurl "https://contracts.zoho.com/api/v1/contracts/msa-with-zenith-dynamics/signers"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"

Input JSON Keys

reminderDaysnumber
Represents the number of days before the deadline to send reminders to signers.
daysToCompletenumber
Represents the total number of days allowed for completing the signing process.
signPapernumber
Represents the type of paper used for signing.
Value Description
0 White Paper
1 Digitized Stamp Paper
2 e-Stamp Paper
usersJSON Array
The array represents the details of all signer groups involved in the contract signing process. The signer groups are organization representatives, counterparty representatives, other representatives, receivers, and in-person signer hosts.
interpartySignersJSON Array
The array represents the details of organization representatives and counterparty representatives associated with the contract.
receiversJSON Array
Represents the list of recipients who receive a copy of the contract after signing is completed. They do not participate in the signing process.
thirdpartySignersJSON Array
Represents the list of other representatives participate in signing the contract but do not represent either the organization or counterparty side.
displayNamestring
Represents the name of the other representatives or receivers.
messagestring
Represents a private message or note sent along with the signing request.
emailIdstring
Represents the email ID of the other representatives or receivers.
idstring
Represents the unique ID of the organization or counterparty representatives maintained in Zoho Contracts.
orderinteger
Represents the signing order of the singers when the signing order is enabled.
hostJSON Object
Represents the details of the in-person signer hosts.
languagestring
Represents the signer's preferred language code for email notifications and the application user interface (e.g, "en" for English).
authenticationJSON Object
The array represents the authentication details of each signer to verify them before signing, such as the authentication type and corresponding information.
auth_typenumber
Represents the authentication type used to verify the signers.
Value Description
1 Email
2 SMS
3 Offline
country_codestring
Represents the country dialing code used for SMS authentication (e.g, "IN").
Note: When SMS authentication is selected, both the country code and phone number must be provided.
phone_nostring
Represents the phone number used for OTP authentication when SMS authentication is selected.
auth_codenumber
Represents the access code used for the Offline authentication (e.g, "678540").
Note: When the Offline authentication type is selected, the authentication code must contain 6 digits.

Sample Input

Copied{
  "reminderDays": 3,
  "daysToComplete": 10,
  "signPaper": 0,
  "users": [
    {
      "interpartySigners": [
        {
          "id": "3000000471101",
          "message": "Please review and sign at the earliest.",
          "language": "en",
          "authentication": {
            "auth_type": 1
          },
          "order": 1
        },
        {
          "id": "3000000471102",
          "language": "en",
          "host": {
            "id": "3000000471101"
          },
          "authentication": {
            "auth_type": 2,
            "country_code": "IN",
            "phone_no": "9876543210"
          },
          "order": 2
        }
      ],
      "thirdpartySigners": [
        {
          "emailId": "sophia.wilson@externalmail.com",
          "displayName": "Sophia Wilson",
          "order": 3
        }
      ],
      "receivers": [
        {
          "emailId": "john.smith@zenithdynamics.com",
          "displayName": "John Smith",
          "language": "en",
          "authentication": {
            "auth_type": 3,
            "auth_code": "859263"
          },
          "order": 4
        }
      ]
    }
  ]
}

Response JSON Keys

signersJSON Array
The array represents the details of all signer groups involved in the contract signing process. The signer groups are organization representatives, counterparty representatives, other representatives, receivers, and in-person signer hosts.
interpartySignersJSON Array
The array represents the details of organization representatives and counterparty representatives associated with the contract.
receiversJSON Array
Represents the list of recipients who receive a copy of the contract after signing is completed. They do not participate in the signing process.
thirdpartySignersJSON Array
Represents the list of other representatives participate in signing the contract but do not represent either the organization or counterparty side.
isOrgUserboolean
Represents whether the signer is a representative of the organization.
displayNamestring
Represents the name of the organization representative, counterparty representative, other representative, or receiver.
emailIdstring
Represents the email ID of the organization representative, counterparty representative, other representative, or receiver.
idstring
Represents the unique ID of the organization or counterparty representatives maintained in Zoho Contracts.
orderinteger
Represents the signing order of the singers when the signing order is enabled.
hostJSON Object
Represents the details of the in-person signer hosts.
languagestring
Represents the signer's preferred language code for email notifications and the application user interface (e.g, "en" for English).
authenticationJSON Object
The array represents the authentication details of each signer to verify them before signing, such as the authentication type and corresponding information.
auth_typenumber
Represents the authentication type used to verify the signers.
Value Description
1 Email
2 SMS
3 Offline
country_codestring
Represents the country dialing code used for SMS authentication (e.g, "IN").
Note: When SMS authentication is selected, both the country code and phone number must be provided.
phone_nostring
Represents the phone number used for OTP authentication when SMS authentication is selected.
auth_codenumber
Represents the access code used for the Offline authentication (e.g, "678540").
Note: When the Offline authentication type is selected, the authentication code must contain 6 digits.

Sample Response

Copied{
  "signers": [
    {
      "receivers": [
        {
          "displayName": "John Smith",
          "emailId": "john.smith@zenithdynamics.com",
          "language": "en",
          "actions": [],
          "order": 1,
          "authentication": {
            "auth_type": 3,
            "auth_code": "859263"
          }
        }
      ],
      "interpartySigners": [
        {
          "isOrgUser": true,
          "displayName": "David Lee",
          "language": "en",
          "emailId": "david.lee@zenithdynamics.com",
          "id": "3000000471101",
          "message": "Please review and sign at the earliest.",
          "actions": [],
          "order": 2,
          "authentication": {
            "auth_type": 1
          }
        },
        {
          "isOrgUser": true,
          "displayName": "Emma Brown",
          "host": {
            "id": "3000000471101"
          },
          "language": "en",
          "emailId": "emma.brown@zylker.com",
          "id": "3000000471102",
          "actions": [],
          "order": 3,
          "authentication": {
            "phone_no": "9876543210",
            "country_code": "IN",
            "auth_type": 2
          }
        }
      ],
      "thirdpartySigners": [
        {
          "displayName": "Sophia Wilson",
          "emailId": "sophia.wilson@externalmail.com",
          "actions": [],
          "order": 4
        }
      ]
    }
  ]
}

Possible Errors

INVALID_URL_PATTERNHTTP 404

Request URL is incorrect. Specify a valid request URL.

Resolution: Provide a valid URL as mentioned in the Request URL section above.

OAUTH_SCOPE_MISMATCHHTTP 401

Unauthorized. The client does not have contracts.contracts.CREATE scope.

Resolution: Create a new client with valid scope. Refer to the Scope section above.

NO_PERMISSIONHTTP 403

Permission denied to create. The user does not have permission to create records.

Resolution: Contact the organization administrator to request the required access.

INTERNAL_ERRORHTTP 500

Internal Server Error.

Resolution: Unexpected and unhandled exception in the server. Try again later or contact the support team for assistance.

INVALID_REQUEST_METHODHTTP 400

The HTTP request method is not a valid one.

Resolution: Specify a valid request method as specified in the Endpoints section above.

AUTHORIZATION_FAILEDHTTP 400

The user does not have sufficient privilege to create module details.

Resolution: Contact the organization administrator to request the required access.

INVALID_SIGNER_MAIL_ADDRESSHTTP 409

Each signer's email address must be unique.

Resolution: Ensure that each signer in the request has a unique email address. Update the payload with distinct email addresses for all signers before resubmitting the request.

INVALID_SIGNING_ORDERHTTP 409

Possible Reasons	Resolution
The signing order number exceeds the maximum possible value.	Ensure that the signing order values assigned to signers do not exceed the total number of signers or the supported range. Provide valid signing order numbers.
The signing order cannot be less than zero.	Verify that all signing order values are non-negative numbers. Negative values are not supported.
The signing order is invalid as the signing order value for some signers is undefined.	Ensure that each signer in the request has a defined and valid signing order. Add missing signing order values before resubmitting the request.

Value	Description
0	White Paper
1	Digitized Stamp Paper
2	e-Stamp Paper

Value	Description
1	Email
2	SMS
3	Offline

Value	Description
1	Email
2	SMS
3	Offline