--- title: "Search tickets" method: POST path: "/tickets/search" tags: ["Tickets"] --- # Search tickets `POST /tickets/search` 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. {% admonition type="warning" name="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](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param. {% /admonition %} ### 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. | 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 | {% admonition type="info" name="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`. {% /admonition %} ### Accepted Operators {% admonition type="info" name="Searching based on `created_at`" %} You may use the `<=` or `>=` operators to search by `created_at`. {% /admonition %} 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 | ## Headers - `Intercom-Version` '1.0' | '1.1' | '1.2' | '1.3' | '1.4' | '2.0' | '2.1' | '2.2' | '2.3' | '2.4' | '2.5' | '2.6' | '2.7' | '2.8' | '2.9' | '2.10' | '2.11' | '2.12' | '2.13' | '2.14' — Intercom API version.
By default, it's equal to the version set in the app package. ## Request body - SearchRequest — Search using Intercoms Search APIs. - `query` union, required - SingleFilterSearchRequest — Search using Intercoms Search APIs with a single filter. - `field` string — The accepted field that you want to search on. - `operator` '=' | '!=' | 'IN' | 'NIN' | '<' | '>' | '~' | '!~' | '^' | '$' — The accepted operators you can use to define how you want to search for the value. - `value` union — The value that you want to search on. - string - integer - boolean - union[] - union - string - integer - MultipleFilterSearchRequest — Search using Intercoms Search APIs with more than one filter. - `operator` 'AND' | 'OR' — An operator to allow boolean inspection between multiple fields. - `value` union - MultipleFilterSearchRequest[] — Add mutiple filters. - SingleFilterSearchRequest[] — Add a single filter field. - `field` string — The accepted field that you want to search on. - `operator` '=' | '!=' | 'IN' | 'NIN' | '<' | '>' | '~' | '!~' | '^' | '$' — The accepted operators you can use to define how you want to search for the value. - `value` union — The value that you want to search on. - string - integer - boolean - union[] - … - `pagination` StartingAfterPaging, nullable - `per_page` integer — The number of results to fetch per page. - `starting_after` string, nullable — The cursor to use in the next request to get the next page of results. ## Response `200` successful - TicketList — Tickets are how you track requests from your users. - `type` 'ticket.list' — Always ticket.list - `tickets` Ticket[] — The list of ticket objects - `type` 'ticket' — Always ticket - `id` string — The unique identifier for the ticket which is given by Intercom. - `ticket_id` string — The ID of the Ticket used in the Intercom Inbox and Messenger. Do not use ticket_id for API queries. - `category` 'Customer' | 'Back-office' | 'Tracker' — Category of the Ticket. - `ticket_attributes` TicketCustomAttributes — An object containing the different attributes associated to the ticket as key-value pairs. For the default title and description attributes, the keys are `_default_title_` and `_default_description_`. - `ticket_state` TicketState, nullable — A ticket state, used to define the state of a ticket. - `type` string — String representing the object's type. Always has the value `ticket_state`. - `id` string — The id of the ticket state - `category` 'submitted' | 'in_progress' | 'waiting_on_customer' | 'resolved' — The category of the ticket state - `internal_label` string — The state the ticket is currently in, in a human readable form - visible in Intercom - `external_label` string — The state the ticket is currently in, in a human readable form - visible to customers, in the messenger, email and tickets portal. - `ticket_type` TicketType, nullable — A ticket type, used to define the data fields to be captured in a ticket. - `type` string — String representing the object's type. Always has the value `ticket_type`. - `id` string — The id representing the ticket type. - `category` 'Customer' | 'Back-office' | 'Tracker' — Category of the Ticket Type. - `name` string — The name of the ticket type - `description` string — The description of the ticket type - `icon` string — The icon of the ticket type - `workspace_id` string — The id of the workspace that the ticket type belongs to. - `ticket_type_attributes` TicketTypeAttributeList — A list of attributes associated with a given ticket type. - `type` string — String representing the object's type. Always has the value `ticket_type_attributes.list`. - `ticket_type_attributes` TicketTypeAttribute[] — A list of ticket type attributes associated with a given ticket type. - `type` string — String representing the object's type. Always has the value `ticket_type_attribute`. - `id` string — The id representing the ticket type attribute. - `workspace_id` string — The id of the workspace that the ticket type attribute belongs to. - `name` string — The name of the ticket type attribute - `description` string — The description of the ticket type attribute - `data_type` string — The type of the data attribute (allowed values: "string list integer decimal boolean datetime files") - `input_options` object — Input options for the attribute - `order` integer — The order of the attribute against other attributes - `required_to_create` boolean — Whether the attribute is required or not for teammates. - `required_to_create_for_contacts` boolean — Whether the attribute is required or not for contacts. - `visible_on_create` boolean — Whether the attribute is visible or not to teammates. - `visible_to_contacts` boolean — Whether the attribute is visible or not to contacts. - `default` boolean — Whether the attribute is built in or not. - `ticket_type_id` integer — The id of the ticket type that the attribute belongs to. - `archived` boolean — Whether the ticket type attribute is archived or not. - `created_at` integer — The date and time the ticket type attribute was created. - `updated_at` integer — The date and time the ticket type attribute was last updated. - `ticket_states` object — A list of ticket states associated with a given ticket type. - `type` string — String representing the object's type. Always has the value `list`. - `data` TicketState[] — A list of ticket states associated with a given ticket type. - `type` string — String representing the object's type. Always has the value `ticket_state`. - `id` string — The id of the ticket state - `category` 'submitted' | 'in_progress' | 'waiting_on_customer' | 'resolved' — The category of the ticket state - `internal_label` string — The state the ticket is currently in, in a human readable form - visible in Intercom - `external_label` string — The state the ticket is currently in, in a human readable form - visible to customers, in the messenger, email and tickets portal. - `archived` boolean — Whether the ticket type is archived or not. - `created_at` integer — The date and time the ticket type was created. - `updated_at` integer — The date and time the ticket type was last updated. - `contacts` TicketContacts — The list of contacts affected by a ticket. - `type` 'contact.list' — always contact.list - `contacts` ContactReference[] — The list of contacts affected by this ticket. - `type` 'contact' — always contact - `id` string — The unique identifier for the contact which is given by Intercom. - `external_id` string, nullable — The unique identifier for the contact which is provided by the Client. - `admin_assignee_id` string — The id representing the admin assigned to the ticket. - `team_assignee_id` string — The id representing the team assigned to the ticket. - `created_at` integer — The time the ticket was created as a UTC Unix timestamp. - `updated_at` integer — The last time the ticket was updated as a UTC Unix timestamp. - `open` boolean — Whether or not the ticket is open. If false, the ticket is closed. - `snoozed_until` integer — The time the ticket will be snoozed until as a UTC Unix timestamp. If null, the ticket is not currently snoozed. - `linked_objects` LinkedObjectList — An object containing metadata about linked conversations and linked tickets. Up to 1000 can be returned. - `type` 'list' — Always list. - `total_count` integer — The total number of linked objects. - `has_more` boolean — Whether or not there are more linked objects than returned. - `data` LinkedObject[] — An array containing the linked conversations and linked tickets. - `type` 'ticket' | 'conversation' — ticket or conversation - `id` string — The ID of the linked object - `category` 'Customer' | 'Back-office' | 'Tracker' | 'null', nullable — Category of the Linked Ticket Object. - `ticket_parts` TicketParts — A list of Ticket Part objects for each note and event in the ticket. There is a limit of 500 parts. - `type` 'ticket_part.list' - `ticket_parts` TicketPart[] — A list of Ticket Part objects for each ticket. There is a limit of 500 parts. - `type` string — Always ticket_part - `id` string — The id representing the ticket part. - `part_type` string — The type of ticket part. - `body` string, nullable — The message body, which may contain HTML. - `previous_ticket_state` 'submitted' | 'in_progress' | 'waiting_on_customer' | 'resolved' — The previous state of the ticket. - `ticket_state` 'submitted' | 'in_progress' | 'waiting_on_customer' | 'resolved' — The state of the ticket. - `created_at` integer — The time the ticket part was created. - `updated_at` integer — The last time the ticket part was updated. - `assigned_to` Reference — reference to another object - `type` string - `id` string, nullable - `author` TicketPartAuthor — The author that wrote or triggered the part. Can be a bot, admin, team or user. - `type` 'admin' | 'bot' | 'team' | 'user' — The type of the author - `id` string — The id of the author - `name` string, nullable — The name of the author - `email` string, email — The email of the author - `attachments` PartAttachment[] — A list of attachments for the part. - `type` string — The type of attachment - `name` string — The name of the attachment - `url` string — The URL of the attachment - `content_type` string — The content type of the attachment - `filesize` integer — The size of the attachment - `width` integer — The width of the attachment - `height` integer — The height of the attachment - `external_id` string, nullable — The external id of the ticket part - `redacted` boolean — Whether or not the ticket part has been redacted. - `app_package_code` string — The app package code if this part was created via API. Note this field won't show if the part was not created via API. - `updated_attribute_data` object, nullable — The updated attribute data of the ticket part. Only present for attribute update parts. - `attribute` object, required — Information about the attribute that was updated. - `type` 'attribute', required — The type of the object. Always 'attribute'. - `id` string, required — The unique identifier of the attribute. - `label` string, required — The human-readable name of the attribute. - `value` object, required — The new value of the attribute. - `type` 'value', required — The type of the object. Always 'value'. - `id` union, required - … - `label` union, required - … - `total_count` integer - `is_shared` boolean — Whether or not the ticket is shared with the customer. - `total_count` integer — A count of the total number of objects. - `pages` CursorPages, nullable — 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. - `type` 'pages' — the type of object `pages`. - `page` integer — The current page - `next` StartingAfterPaging, nullable - `per_page` integer — The number of results to fetch per page. - `starting_after` string, nullable — The cursor to use in the next request to get the next page of results. - `per_page` integer — Number of results per page - `total_pages` integer — Total number of pages --- [API](https://skmtc.net/intercom/apis/intercom-api.md) · [All operations](https://skmtc.net/intercom/apis/intercom-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/intercom/intercom-api/revisions/9517e80f2642/schema)