Working with attachments in the REST API
This article describes foundational concepts for working with entity attachments in the Autotask REST API.
We recommend reading this article after you have familiarized yourself with the key principles discussed in our Introduction to REST API calls and Making basic query calls to the REST API articles. For advanced query syntax, refer to Advanced query features of the REST API.
To help you learn how to construct requests to the Autotask REST API, Datto provides a customizable REST API request collection for use with Postman. For more information, refer to Sample requests.
Overview
Certain REST API resources support attachments via child entities. Via the REST API, you can query the children of these entities to view their attachments, add new attachments, and delete existing attachments. For a list of API resources that currently support attachments, refer to the Before you begin section of this article.
IMPORTANT Attachment behavior in the API has changed. To avoid service disruption, review our Changes to Attachment entities article for important information about this recent update.
BEFORE YOU BEGIN Examples in this article may use the webservices[n].autotask.net placeholder. In such instances, substitute [n] for the zone of your user, as described in Autotask API zones and WSDL versions > Find your zone's API URL for the REST API or Autotask API zones and WSDL versions > Find your zone's WSDL file URL for SOAP API version 1.6.
Index
- Before you begin
- The AttachmentInfo entity
- The FileQueryResultModel
- Querying a resource's attachments
- Making a standard attachment creation call
- Making an attachment creation call with impersonation
- Making an attachment deletion call
- Updating an existing attachment
- Additional resources
Before you begin
There are several key concepts to keep in mind when working with attachments.
When adding an attachment to an entity via the API, the attachment must be encoded as base64 binary data.
To ensure a consistent quality of service for all users, the API uses the following thresholds when processing attachments.
- The maximum attachment file size indicated in the Autotask Online Help does not apply to the API. The API size limit for individual attachment files is 6 to 7 MB, with a maximum of 10,000,000 bytes within a five-minute period. If your integration exceeds either of these limits, you'll receive an error message indicating condition. If the integration exceeds 10,000,000 bytes within a five-minute span, the API will also stop accepting attachment creation calls for five minutes.
NOTE The API size limit for individual attachments is less than the 10 MB limit for individual attachment files when working through the Autotask UI.
- Attachment types are limited to the file types allowed in Autotask. For more details, refer to Add attachments.
Attachments are external documents that are associated with one of the following entities. Attachments in Autotask can be documents uploaded to the server, file links, folder links, and URLs.
- Account
- Documents (REST only)
- Expenses
- Knowledgebase articles (REST only)
- Task
- Ticket
- Task or Ticket Note
- Time Entry
- Asset
- Asset Note
- Project
- Opportunity
The following parent entities support nested attachments. Nested attachments are a child attachment to a parent attachment, and both the parent and the child can be of the same entity type.
- Articles
- Companies
- Configuration Items
- Documents
- Opportunities
- Tasks
- Tickets
NOTE Attachments nested under note or time entry attachments are created via the parent entity URL using the parentAttachmentId. The nested attachment does not have visibility to the note or time entry, but it will reflect that the parent is an attachment with the supplied ID.
The following parent entities do not support nested attachments. For these parents, you cannot create attachments that have a parent attachment of the same type.
- Account
- Sales Order
- Expense Report
- Resource
- Account Note
- Contract Note
- Project
- Project Note
Attachments support create, delete, and query functions only. It is not possible to update an attachment.
The AttachmentInfo entity describes an attachment in Autotask. This entity is unique. You can only query it. To create or delete attachments, you must use the child collection URL for each attachment type. You can also query by using a child collection URL.
To view the attachments associated with an API resource, query this entity as a component of the call to the parent entity. To view nested attachments, query the AttachmentsNestedAttachments entity. For further information, refer to AttachmentInfo (REST API) and Querying a resource's attachments.
When querying certain attachment endpoints, the API may return the information as a FileQueryResultModel object. It contains the following fields.
-
id: The attachment's identifier, such as an invoice ID
-
contentType: The file type, such as "application/pdf"
-
fileName: The name of the file
-
fileSize: The size of the file
-
data: The file contents as a byte array
To query all the names and descriptions of attachments associated with a resource, use a GET call to the AttachmentInfo (REST API) entity along with an ID filter specifying the resource you'd like to query. Refer to Querying all attachments of a resource by parent ID for more information.
To retrieve the data of an attachment associated with a specific resource, use a GET call to the AttachmentInfo (REST API) entity along with the ID of the resource. Refer to Querying attachment data for a specific resource to learn more.
To retrieve the actual attachment of a resource, you must provide one of the following identifiers.
-
The Attachment ID of the Attachments child endpoint; or
-
The appropriate <EntityName>Attachments endpoint (such as TicketAttachments, ResourceAttachments, and so forth)
Refer to Retrieving an attachment of a resource for additional details.
NOTE If your query supplies both an entityID and a parentID, the entityID will take precedence.
Querying all attachments of a resource by parent ID
This example uses a filter to query all attachments associated with a resource that has a parent ID of 175.
GET URL:
https://webservices[n].autotask.net/atservicesrest/v1.0/AttachmentInfo/query?search={"filter":[{"op":"eq","field":"ParentID","value":175}]}
Response:
{
"item": {
"id": 75,
"attachDate": "2020-10-02T13:57:23.587",
"attachedByContactID": 30682918,
"attachedByResourceID": 30682918,
"attachmentType": "FILE_ATTACHMENT",
"contentType": "image/jpeg",
"creatorType": 2,
"fileSize": 4938505.0,
"fullPath": "PondOct28.JPG",
"impersonatorCreatorResourceID": null,
"opportunityID": null,
"parentID": 175,
"parentType": 4,
"publish": 1,
"title": "Pond"
}
}
Querying attachment data for a specific resource
The following example queries the resource with a parent ID of 90 and returns its attachment data.
GET URL:
https://webservices[n].autotask.net/atservicesrest/v1.0/AttachmentInfo/90
Response:
{
"item": {
"id": 90,
"articleID": null,
"attachDate": "2020-10-02T13:57:23.587Z",
"attachedByContactID": 30682918,
"attachedByResourceID": 30682918,
"attachmentType": "FILE_ATTACHMENT",
"companyID": null,
"companyNoteID": null,
"configurationItemID": null,
"configurationItemNoteID": null,
"contentType": "image/jpeg",
"contractID": null,
"contractNoteID": null,
"creatorType": 2,
"documentID": null,
"expenseItemID": null,
"expenseReportID": null,
"fileSize": 4938505.0,
"fullPath": "PondOct28.JPG",
"impersonatorCreatorResourceID": null,
"opportunityID": null,
"parentAttachmentID": null,
"parentID": 7848,
"parentType": 4,
"projectID": null,
"projectNoteID": null,
"publish": 1,
"resourceID": null,
"salesOrderID": null,
"taskID": null,
"taskNoteID": null,
"ticketID": 7848,
"ticketNoteID": null,
"timeEntryID": null,
"title": "Pond"
}
Retrieving an attachment of a resource
To view detailed information about an attachment, such as its contents, your request must observe the following hierarchy:
Entity name → entity ID → Attachments → attachment ID
For example, to query ticket ID 7848 for the details about attachment ID 90, you would structure your API request as follows:
GET URL:
https://webservices[n].autotask.net/atservicesrest/v1.0/Tickets/7484/Attachments/90
Response:
{
"items": [
{
"id": 90,
"attachDate": "2020-12-10T18:15:49.827",
"attachedByContactID": null,
"attachedByResourceID": 29682894,
"attachmentType": "FILE_ATTACHMENT",
"contentType": "text/plain",
"creatorType": 1,
"fileSize": 35.0,
"fullPath": "TestText.txt",
"impersonatorCreatorResourceID": null,
"opportunityID": null,
"parentAttachmentID": null,
"parentID": 7484,
"publish": 1,
"ticketID": 7484,
"ticketNoteID": null,
"timeEntryID": null,
"title": "Test text to a ticket",
"data": "VGVzdCB0ZXh0IGZpbGUgdG8gYXR0YWNoLg0KTGluZSAyDQo="
}
],
"pageDetails": {
"count": 1,
"requestCount": 1,
"prevPageUrl": null,
"nextPageUrl": null
}
}
A standard attachment creation call with POST attributes the file attachment's author to "API User."
If you need to define a specific author instead, use an attachment creation call with contact or resource impersonation. Refer to the Making an attachment creation call with impersonation of this article for more information.
Syntax example
The following example attaches a file called TestText.txt to a resource with the ID of 90 that contains the phrase "Test text to a ticket." The file is base64 encoded in the data field.
POST URL:
https://webservices[n].autotask.net/atservicesrest/v1.0/Tickets/90/Attachments
Body:
{
"id": 0,
"attachDate": "2020-10-05T10:59:57.537",
"attachedByContactID": null,
"attachedByResourceID": null,
"attachmentType": "FILE_ATTACHMENT",
"fullPath": "TestText.txt",
"publish": 1,
"title": "Test text to a ticket",
"data": "VGVzdCB0ZXh0IGZpbGUgdG8gYXR0YWNoLg0KTGluZSAyDQo="
}
200 response:
{
"itemId": 83
}
Attachment creation calls that use POST with contact or resource impersonation enable the API to generate content with a specified author designated as the object's creator.
NOTE To create attachments on the behalf of another user, the API user account must meet the requirements described in the Contact impersonation validation rules for creating entities section of this topic. Additionally, you must have first configured impersonation as described in Impersonating resources and contacts.
To learn how to create an attachment without using impersonation, refer to the Making a standard attachment creation call section of this article.
Contact impersonation validation rules for creating entities
- The API user security level has access to contact impersonation for attachments.
- Publish must always be ALL.
- Contacts can only create attachments for Tickets or Project/Task/Ticket Notes that they have created.
- The contact is active.
- The contact's account is active.
Syntax example - attachment with contact impersonation
The following example attaches a file called TestText.txt to a ticket resource with the ID of 90 that contains the phrase "Test text to a ticket." The file is base64 encoded in the data field.
IMPORTANT For contact impersonation to be successful, you must send the ID of the contact you want to impersonate as an attachedByContactID field value. In this example, the attributed contact is the user with the ID of 30682903.
POST URL:
https://webservices[n].autotask.net/atservicesrest/v1.0/Tickets/90/Attachments
Body:
{
"id": 0,
"attachDate": "2020-10-05T10:59:57.537",
"attachedByContactID": 30682903,
"attachedByResourceID": null,
"attachmentType": "FILE_ATTACHMENT",
"fullPath": "TestText.txt",
"publish": 1,
"title": "Test text to a ticket",
"data": "VGVzdCB0ZXh0IGZpbGUgdG8gYXR0YWNoLg0KTGluZSAyDQo="
}
200 response:
{
"itemId": 84
}
Syntax example - attachment with resource impersonation
The following example attaches a file called TestText.txt to a ticket resource with the ID of 90 that contains the phrase "Test text to a ticket." The file is base64 encoded in the data field. The header of the request must contain the ImpersonationResourceID value
NOTE In the header of the request, we've specified an ImpersonationResourceId value of 29682885. Doing so will result in the author of this attachment being attributed to the resource with the corresponding identifier.
POST URL:
https://webservices[n].autotask.net/atservicesrest/v1.0/Tickets/90/Attachments
Body:
{
"id": 0,
"attachDate": "2020-10-05T10:59:57.537",
"attachedByContactID": null,
"attachedByResourceID": null,
"attachmentType": "FILE_ATTACHMENT",
"fullPath": "TestText.txt",
"publish": 1,
"title": "Test text to a ticket",
"data": "VGVzdCB0ZXh0IGZpbGUgdG8gYXR0YWNoLg0KTGluZSAyDQo="
}
200 response:
{
"itemId": 85
}
To delete an attachment, you'll need to send a DELETE call to the ID of the ticket resource from which you would like to remove the attachment, and you'll also need to specify the attachment's ID.
The following example deletes an attachment from the resource with the ID of 90. The attachment has an ID of 91.
POST URL:
https://webservices[n].autotask.net/atservicesrest/v1.0/Tickets/90/Attachments/91
200 response:
{
"itemId": 91
}
It is not possible to directly update an attachment. To replace an existing attachment with a newer version of the file, delete the existing attachment and then use the attachment creation call to upload the new file.