Need to attach images or files when creating tickets or posting ticket updates through the BoldDesk API? This article explains how to upload a file, generate an attachment token, and use that token to associate the file with a new ticket or an existing ticket update.

After uploading a file, include the generated attachment token in the attachments field to ensure the file is linked to the ticket and displayed within the ticket conversation.

In this article, you’ll learn how to:

• Generate an attachment token.
• Create a ticket with an attachment.
• Add an attachment to a ticket update.
• Associate uploaded files using the attachments field.
• Troubleshoot common attachment-related issues.

Prerequisites

Before you begin, ensure you have:

• A valid BoldDesk API key.
• Your BoldDesk domain name.
• The ticket ID (when adding attachments to an existing ticket).
• The file you want to upload.

For more information, see:

• Generate and Manage API Keys in BoldDesk
• BoldDesk API Authentication Guide

Step 1: Generate an Attachment Token

Upload the file using the Attachments API. The API returns an attachment token that can later be used when creating a ticket or posting a ticket update.

Endpoint

POST https://{yourdomain}.bolddesk.com/api/v1/attachments

cURL Example

curl --request POST \
  'https://{yourdomain}.bolddesk.com/api/v1/attachments' \
  --header 'x-api-key: {API_KEY}' \
  --form 'file=@"/path/to/image.png"'

Sample Response

{
  "success": true,
  "result": {
    "attachmentToken": "generated_attachment_token"
  }
}

Copy the returned attachmentToken. You’ll use it in subsequent API requests to associate the uploaded file with a ticket or ticket update.

Step 2: Create a Ticket with an Attachment

Include the generated attachment token in the attachments field when creating the ticket.

Endpoint

POST https://{yourdomain}.bolddesk.com/api/v1/tickets

Sample Payload

{
  "brandId": 1,
  "requesterId": 1053,
  "subject": "Unable to access customer portal",
  "description": "<p>The customer is unable to log in to the portal.</p>",
  "priorityId": 2,
  "statusId": 1,
  "isVisibleInCustomerPortal": true,
  "attachments": "{generated_attachment_token}"
}

cURL Example

curl --request POST \
  'https://{yourdomain}.bolddesk.com/api/v1/tickets' \
  --header 'x-api-key: {API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "brandId": 1,
    "requesterId": 1053,
    "subject": "Unable to access customer portal",
    "description": "<p>The customer is unable to log in to the portal.</p>",
    "priorityId": 2,
    "statusId": 1,
    "isVisibleInCustomerPortal": true,
    "attachments": "{generated_attachment_token}"
  }'

Result

After the request is processed successfully:

• The ticket is created.
• The uploaded file is associated with the ticket.
• The attachment appears in the ticket conversation.
• Agents and authorised customers can access the file.

Add an Attachment to a Ticket Update

You can also use the attachment token when posting updates to an existing ticket.

Endpoint

POST https://{yourdomain}.bolddesk.com/api/v1/tickets/{ticketID}/updates

Sample Payload

{
  "description": "<p>See attached screenshot.</p>",
  "attachments": "{generated_attachment_token}",
  "isBillable": true
}

cURL Example

curl --request POST \
  'https://{yourdomain}.bolddesk.com/api/v1/tickets/{ticketID}/updates' \
  --header 'x-api-key: {API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "description": "<p>See attached screenshot.</p>",
    "attachments": "{generated_attachment_token}",
    "isBillable": true
  }'

Result

After the update is posted:

• The ticket update is created successfully.
• The uploaded file is linked to the update.
• The attachment appears in the ticket conversation.

Understanding the attachments Field

The attachments field accepts the attachment token returned by the Attachments API.

{
  "attachments": "{generated_attachment_token}"
}

When the token is included:

• The uploaded file is associated with the ticket or ticket update.
• The file becomes visible within the conversation.
• Authorized users can access the attachment.

When the token is omitted:

• The ticket or update is still created successfully.
• The uploaded file is not associated with the ticket.
• No attachment appears in the conversation.

Common Use Cases

Attach a Screenshot

{
  "description": "<p>Please review the attached screenshot.</p>",
  "attachments": "{generated_attachment_token}",
  "isBillable": false
}

Provide a Resolution Update

{
  "description": "<p>The issue has been resolved. See the attached image for verification.</p>",
  "attachments": "{generated_attachment_token}",
  "isBillable": true
}

Add an Internal Investigation Note

{
  "description": "<p>Internal investigation screenshot attached.</p>",
  "attachments": "{generated_attachment_token}",
  "isBillable": false
}

Replace {generated_attachment_token} with the attachment token returned by the upload request.

Troubleshooting

Attachment Does Not Appear in the Ticket

Cause: The attachment token was not included in the request.

Resolution: Ensure the token returned by the Attachments API is included in the attachments field.

Invalid Attachment Token

Cause: The token is invalid, incomplete, or no longer valid.

Resolution: Upload the file again and use the newly generated attachment token.

401 Unauthorized

Cause: Missing, invalid, or inactive API key.

Resolution:

• Verify the request includes the x-api-key header.
• Confirm the API key is active.
• Verify the request is sent to the correct BoldDesk domain.

404 Ticket Not Found

Cause: The specified ticket does not exist or is inaccessible.

Resolution: Verify the ticket ID and ensure the authenticated user has permission to access it.

File Upload Fails

Cause: Unsupported file type, malformed request, or corrupted file.

Resolution:

• Verify the file type is supported.
• Ensure the request uses multipart/form-data.
• Confirm the file is not corrupted.
• Retry the upload with a valid file.

Attachment Appears on the Wrong Ticket

Cause: An incorrect ticket ID was used.
Resolution: Verify the ticket ID before posting the update.

Frequently Asked Questions

1. Can I create a ticket with an attachment using the API?
Yes. Upload the file using the Attachments API and include the returned attachment token in the attachments field when creating the ticket.

2. Can I upload a file directly through the ticket creation API?
No. Files must be uploaded first through the Attachments API.

3. What is an attachment token?
An attachment token is a unique value generated after a successful file upload. It links the uploaded file to a ticket or ticket update.

4. Where should I include the attachment token?
Include it in the attachments field of the ticket creation or ticket update request.

5. What happens if I omit the attachments field?
The ticket or update is created successfully, but the uploaded file is not associated with the ticket.

6. Does the description field support HTML?
Yes. HTML formatting such as <p> tags is supported.

7. Can I upload multiple attachments?
Yes. Upload each file separately and include the corresponding attachment tokens using the supported payload format.

Related Articles

1. How to Create a Ticket with an Attachment via API in Power Automate
2. BoldDesk REST API Overview for Developers
3. BoldDesk API Authentication Guide: Secure Access Made Simple
4. Generate and Manage API Keys in BoldDesk
5. BoldDesk API Documentation