Search tickets

REST API Reference

Search tickets

Request

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.

Optimizing search queries

Search queries can be complex, so optimizing them can help the performance of your search. Use the AND and OR operators to combine multiple filters to get the exact results you need and utilize pagination to limit the number of results returned. The default is 20 results per page and maximum is 150. See the pagination section for more details on how to use the starting_after param.

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"). Fields not in the table below, such as source.body, are rejected with a 400 error.

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

Searching by Category

When searching for tickets by the category field, specific terms must be used instead of the category names:

For Customer category tickets, use the term request.
For Back-office category tickets, use the term task.
For Tracker category tickets, use the term tracker.

Sorting

You can sort the results with a sort object, for example {"field": "created_at", "order": "ascending"}. field must be one of the fields in the table above, other than ticket_attribute.{id}, title and description. order is ascending or descending, and any other value is treated as descending. Without sort, results are sorted by updated_at, newest first.

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

Security

bearerAuth

Intercom-Versionstring(intercom_version)

Intercom API version.
If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example:2.17

Bodyapplication/json

querySingle filter search request (object) or multiple filter search request (object)required

One of:

Search using Intercoms Search APIs with a single filter.

paginationobject or null(Pagination: Starting After)

curl -i -X POST \
  https://api.intercom.io/tickets/search \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.17' \
  -d '{
    "query": {
      "operator": "AND",
      "value": [
        {
          "field": "created_at",
          "operator": ">",
          "value": "1306054154"
        }
      ]
    },
    "pagination": {
      "per_page": 5
    }
  }'

Responses

successful

Bodyapplication/json

typestring

Always ticket.list

Value:"ticket.list"

Example:"ticket.list"

ticketsArray of objects(Ticket)

The list of ticket objects

total_countinteger

A count of the total number of objects.

Example:12345

pagesobject 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.

Response

{
  "type": "ticket.list",
  "pages": {
    "type": "pages",
    "page": 1,
    "per_page": 5,
    "total_pages": 1
  },
  "total_count": 1,
  "tickets": [
    { … }
  ]
}