Import Contract

Purpose

To import contracts initiated by your organization in various states - Draft, Signed, Active, or Expired, and contracts initiated by the counterparty in Draft or Signed states. The import contract process involves two steps:

Uploading the contract documents using the Upload File API.
Providing the uploaded file references and contract details using the Import Contract API.

Note:

If multiple documents are required for the import, such as the original document, signed copy, and digital sign certificate, each file must be uploaded individually. After each upload, retrieve the corresponding ID and include all relevant IDs when calling the Import Contract API.
Importing signed and expired contracts along with their amendment or renewal history is not supported.
For developers who are already using the previous Import Draft Contract API, you can continue to use the API.

Endpoints

POST /uploadfile

POST /importcontract

Request Details

1. Request URL: First API Call

https://contracts.zoho.com/api/v1/contracts/uploadfile?module={File-Type}

Note:

The request should use the multipart/form-data Content-Type to support file uploads.

The request URL should contain the query parameter ?module={File-Type} to specify the type of file being uploaded, as mentioned below

File types for contracts initiated by your organization:

File Type	Description
uploadDraftDetail	Represents the contract document. Applicable for importing draft contracts. Supported file formats: .doc, .docx, and .rtf.
uploadOriginalDetail	Represents the original contract's document. Applicable for importing contracts in these statuses: Signed and Active, Signed but Not Active, and Expired. Supported file formats: .doc, .docx, and .rtf
uploadSignedDetail	Represents the signed PDF document. Supported file format: .pdf
uploadDigiSignedDetail	Represents the digital sign certificate. Supported file format: .pdf

File types for contracts initiated by the counterparty:

File Type	Description
uploadCpDraftDetail	Represents the counterparty initiated contract document. Applicable for importing counterparty initiated draft contracts. Supported file formats: .doc, .docx, and .rtf.
uploadCpSignedDetail	Represents the counterparty initiated contract's signed PDF document. Supported file format: .pdf
uploadCpDigiSignedDetail	Represents the counterparty initiated contract's digital sign certificate. Supported file format: .pdf

Sample Request: First API Call

Copiedcurl "https://contracts.zoho.com/api/v1/contracts/uploadfile?module=uploadSignedDetail"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"
-H "Content-Type: multipart/form-data"

Response to the First API Call

Copied[
    {   
        "fileName": "Contract File Name",
        "size": 313927,
        "uploads": "8358de6593d744a581edaaf714145521"
    }
]

2. Request URL: Second API Call

https://contracts.zoho.com/api/v1/importcontract

Authorization

Authorization: Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6

Scope

contracts.contracts.CREATE, contracts.contracts.ALL

Possible Operation Types

ALL - Full access to contract details
CREATE - Create contract

Sample Request: Second API Call

Copiedcurl "https://contracts.zoho.com/api/v1/importcontract"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"

Input JSON Keys

sourcenumber
Represents the origin of the contract. The source key should be set to 2.
inputfieldsJSON Array
Represents all the fields used to create the contract.
initiatedByinteger
Represents the party that initiated the contract.
Values Description
0 Represents the contract initiated by your organization.
1 Represents the contract initiated by the counterparty.

uploadsJSON Object

Represents the ID returned by the Upload File API, mapped to the respective uploaded file type.

File types ID for contracts initiated by your organization:

Key	Description
uploadDraftDetail	ID of the uploaded document for the draft contract.
uploadOriginalDetail	ID of the uploaded contract document for the signed and not yet active, signed and active, or expired contract.
uploadSignedDetail	ID of the uploaded signed PDF document.
uploadDigiSignedDetail	ID of the uploaded digitally signed certificate.

File types ID for contracts initiated by the counterparty:

Key	Description
uploadCpDraftDetail	ID of the counterparty initiated contract document. Applicable for importing counterparty initiated draft contracts.
uploadCpSignedDetail	ID of the counterparty initiated contract's signed PDF document.
uploadCpDigiSignedDetail	ID of the counterparty initiated contract's digital sign certificate.

importContractStatesstring

