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

No tickets returned

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

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 add multiple external reference IDs in one request?
   Yes. Add multiple IDs inside the array and separate them with commas:
   externalreferenceids:["id1","id2"].

2. Do the external reference IDs need double quotes?
   Yes. Each ID must be wrapped in double quotes.

3. Does this confirm it works on my end?
   This article documents the supported request format. To confirm in your environment, run the request and verify the API response returns the expected ticket(s).

Related Articles

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