Uploading Attachments (Ticket API)

Helpdocs Admin Updated by Helpdocs Admin

Attaching files to tickets, comments, or time entries is a two-step process: create an upload session, then verify the upload once it's complete. This design lets users upload files ahead of time in the UI, so the actual ticket/comment/time entry can be created almost instantly — with no wait for a large file to finish uploading at the same moment.

Step 1: Create an upload session

// POST /api/v4/features/files/$session
{
  "fileName": "string",
  "fileSize": 0,
  "purpose": "ticket"
}

This returns a short-lived link with a SAS (Shared Access Signature) token, giving you temporary access to upload a single file directly to Azure Blob Storage:

{
  "entityId": "string",
  "name": "string",
  "url": "string",
  "sharedAccessSecurity": "string",
  "expiresIn": 0,
  "expiresOn": 0,
  "expiresAt": "2026-09-11T09:40:08.115Z"
}

Upload your file directly to the returned url. Each session link is valid for a single file and expires quickly, so upload promptly after creating the session.

Note: You can technically provide any fileSize when creating the session — it isn't verified at this point. The actual file size is checked and recorded during the verify step below.

Step 2: Verify the upload

Once the file has finished uploading to the blob URL, call:

POST /api/v4/features/files/{fileId}/$verify

Use the entityId returned from the session step as the fileId. On success, the system confirms the file exists in blob storage and populates its actual metadata:

{
  "entityId": "string",
  "name": "string",
  "purpose": "string",
  "meta": {
    "contentType": "string",
    "eTag": "string",
    "fileSize": 0
  }
}

Step 3: Attach the file to a ticket, comment, or time entry

Once verified, reference the file's entityId in the attachments property when creating a ticket, comment, or time entry:

{
  "name": "ticket title",
  "description": { "content": "description", "contentType": "markdown" },
  "attachments": [{ "entityId": "id", "name": "file.txt" }]
}
Limits

  • Up to 10 attachments per ticket, comment, or time entry.
  • Max file size per attachment:
    • 15 MB on Essential licenses
    • 100 MB on Platinum licenses

Important: file ownership and context

Every uploaded file is tied to the identity of whoever uploaded it. When you later attach that file to a ticket, comment, or time entry, the system checks whether the file was uploaded by that same identity.

This matters most when using on behalf of access:

  • If you're creating a ticket on behalf of an agent, you must also upload the file using the file API on behalf of that same agent — not on behalf of your own integration identity.
  • Mismatched identities between the upload and the entity creation will cause the attachment to fail.

Files can't be added after creation

Once a ticket, comment, or time entry has been created, you cannot upload additional files to it afterward. You can only remove existing attachments from the created entity — not add new ones. If you need to attach more files, upload and verify them before creating the ticket, comment, or time entry.

How did we do?

The Prefer Header — Overview

Contact