Represents the status of the contract to be imported.

Status of the contract initiated by your organization:

Values	Description
draft	Represents a contract that is in the draft state.
signed	Represents a contract that has been signed but is not yet active.
active	Represents a contract that has been signed and is currently active.
expired	Represents a contract that was active but has expired.

Status of the contract initiated by the counterparty:

Values	Description
cp_draft	Represents a contract initiated by the counterparty that is in the draft state.
cp_signed	Represents a contract initiated by the counterparty that has been signed and not active, and signed and active.

importCurrentContractTerminteger
Represents the current phase of the contract. Currently, only the original version of the contract can be imported. Importing contracts with amendment or renewal history is not supported.
Value Description
1 Represents the original version of the contract, before any renewals or amendments were made.
metaApiNamestring
Represents the API name of the field used to create a contract. The field can be a particular field or a field and its related fields.
inputsJSON Array
The array represents the API names of the fields and its value used to create a contract.
inputApiNamestring
Represents the API name of the field used to create a contract. Refer to the inputApiNames List below that lists all the values of the inputApiName key.
inputValue
Represents the value of a field used to create a contract. Regarding the data type, refer to the data type of each of the inputApiNames' values in the inputApiNames List below.

inputApiNames List

This section lists all the values of the inputApiName key that indeed are the API names of each field used to create a contract.

contract-typestring
Represents the API name of the contract type.
titlestring
Represents the contract title.
descriptionstring
Represents the description of the contract.
requester-namestring
Represents the name of the person who requested the contract.
requester-departmentstring
Represents the API name of the department to which the requested person belongs to.
party-b-namestring
Represents the API name of the counterparty.
counterparty-primary-contactstring
Represents the email ID of the counterparty's primary contact.
contract-termboolean
Represents whether the contract's term is definite or indefinite.
Value Description
True Definite
False Indefinite
contract-effective-datenumber
Represents the effective date options of the contract.
Value Description
0 Specific Date
1 Execution
effective-specific-datestring
Represents the specific date on which the contract's term begins.
contract-end-datenumber
Represents the end date options of the contract.
Value Description
0 Specific Date
1 On Condition
2 On Event
3 N Months/Years
4 On Fulfillment Of Order/Service
end-specific-datestring
Represents the specific date on which the contract's term ends.
n-monthsyears-termnumber
Represents whether the contract period ends by Months or Years (i.e., N Months/Years).
Value Description
0 Months
1 Years
n-monthsyears-valuenumber
Represents the number of months or years after which the contract will end from the start date.
end-on-conditionstring
Represents the description of the condition on which the contract's term ends.
end-on-eventstring
Represents the description of the event on which the contract's term ends.
end-on-fulfillment-of-orderservicestring
Represents the description of the order/service that when fulfilled will end the contract.
termination-notice-periodnumber
Represents the minimum number of days required before the contract's end date to send/receive a termination notice. For example, 20 Days.
is-renewableboolean
Represents whether the contract is renewable or not.
Value Description
True Renewable
False Non-Renewable
renewal-typenumber
Represents whether the contract is of manual or evergreen renewal type.
Value Description
0 Manual Renewal
1 Evergreen Renewal
notice-period-before-expirationnumber
Represents the minimum number of days required before the manually renewable contract's end date to initiate the renewal. For example, 5 Days.
send-expiration-remindernumber
Represents the number of days before the contract's end date on which the renewal reminder notification has to be sent for manually renewable contracts. For example, 15 Days.
renewal-termnumber
Represents the consecutive renewal term period of an evergreen contract after the end of each term in months or years.
Value Description
0 Months
1 Years
renewal-term-periodnumber
Represents the number of months or years of the renewal term period of an evergreen contract. For example, 10 Months.
non-renewal-notice-periodnumber
Represents the minimum number of days required before the evergreen contract's end date to send/receive a non-renewal notice. For example, 10 Days.
amountBigDecimal
Represents the contract amount to be paid or received, which is based on the contract type's intent (i.e., Buy or Sell).
taxnumber
Represents whether the contract amount is inclusive of tax or the tax is as per the payment terms.
Value Description
0 All Taxes Included
1 As Per Payment Terms

