# 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 request to . 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 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 results per page. See the pagination section for more details on how to use the 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 accepts a date, the cannot be a string such as ). The 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 body - the query should contain a operator with the value for such conversation to be returned. A query with a operator and a value will not yield a result. | Field | Type | | :---------------------------------------- | :--------------------------------------------------------------------------------------- | | id | String | | created_at | Date (UNIX timestamp) | | updated_at | Date (UNIX timestamp) | | _default_title_ | String | | _default_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 {% admonition type="info" name="Searching based on " %} You may use the operators to search by . {% /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 queries Values most be in Array | | NIN | All | Not In Shortcut for 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 | Endpoint: POST /tickets/search Version: 2.12 Security: bearerAuth ## Header parameters: - `Intercom-Version` (string) Intercom API version.By default, it's equal to the version set in the app package. Enum: "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", "Unstable" ## Request fields (application/json): - `query` (any, required) - `pagination` (object,null) - `pagination.per_page` (integer) The number of results to fetch per page. Example: 2 - `pagination.starting_after` (string,null) The cursor to use in the next request to get the next page of results. Example: "your-cursor-from-response" ## Response 200 fields (application/json): - `type` (string) Always ticket.list Enum: "ticket.list" - `tickets` (array) The list of ticket objects - `tickets.type` (string) Always ticket Enum: "ticket" - `tickets.id` (string) The unique identifier for the ticket which is given by Intercom. Example: "1295" - `tickets.ticket_id` (string) The ID of the Ticket used in the Intercom Inbox and Messenger. Do not use ticket_id for API queries. Example: "1390" - `tickets.category` (string) Category of the Ticket. Enum: "Customer", "Back-office", "Tracker" - `tickets.ticket_attributes` (object) An object containing the different attributes associated to the ticket as key-value pairs. For the default title and description attributes, the keys are and . Example: {"_default_title_":"Found a bug","_default_description_":"The button's not working"} - `tickets.ticket_state` (object,null) A ticket state, used to define the state of a ticket. - `tickets.ticket_state.type` (string) String representing the object's type. Always has the value . Example: "ticket_state" - `tickets.ticket_state.id` (string) The id of the ticket state Example: "12" - `tickets.ticket_state.category` (string) The category of the ticket state Enum: "submitted", "in_progress", "waiting_on_customer", "resolved" - `tickets.ticket_state.internal_label` (string) The state the ticket is currently in, in a human readable form - visible in Intercom Example: "With Dev Team" - `tickets.ticket_state.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. Example: "In Progress" - `tickets.ticket_type` (object,null) A ticket type, used to define the data fields to be captured in a ticket. - `tickets.ticket_type.id` (string) The id representing the ticket type. Example: "1295" - `tickets.ticket_type.category` (string) Category of the Ticket Type. Enum: "Customer", "Back-office", "Tracker" - `tickets.ticket_type.name` (string) The name of the ticket type Example: "Bug" - `tickets.ticket_type.description` (string) The description of the ticket type Example: "A bug that has been reported." - `tickets.ticket_type.icon` (string) The icon of the ticket type Example: "🐞" - `tickets.ticket_type.workspace_id` (string) The id of the workspace that the ticket type belongs to. Example: "ecahpwf5" - `tickets.ticket_type.ticket_type_attributes` (object) A list of attributes associated with a given ticket type. - `tickets.ticket_type.ticket_type_attributes.ticket_type_attributes` (array) A list of ticket type attributes associated with a given ticket type. - `tickets.ticket_type.ticket_type_attributes.ticket_type_attributes.id` (string) The id representing the ticket type attribute. Example: "1" - `tickets.ticket_type.ticket_type_attributes.ticket_type_attributes.workspace_id` (string) The id of the workspace that the ticket type attribute belongs to. Example: "ecahpwf5" - `tickets.ticket_type.ticket_type_attributes.ticket_type_attributes.name` (string) The name of the ticket type attribute Example: "Title" - `tickets.ticket_type.ticket_type_attributes.ticket_type_attributes.description` (string) The description of the ticket type attribute Example: "Bug title." - `tickets.ticket_type.ticket_type_attributes.ticket_type_attributes.data_type` (string) The type of the data attribute (allowed values: "string list integer decimal boolean datetime files") Example: "string" - `tickets.ticket_type.ticket_type_attributes.ticket_type_attributes.input_options` (object) Input options for the attribute Example: "multiline: true" - `tickets.ticket_type.ticket_type_attributes.ticket_type_attributes.order` (integer) The order of the attribute against other attributes Example: 1 - `tickets.ticket_type.ticket_type_attributes.ticket_type_attributes.required_to_create` (boolean) Whether the attribute is required or not for teammates. - `tickets.ticket_type.ticket_type_attributes.ticket_type_attributes.required_to_create_for_contacts` (boolean) Whether the attribute is required or not for contacts. - `tickets.ticket_type.ticket_type_attributes.ticket_type_attributes.visible_on_create` (boolean) Whether the attribute is visible or not to teammates. - `tickets.ticket_type.ticket_type_attributes.ticket_type_attributes.visible_to_contacts` (boolean) Whether the attribute is visible or not to contacts. - `tickets.ticket_type.ticket_type_attributes.ticket_type_attributes.default` (boolean) Whether the attribute is built in or not. Example: true - `tickets.ticket_type.ticket_type_attributes.ticket_type_attributes.ticket_type_id` (integer) The id of the ticket type that the attribute belongs to. Example: 42 - `tickets.ticket_type.ticket_type_attributes.ticket_type_attributes.archived` (boolean) Whether the ticket type attribute is archived or not. - `tickets.ticket_type.ticket_type_attributes.ticket_type_attributes.created_at` (integer) The date and time the ticket type attribute was created. - `tickets.ticket_type.ticket_type_attributes.ticket_type_attributes.updated_at` (integer) The date and time the ticket type attribute was last updated. - `tickets.ticket_type.ticket_states` (object) A list of ticket states associated with a given ticket type. - `tickets.ticket_type.ticket_states.data` (array) A list of ticket states associated with a given ticket type. - `tickets.ticket_type.archived` (boolean) Whether the ticket type is archived or not. - `tickets.ticket_type.created_at` (integer) The date and time the ticket type was created. - `tickets.ticket_type.updated_at` (integer) The date and time the ticket type was last updated. - `tickets.contacts` (object) The list of contacts affected by a ticket. - `tickets.contacts.type` (string) always contact.list Enum: "contact.list" - `tickets.contacts.contacts` (array) The list of contacts affected by this ticket. - `tickets.contacts.contacts.type` (string) always contact Enum: "contact" - `tickets.contacts.contacts.id` (string) The unique identifier for the contact which is given by Intercom. Example: "5ba682d23d7cf92bef87bfd4" - `tickets.contacts.contacts.external_id` (string,null) The unique identifier for the contact which is provided by the Client. Example: "f3b87a2e09d514c6c2e79b9a" - `tickets.admin_assignee_id` (string) The id representing the admin assigned to the ticket. Example: "1295" - `tickets.team_assignee_id` (string) The id representing the team assigned to the ticket. Example: "1295" - `tickets.created_at` (integer) The time the ticket was created as a UTC Unix timestamp. Example: 1663597223 - `tickets.updated_at` (integer) The last time the ticket was updated as a UTC Unix timestamp. Example: 1663597260 - `tickets.open` (boolean) Whether or not the ticket is open. If false, the ticket is closed. Example: true - `tickets.snoozed_until` (integer) The time the ticket will be snoozed until as a UTC Unix timestamp. If null, the ticket is not currently snoozed. Example: 1663597260 - `tickets.linked_objects` (object) An object containing metadata about linked conversations and linked tickets. Up to 1000 can be returned. - `tickets.linked_objects.type` (string) Always list. Enum: "list" - `tickets.linked_objects.total_count` (integer) The total number of linked objects. Example: 100 - `tickets.linked_objects.has_more` (boolean) Whether or not there are more linked objects than returned. - `tickets.linked_objects.data` (array) An array containing the linked conversations and linked tickets. - `tickets.linked_objects.data.type` (string) ticket or conversation Enum: "ticket", "conversation" - `tickets.linked_objects.data.id` (string) The ID of the linked object Example: "7583" - `tickets.linked_objects.data.category` (string,null) Category of the Linked Ticket Object. Enum: "Customer", "Back-office", "Tracker", null - `tickets.ticket_parts` (object) A list of Ticket Part objects for each note and event in the ticket. There is a limit of 500 parts. - `tickets.ticket_parts.type` (string) Enum: "ticket_part.list" - `tickets.ticket_parts.ticket_parts` (array) A list of Ticket Part objects for each ticket. There is a limit of 500 parts. - `tickets.ticket_parts.ticket_parts.type` (string) Always ticket_part Example: "ticket_part" - `tickets.ticket_parts.ticket_parts.id` (string) The id representing the ticket part. Example: "3" - `tickets.ticket_parts.ticket_parts.part_type` (string) The type of ticket part. Example: "comment" - `tickets.ticket_parts.ticket_parts.body` (string,null) The message body, which may contain HTML. Example: "

