This article explains how to use the List Tickets API query parameter Q to filter tickets by the supported field, for example, externalreferenceids. Use this when you need to retrieve tickets that were mapped to one or more external system reference IDs.

Prerequisites

• Access to the BoldDesk API (valid API key / token).
• Permission to view tickets in the target workspace/brand.
• The external reference IDs must already be stored on the ticket as externalreferenceids.

Using the Q Parameter for Advanced List Tickets API Filtering

• The List Tickets API supports advanced filtering using the Q parameter.
• For fields that support list/array matching (such as externalreferenceids), provide the value as an array of strings.
• When multiple IDs are provided, the IDs must be separated by commas inside the array.

Filter Tickets by External Reference ID(s) Using the Q Parameter

To filter tickets by external reference ID(s) using the Q parameter, do the following:

1. Open your API client (browser, Postman, curl, or code).
2. Call the List Tickets API endpoint and pass a Q filter using externalreferenceids.
3. Provide the external reference ID(s) inside double quotes.

Example (single external reference ID)

https://rocketer.bolddesk.com/api/v1/tickets?Q=externalreferenceids:["874b6812-f325-11ed-8f2d-06b62cc1a326"]

Example (multiple external reference IDs)

https://rocketer.bolddesk.com/api/v1/tickets?Q=externalreferenceids:["1234-2345-45678","126-345"]

Rules, Conditions, and Behavior

• externalreferenceids values must be passed:
  • As an array: [...]
  • With each ID wrapped in double quotes: "id-value"
  • With multiple IDs separated by commas.
• The Q parameter is used for advanced query-based filtering in the List Tickets API.

Supported fields in the query parameter

Provides Q parameter for filtering the ticket module by specified fields (Values allowed are brands, agents, groups, status, priority, categories, requester, createdby, createdon, lastmodifiedon, closedon, responsedue, resolutiondue, source, tags, type, contactgroups, ids, subject, statuscategory, externalreferenceids, requesteremail, requesterphone, agentemail)

How to Combine Filters Using Multiple Q Parameters

You can apply multiple Q-based filters in one request by repeating the Q parameter in the query string (for example, ...&Q=<filter1>&Q=<filter2>). When multiple Q parameters are provided, they act as cumulative filters (equivalent to an AND across the Q clauses).

Example (multiple Q parameters in one request):
/api/v1/tickets?Q=<createdon filter>&Q=<source filter>&RequiresCounts=true

If you use FilterId, do not combine it with Q in the same request—FilterId uses the saved ticket view logic instead.

Use Cases

• Retrieve a ticket created from an external system by searching with that system’s unique reference ID.
• Retrieve tickets linked to any of several external IDs when reconciling data across systems.

Troubleshooting Common Errors

1. No tickets returned

   • Confirm the field ID exists on at least one ticket.
   • Verify the ID value matches exactly (including hyphens/case).

2. Invalid query / bad request
   Ensure the Q value uses the correct bracket and quote format:

   • Correct: externalreferenceids:["id1","id2"]
   • Incorrect: externalreferenceids:[id1,id2]

Frequently Asked Questions

1. Can I use FilterId and Q together in the same List Tickets API request?
   No. Do not combine FilterId and Q in the same request. Use FilterId for saved ticket view filtering and use Q for query-based filtering.

2. Which Q field should I use to find tickets linked to external systems?
   Use externalreferenceids when you need to retrieve tickets mapped to one or more external system reference IDs.

3. How can I confirm that the externalreferenceids Q filter works in my BoldDesk account?
   Run the List Tickets API request using an external reference ID that is already stored on a ticket. If the request format is correct and the authenticated user has access to the ticket, the API response should return the matching ticket.

Related Articles

1. API Rate Limits: Optimizing RESTful API Usage
2. Generate and Manage API Keys in BoldDesk