Sample Input: Second API Call

Copied{
"source": 2,
"inputfields": [
     {
         "metaApiName": "contract-type",
         "inputs":[
            {
               "inputApiName": "contract-type",
               "inputValue": "service-level-agreement"
            }
         ]
      },
     {
         "metaApiName":"title",
         "inputs":[
            {
               "inputApiName":"title",
               "inputValue":"SLA with Zylker"
            }
         ]
      },
     {
         "metaApiName":"description",
         "inputs":[
            {
               "inputApiName":"description",
               "inputValue":"SLA with Zylker to agree on the service quality and responsibilities."
            }
         ]
      },
      {
         "metaApiName":"requester-name",
         "inputs":[
            {
               "inputApiName":"requester-name",
               "inputValue":"Kevin Smith"
            }
         ]
      },
      {
         "metaApiName":"requester-department",
         "inputs":[
            {
               "inputApiName":"requester-department",
               "inputValue":"accounts"
            }
         ]
      },
     {
         "metaApiName":"party-b-name",
         "inputs":[
            {
               "inputApiName":"party-b-name",
               "inputValue":"laura-holmes"
            }
         ]
      },
      {
         "metaApiName":"counterparty-primary-contact",
         "inputs":[
            {
               "inputApiName":"party-b-primary-contact-name",
               "inputValue":"laura.holmes@zylker.com"
            }
         ]
      },
      {
         "metaApiName":"contract-term",
         "inputs":[
            {
               "inputApiName":"contract-term",
               "inputValue":true
            }
         ]
      },
      {
         "metaApiName":"contract-effective-date",
         "inputs":[
            {
               "inputApiName":"contract-effective-date",
               "inputValue":0
            },
            {
               "inputApiName":"effective-specific-date",
               "inputValue":"06/11/2024"
            }
         ]
      },
      {
         "metaApiName":"contract-end-date",
         "inputs":[
            {
               "inputApiName":"contract-end-date",
               "inputValue":3
            },
            {
               "inputApiName":"n-monthsyears-value",
               "inputValue":2
            },
            {
               "inputApiName":"n-monthsyears-term",
               "inputValue":0
            }
         ]
      },
      {
         "metaApiName":"termination-notice-period",
         "inputs":[
            {
               "inputApiName":"termination-notice-period",
               "inputValue":20
            }
         ]
      },
      {
         "metaApiName":"is-renewable",
         "inputs":[
            {
               "inputApiName":"is-renewable",
               "inputValue":true
            }
         ]
      },
      
      {
         "metaApiName":"renewal-type",
         "inputs":[
            {
               "inputApiName":"renewal-type",
               "inputValue":0
            }
         ]
      },
      {
         "metaApiName":"notice-period-before-expiration",
         "inputs":[
            {
               "inputApiName":"notice-period-before-expiration",
               "inputValue":5
            }
         ]
      },
      {
         "metaApiName":"send-expiration-reminder",
         "inputs":[
            {
               "inputApiName":"send-expiration-reminder",
               "inputValue":15
            }
         ]
      },
      {
         "metaApiName":"amount",
         "inputs":[
            {
               "inputApiName":"amount",
               "inputValue":1200
            }
         ]
      },
      {
         "metaApiName":"tax",
         "inputs":[
            {
               "inputApiName":"tax",
               "inputValue":0
            }
         ]
      }
 ],
    "uploads": {
        //"uploadDraftDetail": "1610d24d68e14a319cc2c790d83adc12"
        "uploadOriginalDetail": "ae184187a9e343e7b29aa7fc045763f6",
        "uploadSignedDetail": "bf4b5704059645f3b768fed488e2a3df",
        "uploadDigiSignedDetail": "544e665fc9d04712a7f155d56527b80b"
        //"uploadCpDraftDetail": "f7289ca9f29542f09a108fe14f76f7f8"
        //"uploadCpSignedDetail": "07b96d4a83334efaa7bf9ed15ef2fde4",
        //"uploadCpDigiSignedDetail": "9a93560716364718bf84041115f3bbaa"
    },
     "importCurrentContractTerm": 1,
    "initiatedBy": "0"
    "importContractStates": "signed"
}

