Attach File

Purpose

To attach a file to your contract at any stage. Attaching a file to your contract involves two steps:

Uploading the file using the Upload API.
Providing the uploaded file references and contract details using the Attachments API.

Note:

If multiple files are required for the import, each file must be uploaded individually. After each upload, retrieve the corresponding ID and include all relevant IDs when calling the Attachments API.
You can add any number of attachments to a contract, but their combined size must not exceed 100 MB.
If your subscription downgrades to the Free plan, you will only be able to view files and links that were attached during the paid plan, but you will not be able to modify them.
Supported file formats:

File Category	File Formats
Document	PDF: pdf MS Word: docx, doc, doct, dot MS Excel: xlsx, xls, xlt MS PowerPoint: pptx, ppt, pot, potx OpenDocument: odt, ods, odp Rich Text: rtf Plain Text: txt, csv, tsv
Image	jpg, jpeg, png, apng, svg, gif, tiff, ico, bmp, webp, psd, eps, ai, cdr
Video	mp4, mov, wmv, avi, webm, mpeg
Audio	wav, mp3, wma, aiff, aac, flac, alac, m4a
CAD	dwg, blend, model, x_t, jt, qif, sat, ipt, ham, step, stp, igs, iges, stl
Scientific Documents	tex

Endpoints

POST /upload

POST /attachments

Request Details

1. Request URL: First API Call

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

Note:

The request must be sent with "multipart/form-data" as the Content-Type to support file uploads.

Sample Request: First API Call

Copiedcurl "https://contracts.zoho.com/api/v1/contracts/msa-with-zenith-dynamics/upload"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"
-H  "Content-Type: multipart/form-data"
-F  "content=@file"
-F  "module=attachment"

Response to the First API Call

Copied[
    {   
        "path": "A8aP0on9J6gN",
        "fileName": "contract-attachment.pdf",
        "size": 681082,
        "uploads": "9aa9c78837974a04951cd304d15d294e"
    }
]

2. Request URL: Second API Call

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

Authorization

Authorization: Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6

Scope

contracts.contracts.CREATE, contracts.contracts.ALL

Possible Operation Types

ALL - Full access to contract information
CREATE - Attach a file to a contract

Sample Request: Second API Call

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

Input JSON Keys

contractattachmentsJSON Array
Represents the list of files attached to the contract.
sequenceNumberinteger
Represents the order in which the attachment was added.
uploadsJSON Object
Represents the ID returned by the Upload API.
attachmentTypeinteger
Represents the type of attachment.
Values Description
1 File
2 Link

Sample Input: Second API Call

Copied{
"contractAttachments": [
    {
      "sequenceNumber": 1,
      "uploads": "9aa9c78837974a04951cd304d15d294e",
      "attachmentType": 1
    }
	]
}

Response JSON Keys

contractattachmentsJSON Array
Represents the list of files attached to the contract.
contractAttachmentIdstring
Represents the unique ID of the attachment.
attachmentIdstring
Represents the unique ID of the attached file, applicable only for the "File" attachment type.
sequenceNumberinteger
Represents the order in which the attachment was added.
attachmentTypeinteger
Represents the type of attachment.
Value Description
1 File
2 Link
statusinteger
Represents the status of the attachment.
Value Description
0 Deleted
1 Active
addedByJSON Object
Represents the details of the user who added the attachment.
idnumber
Represents the unique ID of the user.
displayNamestring
Represents the display name of the user.
emailIdstring
Represents the email address of the user.
modifiedByJSON Object
Represents the details of the user who last modified the attachment.
addedTimestring
Represents the date and time when the file was added in the full format (DD MMM YYYY, h:mm a).
addedTimeExtstring
Represents the date and time when the file was added in the medium format (DD-MMM-YYYY).
addedTimeFullstring
Represents the date and time when the file was added in the long format (EEEE, D MMMM, YYYY h:mm a).
modifiedTimestring
Represents the date and time when the file was modified in the full format (DD MMM YYYY, h:mm a).
modifiedTimeExtstring
Represents the date and time when the file was modified in the medium format (DD-MMM-YYYY).
fileJSON Object
Represents the details of the attached file (such as File Name, Type, Size).
FileIdinteger
Represents the unique ID of the file.
fileVersionIdinteger
Represents the unique ID of the file version.
namestring
Represents the name of the file.
Extensionstring
Represents the file type(e.g, "pdf”).
sizeinteger
Represents the size of the file in bytes.
previewURLstring
Represents the URL to preview the file within the application.
viewURLstring
Represents the URL to directly view the file.

Response to the Second API Call

Copied{
  "contractattachments": [
    {
      "contractAttachmentId": "1234567890001",
      "attachmentId": "1234567890002",
      "sequenceNumber": 1,
      "attachmentType": 1,
      "status": 1,
      "addedBy": {
        "id": "987654321001",
        "displayName": "John Smith",
        "emailId": "john.smith@zylker.com"
      },
      "addedTime": "20 Sep 2025, 10:30 AM",
      "addedTimeExt": "20-Sep-2025",
      "addedTimeFull": "Saturday, 20 September, 2025 10:30 AM",
      "modifiedBy": {
        "id": "987654321001",
        "displayName": "John Smith",
        "emailId": "john.smith@zylker.com"
      },
      "modifiedTime": "20 Sep 2025, 10:30 AM",
      "modifiedTimeExt": "20-Sep-2025",
      "file": {
        "FileId": 1234567890003,
        "fileVersionId": 1234567890004,
        "name": "Service_Agreement_2025.pdf",
        "Extension": "pdf",
        "size": 245678,
        "Status": 1,
        "previewURL": "https://contracts.zylker.com/preview/contracts/attachments/1234567890002",
        "viewURL": "https://contracts.zylker.com/view/contracts/attachments/1234567890004"
      },
      "source": 1
    }
  ]

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.

AUTHORIZATION_FAILEDHTTP 2131

Duplicate values not allowed

Resolution: Remove the duplicate values from the sequence number.

Values	Description
1	File
2	Link

Value	Description
1	File
2	Link

Value	Description
0	Deleted
1	Active