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.
Related topics
- Create Records and Run Actions - creating records and running workflow actions.
- List and Read Objects