Response JSON Keys

Refer to Get Contract API to view the Sample Response and its corresponding Response JSON Keys section to know the details.

Response to the Second API Call

Copied{
  "contracts": [
    {
      "owner": {
        "displayName": “Smith Jones”,
        "emailId": “smith.jones@zylker.com”,
        "id": 596000000183025
      },
      "modifiedTime": “Nov 06, 2024 12:26 PM”,
      "apiName": “sla-with-zylker”,
      "endIn": 1,
      "endInType": 0,
      "resourceId": “9a57560bbf7b48628acdc2fe41317ee0”,
      "contractType": {
        "apiName": “sla”,
        "name": “SLA”,
      },
      "description": “SLA with Zylker to agree on the service quality and responsibilities.”,
      "amendments": [
        {
          "number": 4,
          "modifiedTime": “Nov 06, 2024 12:26 PM”,
          "isCurrent": false,
          "stage": {
            "apiName": “active”,
            "name": “Active”,
          },
          "systemStatus": 6,
          "latestCycleNumber": 1,
          "id": “596000000415223”,
          "type": 1,
          "startOption": 0,
          "endOption": 0,
          "docSource": 3
        }
      ],
      "source": 2,
      "isActive": 1,
      "partyA": 0,
      "isRenewable": true,
      "renewalType": 0,
      "expirationNoticePeriod": 1,
      "expirationReminderPeriod": 2,
      "terminationNoticePeriod": 12,
      "intent": 1,
      "amount": 1200,
      "currency": 65
      "taxOption": 0,
      "resourceUrl": String,
      "requesterName": “Kevin Smith”,
      "primaryContact": {
        "displayName": "Laura Holmes",
        "emailId": "laura.holmes@zylker.com",
        "id": “200989”
      },
      "contractTerm": true,
      "systemStatus": 1,
      "partyB": 1,
      "contractId": “596000000413741”,
      "name": “SLA with Zylker”,
      "counterParty": {
        "organizationApiName": “zylker”,
        "name": “Zylker”
      },
      "requesterDepartment": {
        "apiName": “accounts”,
        "name": “Accounts”
      }
    }
  ]
}

Possible Errors

INVALID_URL_PATTERNHTTP 404

Request URL is incorrect

Resolution: Specify a valid request URL. Refer to the Request URL section above.

OAUTH_SCOPE_MISMATCHHTTP 401

Unauthorized

Resolution: Client does not have contracts.contracts.CREATE scope. Create a new client with valid scope. Refer to the Scope section above.

NO_PERMISSIONHTTP 403

Permission denied to create

Resolution: The user does not have permission to create records. Contact your organization administrator.

INTERNAL_ERRORHTTP 500

Internal Server Error

Resolution: Unexpected and unhandled exception in the server.

INVALID_REQUEST_METHODHTTP 400

The HTTP request method is not a valid one.

Resolution: You have specified an invalid HTTP method to access the API URL. Specify a valid request method. Refer to the Endpoints section above.

AUTHORIZATION_FAILEDHTTP 400

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

Resolution: The user does not have permission to create module details. Contact your organization administrator.

Values	Description
0	Represents the contract initiated by your organization.
1	Represents the contract initiated by the counterparty.

Value	Description
1	Represents the original version of the contract, before any renewals or amendments were made.

Value	Description
0	Specific Date
1	On Condition
2	On Event
3	N Months/Years
4	On Fulfillment Of Order/Service

Value	Description
0	All Taxes Included
1	As Per Payment Terms

Value	Description
True	Definite
False	Indefinite

Value	Description
0	Months
1	Years

Value	Description
True	Renewable
False	Non-Renewable

Value	Description
0	Manual Renewal
1	Evergreen Renewal