Working with attachments in the REST API

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

1. The API user security level has access to contact impersonation for attachments.
2. Publish must always be ALL.
3. Contacts can only create attachments for Tickets or Project/Task/Ticket Notes that they have created.
4. The contact is active.
5. 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.