Overview

Live Search enables you to search and access ticket data immediately after connecting a Linked Account, eliminating the wait for a full sync and letting your users see value fast.

How It Works

When you connect a ticketing system to Merge, Live Search lets you search for tickets by ticket_url , name , status, assignees, assignee_ids, collections, and collection_ids . Searching by URL is typically faster and ideal for specific tickets, while searching by name (full or partial string) may take slightly longer, especially for frequently found names. There’s no minimum character requirement for searches, but we recommend enforcing a minimum of 3 characters before searching to narrow down results.

When providing a filter, you should pass in values that match the values available natively in the third-party system (typically remote IDs). For full integration nuances on what is supported per integration and the typical remote values, refer to the live search integration nuances section below.

Essential ticket fields, such as the name, due date, description, type, tags, and timestamps (created, updated), are immediately available. Assignees (User Common Model) Merge IDs are also returned as a part of the ticket object. To fetch assignee metadata, you can hit the GET /users/{id} endpoint.

Endpoint

GET https://api.merge.dev/api/ticketing/v1/tickets/live-search

Query Parameters: at least one query parameter must be passed into a Live Search

ticket_url: the URL of the ticket

name: the text identifier for the ticket; can be either a substring or the full ticket name

status: the status of the ticket

assignees: comma-separated list of ticket assignees by name

assignee_ids: comma-separated list of ticket assignees by remote ID

collections: comma-separated list of ticket collections by name

collection_ids: comma-separated list of ticket collections by remote ID

Page sizes are defaulted to the third-party configurations

• Asana: default is 100 items per page

• ServiceNow: default is 10,000 items per page

• Salesforce Service Cloud: by default, we query for the first 200 results for both cases and ticket types, after which we use pagination to retrieve additional results

Real-Time Updates and Edits

Any changes made to tickets in your connected systems are pushed to Merge using third-party webhooks. Updates happen almost instantly, so your app always displays the latest data. You can also edit tickets after performing a live request for integrations that support POST or PATCH tickets.

If you need to update a single ticket quickly, the force resync endpoint lets you refresh specific ticket data in real-time with targeted API requests.

Endpoint

GET https://api.merge.dev/api/ticketing/v1/tickets/{id}/live-fetch

Search Efficiency and Customization

For large data sets, ticket results are displayed in pages (not supported by Asana), allowing you to paginate through them efficiently using the remote_next field in the endpoint response. This is especially useful when searching with substring matches, where many tickets might have similar titles.

If you are using Live Search for a typeahead use case, we recommend common typeahead best practices like debouncing and minimum character counts.

Live Search Integration Nuances

Asana

• Supported filters: ticket_url , name , status, assignee_ids, collection_ids

  • Ticket search by assignee names and collection names are not supported in Asana

• Supported ticket status filter values: [completed, incomplete]

• Filters are additive, which means chaining different filters together results in an AND* operation

Trello

• Supported filters: ticket_url , name , status, assignees, collections , collection_ids

  • Filtering assignees is by Trello username

  • collections and collection_ids filtering is limited to Trello boards

  • Supported ticket status filter values: [open, archived, complete, incomplete]

  • If filtering by collection_ids, at least one other filter among [name , status, assignees, collections] must be provided. This is a 3P search nuance.

  • Trello collection (board) search by name can be finicky. This is a known 3P nuance. Filtering by collection_ids (board IDs) is more reliable.

• Chaining filters within a specific filter class results in an OR* operation

  • For example, assignees=john,jacob results in filtering Trello tasks assigned to users john or jacob

• Chaining filters in different filter classes results in an *AND operation

  • For example, assignees=john and status=open results in filtering Trello tasks assigned to john with a status of open

ServiceNow

• Supported filters: ticket_url , name , status, assignees, assignee_ids

  • Supported ticket status filter values are the integer values in your ServiceNow instance which represent Task state

    • For example, 1, 2, 3…

  • Ticket name filters on the Task short description

• Chaining filters within a specific filter class results in an AND* operation

  • For example, assignees=john,jacob results in filtering ServiceNow tasks assigned to users john and jacob

• Chaining filters in different filter classes results in an *AND operation

  • For example, assignees=john and status=open results in filtering ServiceNow tasks assigned to john with a status of open

Linear

• Supported filters: ticket_url, assignee_ids, collection_ids, status(es), collections, assignees

• Only 1 user can be assigned to an issue at a time https://linear.app/docs/assigning-issues#overview so can’t filter by multiple assignee ids

• Allows filtering by multiple statuses - added logic to filter tickets by multiple statuses

• Chaining multiple filters results within the same class uses an OR* operation

  • For example, assignees=john,jacob results in filtering Linear tasks assigned to users john or jacob

• Chaining filters in different filter classes results in an *AND operation

  • For example, assignees=john and status=open results in filtering Linear tasks assigned to john with a status of open

• Supported ticket status filter values: [backlog, unstarted, cancelled, completed, started]

Clickup

• Supported filters: ticket_url, status(es), assignee_ids, collection_ids

• Collection names & Assignee names filtering not supported

• Projects which are Folders in ClickUp is supported by Merge

• Clickup limitations:

  • Clickup does not allow page sizing on their /tasks endpoint. To ensure accurate results, please use the available filters to query

  • ClickUp’s rate limits are fairly strict, so please apply as many task filters as possible to minimize API load.

• Chaining filters within the same filter class results in an OR* operation

  • For example, assignees=john,jacob results in filtering Clickup tasks assigned to users john or jacob

• Chaining filters in different filter classes results in an *AND operation

  • For example, assignees=john and status=open results in filtering Clickup tasks assigned to john with a status of open

• Supported ticket status filter values: [Open, open, to do, Closed, closed, complete, In Progress, In progress, in progress, On Hold, On hold, on hold]

Rally

• Supported filters: ticket_url, name, status(es), assignees (by username), collections, assignee_ids, collection_ids

  • Querying for assignees: can only query using username

• Objects supported by /artifacts: HierarchicalRequirement, Defect, DefectSuite

• Chaining filters within multiple filter classes results in an OR* operation

  • For example, assignees=john,jacob results in filtering Rally tasks assigned to users john or jacob

• Chaining filters in different filter classes results in an *AND operation

  • For example, assignees=john and status=open results in filtering Rally tasks assigned to john with a status of open

• Supported ticket status filter values: [Defined, Done, Completed, Measuring, Developing, Discovering, In-Progress]

Salesforce Service Cloud

• Support filters: ticket_url , name