Attachments Basics

Attachments can exist on a comment (that is, within a discussion), on a row, or on a sheet.

Post an Attachment

Like the Smartsheet app, the Smartsheet API allows uploading files to sheets, rows, and comments. You can upload a file by performing either a simple upload or a multipart upload.

A simple upload allows you to add a single file attachment to the specified object. For example, you can perform a simple upload to attach a file to a sheet, attach a file to a row, or attach a file to a comment.

A multipart upload allows you to add a single file attachment to the specified object (that is, attach a file to a sheet, row, or comment), or to create an object and attach a file using a single request. For example, you can perform a multipart upload to add a new comment that contains a single file attachment or to add a new discussion to a sheet that contains a single file attachment.

The max file size for uploads through the API is limited to 30mb.

NOTE: Posting an attachment is a resource-intensive operation and incurs 10 additional requests against the rate limit.

Multipart Uploads

A multipart upload request must include the following HTTP headers:

Header Description
Content-Length The length of the request payload.
Content-Type Must be set to multipart/form-data, and include the boundary string that separates the parts in the request payload.

The request body of a multipart upload request contains one or more parts, each part containing either JSON or a file to upload. The request body must contain at least one part. Each part must start with the boundary string specified in the Content-Type request header, and must contain the following part headers:

Header Description
Content-Disposition Contains the following semicolon-delimited items:
  • form-data
  • name="partname"
  • filename="filename" (only required for file parts)
NOTE: Values specified in the Content-Disposition header must be URL-encoded.
Content-Type The content type of the part: application/json for JSON objects, or the applicable MIME type for file parts

The last part in the request must be followed by the boundary string, followed by two hyphens.

The documentation for each operation that supports multipart uploads specifies the number and names of parts that are expected for the operation. File parts must have the part name "file", and documentation for operations which allow for JSON object parts specify the required part name for the JSON part.

The following example shows a multipart upload request that creates a comment containing the specified text and file attachment:

POST Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Length: 29008 Content-Type: multipart/form-data; boundary=----gU8h01zAAp3LagBr

------gU8h01zAAp3LagBr Content-Disposition: form-data; name="comment" Content-Type: application/json

{ "text": "Please review the attached image." } ------gU8h01zAAp3LagBr Content-Disposition: form-data; name="file"; filename="picture.jpg" Content-Type: image/jpeg

*< Binary content for file >* ------gU8h01zAAp3LagBr--

NOTE: Most programming languages have libraries that can be used to assemble multipart requests.

Simple Uploads

To perform this kind of upload, you must set specific headers to tell Smartsheet about the file. The following three headers are required:

Header Description
Content-Disposition attachment to tell the API that a file is in the body of the POST request, followed by a semicolon, followed by filename= and the URL-encoded filename in quotes
Content-Length Must be set to the size of the file, in bytes. For example to determine file size using in UNIX:

$ ls -l ProgressReport.docx
5463 ProgressReport.docx

Content-Type Can be left blank if it is not known (but must be present); Smartsheet makes its best guess based on the extension of the file.

The following example request shows a simple upload that adds a file attachment to a sheet:

POST Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Disposition: attachment; filename="ProgressReport.docx" Content-Type: application/msword Content-Length: 5463

*< Binary content for file >*

As shown in this example, the contents of the file is included in the body of the POST request. In most programming languages, this is done by reading the file from an input stream and writing it out to the output stream of the HTTP request.

➔ Next to Objects