Opportunities Search API

Due to the complexity of advanced filtering, updates may take a few seconds to appear in search results.

The Opportunities Search API lets you search for opportunities using extensive filtering, sorting, and pagination options.

Endpoint

POST /opportunities/search

Request body

Parameter	Type	Required	Description	Limit
`locationId`	string	Yes	Location ID to search within.	—
`page`	number	No	Page number for standard pagination. Do not use with `searchAfter`.	min: 0
`limit`	number	Yes	Results per page.	1–500
`searchAfter`	array	No	Cursor for pagination beyond 10,000 records. Value returned in each response.	—
`query`	string	No	Full-text search against configured searchable fields.	max 75 chars
`filters`	array	No	Filter criteria — see Filters below.	—
`sort`	array	No	Sort criteria — see Sort below.	—
`additionalDetails.notes`	boolean	No	Include notes (`true`/`false`).	—
`additionalDetails.tasks`	boolean	No	Include tasks (`true`/`false`).	—
`additionalDetails.calendarEvents`	boolean	No	Include calendar events (`true`/`false`).	—

Sample request

{
  "locationId": "5DP41231LkQsiKESj6rh",
  "page": 1,
  "limit": 20,
  "query": "john@example.com",
  "filters": [
    { "field": "status", "operator": "eq", "value": "open" },
    {
      "group": "OR",
      "filters": [
        { "field": "pipeline_id", "operator": "eq", "value": "bCkKGpDsyPP4peuKowkG" },
        { "field": "pipeline_stage_id", "operator": "eq", "value": "7915dedc-8f18-44d5-8bc3-77c04e994a10" }
      ]
    }
  ],
  "sort": [{ "field": "date_added", "direction": "desc" }],
  "additionalDetails": { "notes": true, "tasks": true, "calendarEvents": false }
}

Pagination

Standard pagination (`page` + `limit`)

Fetches up to 10,000 records total.
Maximum 500 records per request.

Cursor-based pagination (`searchAfter` + `limit`)

Required for more than 10,000 records.
Use the searchAfter value returned in each response as the start point for the next page.
Do not include page when using searchAfter.

Filters

Filters can be applied individually or grouped with AND / OR logical operators. Each filter has three components:

Field — the opportunity attribute to filter on.
Operator — the comparison to apply.
Value — the value to compare against.

Sample filter payload

{
  "group": "AND",
  "filters": [
    {
      "group": "AND",
      "filters": [
        { "field": "status", "operator": "eq", "value": "open" },
        { "field": "monetary_value", "operator": "range", "value": { "gte": 1000, "lte": 5000 } }
      ]
    },
    {
      "group": "OR",
      "filters": [
        { "field": "assigned_to", "operator": "eq", "value": "082goXVW3lIExEQPOnd3" },
        { "field": "source", "operator": "exists" }
      ]
    }
  ]
}

Supported operators

Operator	Definition	Value type	Limit
`eq`	Equals	Number, String, Boolean	—
`not_eq`	Not equals	Number, String, Boolean	—
`contains`	Contains (no special characters)	String	75
`not_contains`	Not contains (no special characters)	String	75
`exists`	Has a value	— (omit value)	—
`not_exists`	Has no value	— (omit value)	—
`range`	Range with `gte`, `lte`, `gt`, `lt`	Object	—

Supported filter fields

Opportunity information

Display name	Field name	Supported operators
Opportunity ID	`id`	`eq`, `not_eq`
Opportunity Name	`name`	`eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`
Monetary Value	`monetary_value`	`eq`, `not_eq`, `range`, `exists`, `not_exists`
Pipeline ID	`pipeline_id`	`eq`, `not_eq`, `exists`, `not_exists`
Pipeline Stage ID	`pipeline_stage_id`	`eq`, `not_eq`, `exists`, `not_exists`
Status	`status`	`eq`, `not_eq`, `exists`, `not_exists`
Lost Reason ID	`lost_reason_id`	`eq`, `not_eq`, `exists`, `not_exists`
Source	`source`	`eq`, `not_eq`, `exists`, `not_exists`
Assigned To	`assigned_to`	`eq`, `not_eq`, `exists`, `not_exists`
Followers	`followers`	`eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`

Contact information (on opportunity)

Display name	Field name	Supported operators
Contact ID	`contact_id`	`eq`, `not_eq`, `exists`, `not_exists`
Contact Name	`contact_name`	`eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`
Company Name	`company_name`	`eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`
Email	`email`	`eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`
Phone	`phone`	`eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`

Date fields

Display name	Field name	Supported operators
Date Added	`date_added`	`range`, `exists`, `not_exists`
Date Updated	`date_updated`	`range`, `exists`, `not_exists`
Last Status Change	`last_status_change_date`	`range`, `exists`, `not_exists`
Last Stage Change	`last_stage_change_date`	`range`, `exists`, `not_exists`

Custom fields

Field type	Field name format	Operators
Text, Large Text, Single Option, Radio, Phone	`custom_fields.{custom_field_id}`	`eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`
Checkbox, Multiple Options	`custom_fields.{custom_field_id}`	`eq`, `not_eq`, `exists`, `not_exists`
Numerical, Monetary	`custom_fields.{custom_field_id}`	`range`, `eq`, `not_eq`, `exists`, `not_exists`
Date	`custom_fields.{custom_field_id}`	`range`, `exists`, `not_exists`
Textbox List	`custom_fields.{field_id}.{option_id}`	`eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`

Sort

You can combine up to 2 sort criteria.

[
  { "field": "date_added", "direction": "desc" },
  { "field": "monetary_value", "direction": "asc" }
]

Supported sort fields

Display name	Field name
Date Created	`date_added`
Date Updated	`date_updated`
Opportunity Name	`name`
Monetary Value	`monetary_value`
Last Status Change	`last_status_change_date`
Last Stage Change	`last_stage_change_date`

Developer Basics

Guides

API Overview

Concepts & Guides

Authentication

Endpoint

Request body

Sample request

Filters

Sample filter payload

Supported operators

Supported filter fields

Opportunity information

Contact information (on opportunity)

Date fields

Custom fields

Sort

Supported sort fields

​Endpoint

​Request body

​Sample request

​Pagination

​Standard pagination (page + limit)

​Cursor-based pagination (searchAfter + limit)

​Filters

​Sample filter payload

​Supported operators

​Supported filter fields

​Opportunity information

​Contact information (on opportunity)

​Date fields

​Custom fields

​Sort

​Supported sort fields

Endpoint

Request body

Sample request

Pagination

Standard pagination (`page` + `limit`)

Cursor-based pagination (`searchAfter` + `limit`)

Filters

Sample filter payload

Supported operators

Supported filter fields

Opportunity information

Contact information (on opportunity)

Date fields

Custom fields

Sort

Supported sort fields