Search tickets

You can search for multiple tickets by the value of their attributes in order to fetch exactly which ones you want.

To search for tickets, you send a POST request to https://api.intercom.io/tickets/search.

This will accept a query object in the body which will define your filters.

Nesting & Limitations

You can nest these filters in order to get even more granular insights that pinpoint exactly what you need. Example: (1 OR 2) AND (3 OR 4). There are some limitations to the amount of multiples there can be:

There's a limit of max 2 nested filters
There's a limit of max 15 filters for each AND or OR group

Accepted Fields

Most keys listed as part of the Ticket model are searchable, whether writeable or not. The value you search for has to match the accepted type, otherwise the query will fail (ie. as created_at accepts a date, the value cannot be a string such as "foobar").

Field	Type
id	String
created_at	Date (UNIX timestamp)
updated_at	Date (UNIX timestamp)
title	String
description	String
category	String
ticket_type_id	String
contact_ids	String
teammate_ids	String
admin_assignee_id	String
team_assignee_id	String
open	Boolean
state	String
snoozed_until	Date (UNIX timestamp)
ticket_attribute.{id}	String or Boolean or Date (UNIX timestamp) or Float or Integer

Accepted Operators

Searching based on `created_at`

You may use the <= or >= operators to search by created_at.

The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string ("="). The operator has to be compatible with the field's type (eg. you cannot search with > for a given string value as it's only compatible for integer's and dates).

Operator	Valid Types	Description
=	All	Equals
!=	All	Doesn't Equal
IN	All	In Shortcut for `OR` queries Values most be in Array
NIN	All	Not In Shortcut for `OR !` queries Values must be in Array
>	Integer Date (UNIX Timestamp)	Greater (or equal) than
<	Integer Date (UNIX Timestamp)	Lower (or equal) than
~	String	Contains
!~	String	Doesn't Contain
^	String	Starts With
$	String	Ends With

{ "query": { "operator": "AND", "value": [ { "field": "id", "operator": "=", "value": "4903" }, { "operator": "OR", "value": [ { "field": "id", "operator": "=", "value": "4903" }, { "field": "id", "operator": "=", "value": "4903" } ] } ] } }

{ "type": "ticket.list", "pages": { "type": "pages", "page": 1, "per_page": 150, "total_pages": 1 }, "total_count": 1, "tickets": [ { "type": "ticket", "id": "4903", "ticket_id": "223", "ticket_attributes": { "title": "attribute_value", "description": null }, "ticket_state": "submitted", "ticket_state_internal_label": "Submitted", "ticket_state_external_label": "Submitted", "ticket_type": { "type": "ticket_type", "id": "910", "name": "my-ticket-type-23", "description": "my ticket type description is awesome.", "icon": "🦁", "workspace_id": "this_is_an_id642_that_should_be_at_least_", "archived": false, "created_at": 1712223168, "updated_at": 1712223168, "is_internal": false, "ticket_type_attributes": { "type": "list", "data": [ { "type": "ticket_type_attribute", "id": "2503", "workspace_id": "this_is_an_id642_that_should_be_at_least_", "name": "title", "description": "ola", "data_type": "string", "input_options": null, "order": 0, "required_to_create": true, "required_to_create_for_contacts": false, "visible_on_create": true, "visible_to_contacts": false, "default": false, "ticket_type_id": 910, "archived": false, "created_at": 1712223168, "updated_at": 1712223168 }, { "type": "ticket_type_attribute", "id": "2504", "workspace_id": "this_is_an_id642_that_should_be_at_least_", "name": "description", "description": "ola", "data_type": "string", "input_options": null, "order": 0, "required_to_create": true, "required_to_create_for_contacts": false, "visible_on_create": true, "visible_to_contacts": false, "default": false, "ticket_type_id": 910, "archived": false, "created_at": 1712223168, "updated_at": 1712223168 } ] }, "category": "Back-office" }, "contacts": { "type": "contact.list", "contacts": [ { "type": "contact", "id": "660e73c06abd01bd27af623a", "external_id": "ba95f43e-ddbd-4e7a-9581-54ff26ae28e4" } ] }, "admin_assignee_id": "0", "team_assignee_id": "0", "created_at": 1712223168, "updated_at": 1712223169, "ticket_parts": { "type": "ticket_part.list", "ticket_parts": [ { "type": "ticket_part", "id": "1154", "part_type": "ticket_state_updated_by_admin", "ticket_state": "submitted", "previous_ticket_state": "submitted", "created_at": 1712223169, "updated_at": 1712223169, "author": { "id": "991282774", "type": "admin", "name": "Ciaran446 Lee", "email": "admin446@email.com" }, "attachments": [ ], "redacted": false } ], "total_count": 1 }, "open": true, "linked_objects": { "type": "list", "data": [ ], "total_count": 0, "has_more": false }, "category": "Back-office", "is_shared": false } ] }

type	string Always ticket.list Value: "ticket.list"
	Array of objects or null (Ticket) The list of ticket objects
total_count	integer A count of the total number of objects.
	object or null (Cursor based pages) Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.

Search tickets

Nesting & Limitations

Accepted Fields

Accepted Operators

header Parameters

Request Body schema: application/json

Response Schema: application/json

Was this page helpful?

required	single_filter_search_request (object) or multiple_filter_search_request (object)
	object or null (StartingAfterPaging)