Attachments

On this page

Attachments have their own routes on an object. Upload content as a base64 string in a JSON body. A multipart/* upload is rejected with 415 Unsupported Media Type and a message directing you to JSON. The download route returns the file's raw bytes.

In the API

List an object's attachments

GET or POST /Object/{objectId}/Attachments lists the object's attachment records, without their content. The call first resolves the parent object and checks your view rights on it. What the API answers when the object is missing or you may not view it is described in Objects and Fields.

The list answers with a Fields / Data pair rather than an array of objects: each Fields entry carries a column's Name, DataType, and Caption, and you read the values of each Data row by position.

The list uses the same GET query parameters and POST body members as a class list, including field names, filters, sorting, paging, search text, and view name. See List objects for the syntax, case sensitivity, and encoding rules.

Without a requested sort, attachments are sorted by File_Name. Omitting the limit returns all attachments you may view; a limit of 0 or less disables paging and ignores the offset.

The attachment's id is returned as ID; a filter, sort, or field named ID refers to the attachment's id. Without a requested field list, the list returns ID and those other columns of the attachment list view that the product's field list registers and field customization does not exclude. The list has no Data or Object_ID column. The view defines File_Name, File_Size, Created_by, Created_by_ID, Created_Date, Modified_by, Modified_by_ID, Modified_Date, Description, Is_File, Type, File_Type, Activity_Num, and Link_Count. Type is Link when Is_File is 0, which is how a link is stored, and File otherwise.

Read one attachment

GET /Object/{objectId}/Attachments/{attachmentId} returns the attachment's record in the same shape as reading an object: an Items array of entries with the keys name, caption, and value, in lower case in JSON. An XML response wraps the list as <Items> of <Item> elements. The record shape is described in Objects and Fields.

GET /Object/{objectId}/Attachments/{attachmentId}/content returns the content as a base64 string in the envelope, as Data together with FileName, Description, and Size. This response does not carry IsLink, AttachmentArea, or GroupID, so it does not tell whether the attachment was written as a link or into a named area. The attachment list reports a link with Type Link.

GET /Object/{objectId}/Attachments/{attachmentId}/download returns the raw bytes as a file response, not the JSON envelope. The response carries the attachment's size, a MIME type guessed from the file name, a standard Content-Disposition: attachment header, and an attachment-file-name header holding the URL-escaped file name. The second header exists because browsers and clients disagree about non-ASCII names in the standard header.

Add an attachment

PUT /Object/{objectId}/Attachments adds one attachment object, or an array of them. Any other JSON value, or an empty array, fails as an invalid body. Every entry is validated against the rules below, and each entry carries these members:

Member Meaning
FileName Required. The file name, or the URL for a link.
Data The base64 content.
IsLink true for a link.
Description The attachment's description.
Size The size.
AttachmentArea For an attachment sent with a workflow action, the attachment area, by name.
GroupID For an attachment sent with a workflow action, the attachment area, by id.

An entry is either data or a link, never both. To attach a link, send IsLink: true with the URL in FileName and no Data; supplying Data together with IsLink is rejected as an invalid combination, naming the file. A link is stored as a non-file attachment with no file size and is reported with Type Link in the attachment list.

The maximum attachment size is a database setting, not a web-server one. GET /V1/SystemSettings answers with an object whose one member is the integer AttachmentMaxSizeMB: the maximum in megabytes, or 0 when the attachment limit is switched off. This is the number to check before uploading.

The request body limit of the API is separate and larger: 50 MB as shipped. Because attachment content is base64-encoded, the usable file size is roughly three quarters of that. The API's Web.config sets this limit in two places that must agree: httpRuntime maxRequestLength, shipped as 51200 KB, and the IIS request-filtering maxAllowedContentLength, shipped as 52428800 bytes. A request whose Content-Length is above 100 KB and above maxRequestLength is rejected with 413 Request Entity Too Large, quoting both sizes.

A successful PUT answers with a null responseObject.

Change or remove an attachment

PATCH /Object/{objectId}/Attachments/{attachmentId} changes the attachment's description and nothing else: it accepts a whole attachment object but reads only Description.

DELETE /Object/{objectId}/Attachments/{attachmentId} removes the attachment.

Both calls, like PUT, answer with a null responseObject.

Adding, changing, and removing an attachment each check, in this order, that you may view the object, that you may edit it, and that the object is not at its class's inactive status. An object at the inactive status is refused with a message naming the class and the status.

Attachments through workflow actions

An action's request body may carry a reserved Attachments array. When you run a task action with POST /Object/{objectId}/Action/{actionId}, the array sits beside the flat field values; when you run a create action with POST /, it sits beside ActionId and the Fields map. In a task action's flat body, it is the one exception to the rule that a value is a string, integer, float, boolean, or null. How the rest of an action's body is built is covered in Create Records and Run Actions.

An attachment sent with an action must land in an attachment area of the action's form. You select the area by id (GroupID) or by name (AttachmentArea). With neither, the attachment goes to the form's attachment area if the form has exactly one. An action whose form has no attachment area rejects the attachment, and so does a form with several areas when the attachment names none.

A link is sent in an action's Attachments array the same way as on PUT: IsLink: true, the URL in FileName, and no Data. It goes through the same attachment-area selection as a file, so AttachmentArea or GroupID applies to it the same way. An entry that supplies Data together with IsLink is rejected here too, and the link is stored as a non-file attachment with no file size and no content.

A global workflow function, run with POST /function/{functionId}, takes attachments differently: every array-valued member of its body becomes attachments, and the member's name replaces each entry's GroupID. An attachment-typed parameter of a function can be supplied only this way. How a function call is built is covered in Global Workflow Functions.