Okay!

" - `tickets.ticket_parts.ticket_parts.previous_ticket_state` (string) The previous state of the ticket. Enum: "submitted", "in_progress", "waiting_on_customer", "resolved" - `tickets.ticket_parts.ticket_parts.ticket_state` (string) The state of the ticket. Enum: "submitted", "in_progress", "waiting_on_customer", "resolved" - `tickets.ticket_parts.ticket_parts.created_at` (integer) The time the ticket part was created. Example: 1663597223 - `tickets.ticket_parts.ticket_parts.updated_at` (integer) The last time the ticket part was updated. Example: 1663597260 - `tickets.ticket_parts.ticket_parts.assigned_to` (object) reference to another object - `tickets.ticket_parts.ticket_parts.assigned_to.id` (string,null) Example: "1a2b3c" - `tickets.ticket_parts.ticket_parts.author` (object) The author that wrote or triggered the part. Can be a bot, admin, team or user. - `tickets.ticket_parts.ticket_parts.author.type` (string) The type of the author Enum: "admin", "bot", "team", "user" - `tickets.ticket_parts.ticket_parts.author.id` (string) The id of the author Example: "274" - `tickets.ticket_parts.ticket_parts.author.name` (string,null) The name of the author Example: "Operator" - `tickets.ticket_parts.ticket_parts.author.email` (string) The email of the author Example: "operator+abcd1234@intercom.io" - `tickets.ticket_parts.ticket_parts.attachments` (array) A list of attachments for the part. - `tickets.ticket_parts.ticket_parts.attachments.type` (string) The type of attachment Example: "upload" - `tickets.ticket_parts.ticket_parts.attachments.name` (string) The name of the attachment Example: "example.png" - `tickets.ticket_parts.ticket_parts.attachments.url` (string) The URL of the attachment Example: "https://picsum.photos/200/300" - `tickets.ticket_parts.ticket_parts.attachments.content_type` (string) The content type of the attachment Example: "image/png" - `tickets.ticket_parts.ticket_parts.attachments.filesize` (integer) The size of the attachment Example: 100 - `tickets.ticket_parts.ticket_parts.attachments.width` (integer) The width of the attachment Example: 100 - `tickets.ticket_parts.ticket_parts.attachments.height` (integer) The height of the attachment Example: 100 - `tickets.ticket_parts.ticket_parts.external_id` (string,null) The external id of the ticket part Example: "abcd1234" - `tickets.ticket_parts.ticket_parts.redacted` (boolean) Whether or not the ticket part has been redacted. - `tickets.ticket_parts.total_count` (integer) Example: 2 - `tickets.is_shared` (boolean) Whether or not the ticket is shared with the customer. Example: true - `total_count` (integer) A count of the total number of objects. Example: 12345 - `pages` (object,null) 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. - `pages.type` (string) the type of object . Enum: "pages" - `pages.page` (integer) The current page Example: 1 - `pages.next` (object,null) - `pages.next.per_page` (integer) The number of results to fetch per page. Example: 2 - `pages.next.starting_after` (string,null) The cursor to use in the next request to get the next page of results. Example: "your-cursor-from-response" - `pages.per_page` (integer) Number of results per page Example: 2 - `pages.total_pages` (integer) Total number of pages Example: 13