Skip to content
Home/
REST API Reference
/
/
Search tickets

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. 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"). The source.body field is unique as the search will not be performed against the entire value, but instead against every element of the value separately. For example, when searching for a conversation with a "I need support" body - the query should contain a = operator with the value "support" for such conversation to be returned. A query with a = operator and a "need support" value will not yield a result.

FieldType
idString
created_atDate (UNIX timestamp)
updated_atDate (UNIX timestamp)
titleString
descriptionString
categoryString
ticket_type_idString
contact_idsString
teammate_idsString
admin_assignee_idString
team_assignee_idString
openBoolean
stateString
snoozed_untilDate (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.

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

OperatorValid TypesDescription
=AllEquals
!=AllDoesn't Equal
INAllIn Shortcut for OR queries Values most be in Array
NINAllNot 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
~StringContains
!~StringDoesn't Contain
^StringStarts With
$StringEnds With
Security
bearerAuth
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default:"2.16"
Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:2.16
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.16' \
  -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": [
    { … }
  ]
}