BoldDesk List Tickets API: Filtering Guide
The BoldDesk List Tickets API provides flexible filtering options to help teams retrieve tickets with precision. This guide explains:
- Available API parameters
- How to filter by created date ranges
- How to work with custom field filters using BoldDesk ticket views
1. Overview of List Tickets API Parameters
The BoldDesk List Tickets API supports multiple filter parameters designed to refine and optimize ticket retrieval.
Available Filtering Parameters
| Parameter | Purpose |
|---|---|
| Q | Allows advanced query-based filtering. |
| FilterId | Retrieves tickets based on saved ticket views configured in the BoldDesk portal. |
| Fields | Specifies which fields should be returned in the API response. |
| BrandIds | Filters tickets by one or more brands. |
For detailed parameter reference, visit: List Tickets API page in the BoldDesk Developer Portal.
2. Filtering by Created Date (Last 10 Days or Custom Range)
Although BoldDesk provides date shortcuts inside the UI (such as Last 10 Days), shortcuts are not supported directly within the API.
To fetch tickets created in a specific time window, you must define a UTC-based date range using the Q parameter.
Syntax
createdon: {
"from": "yyyy-mm-ddThh:mm:00.000Z",
"to": "yyyy-mm-ddThh:mm:00.000Z"
}
Replace the from and to values with the required start and end date/time in UTC format.
Example Request URL
/api/v1/tickets?Q=createdon%3A%20%7B%22from%22%3A%20%222025-08-05T18%3A30%3A00.000Z%22%2C%20%22to%22%3A%20%222025-08-15T18%3A29%3A59.000Z%22%20%7D%20
3. Filtering Tickets by Custom Fields
The List Tickets API does not yet support direct filtering of custom fields (e.g., cf_reason:false).
Recommended BoldDesk Workaround: Filter Using Ticket Views
You can achieve custom field filtering by using ticket views created in the BoldDesk portal.
-
Go to the BoldDesk portal.
-
Create a ticket view with the desired filters (e.g., created date range + custom field conditions).
-
Copy the FilterId of the created view.
-
Use the FilterId in the API request.
Example Request URL
/api/v1/tickets?FilterId=1038
This returns all tickets that match the conditions of the configured ticket view.
FAQs
1. Can I combine Q and FilterId in the same API request?
No. When a FilterId is applied, the API uses the logic configured in the ticket view. To maintain consistency, additional Q‑based filters are not used simultaneously.
2. How can I obtain the FilterId for a ticket view?
Open the desired ticket view in the BoldDesk Agent Portal, then copy the FilterId from the view’s URL or view details panel.
3. Can I filter tickets by agent, group, or SLA through the Q parameter?
Yes. The Q parameter supports filtering by built‑in ticket fields including assigned agents, groups, and SLA states.
4. Does the BoldDesk API support timezone conversions?
The List Tickets API requires all datetime filters to be passed in UTC format. Any timezone conversion should be handled before sending the request.
5. Can I retrieve only specific fields (e.g., subject, status, requester)?
Yes. Use the Fields parameter to minimize payload size and improve performance, especially when retrieving large datasets.
