Contacts Search API - HoopAI Help Center

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

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

Endpoint

POST /contacts/search

Request body

Parameter	Type	Required	Description
`locationId`	string	Yes	Location ID to search within.
`page`	number	No	Page number for standard pagination. Do not use with `searchAfter`.
`pageLimit`	number	Yes	Results per page (max 500).
`searchAfter`	array	No	Cursor for pagination beyond 10,000 records. Value returned in each response.
`filters`	array	No	Filter criteria — see Filters below.
`sort`	array	No	Sort criteria — see Sort below.
`query`	string	No	Full-text search string (max 75 characters). Runs against searchable fields configured in Custom Field Settings.

Sample request

{
  "locationId": "5DP41231LkQsiKESj6rh",
  "page": 1,
  "pageLimit": 20,
  "filters": [
    { "field": "dnd", "operator": "eq", "value": true },
    {
      "group": "OR",
      "filters": [
        { "field": "firstNameLowerCase", "operator": "eq", "value": "alex" },
        { "field": "lastNameLowerCase", "operator": "eq", "value": "peter" }
      ]
    }
  ],
  "sort": [{ "field": "firstNameLowerCase", "direction": "desc" }],
  "query": "tom"
}

Pagination

Standard pagination (`page` + `pageLimit`)

Fetches up to 10,000 records total.
Maximum 500 records per request.
Use page and pageLimit to paginate through results.

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

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 contact attribute to filter on.
Operator — the comparison to apply.
Value — the value to compare against.

By default, all filters in the filters array are combined with AND logic.

Sample filter payload

{
  "filters": [
    {
      "group": "AND",
      "filters": [
        { "field": "firstNameLowerCase", "operator": "contains", "value": "John" },
        { "field": "email", "operator": "exists" }
      ]
    },
    {
      "group": "OR",
      "filters": [
        { "field": "city", "operator": "eq", "value": "New York" },
        { "field": "state", "operator": "eq", "value": "California" }
      ]
    }
  ]
}

Supported operators

Operator	Definition	Value type	Character limit
`eq`	Equals	Number, String, Boolean	75
`not_eq`	Not equals	Number, String, Boolean	75
`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 (`gte`/`lte`/`gt`/`lt`)	Object	75

Supported filter fields

Contact information

Display name	Field name	Supported operators
Contact ID	`id`	`eq`, `not_eq`
Contact Name	`contactName`	`eq`, `not_eq`, `exists`, `not_exists`
Address	`address`	`eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`
Assigned To	`assignedTo`	`eq`, `not_eq`, `exists`, `not_exists`
Business Name	`businessName`	`eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`
City	`city`	`eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`
Country	`country`	`eq`, `not_eq`, `exists`, `not_exists`
Company Name	`companyName`	`eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`
Created At	`dateAdded`	`range`, `exists`, `not_exists`
Updated At	`dateUpdated`	`range`, `exists`, `not_exists`
DND	`dnd`	`eq`, `not_eq`, `exists`, `not_exists`
Email	`email`	`eq`, `not_eq`, `exists`, `not_exists`
Followers	`followers`	`eq`, `not_eq`, `exists`, `not_exists`
First Name (lowercase)	`firstNameLowerCase`	`eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`
Last Name (lowercase)	`lastNameLowerCase`	`eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`
Is Valid WhatsApp	`isValidWhatsapp`	`eq`, `not_eq`, `exists`, `not_exists`
Last Email Clicked	`lastEmailClickedDate`	`range`, `exists`, `not_exists`
Last Email Opened	`lastEmailOpenedDate`	`range`, `exists`, `not_exists`
Phone	`phone`	`eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`
Postal Code	`postalCode`	`eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`
Source	`source`	`eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`
State	`state`	`eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`
Tags	`tags`	`eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`
Timezone	`timezone`	`eq`, `not_eq`, `exists`, `not_exists`
Contact Type	`type`	`eq`, `not_eq`, `exists`, `not_exists`
Is Valid Email	`validEmail`	`eq`, `not_eq`, `exists`, `not_exists`
Website	`website`	`eq`, `not_eq`, `exists`, `not_exists`
Date of Birth	`dateOfBirth`	`range`, `exists`, `not_exists`

Contact activity

Display name	Field name	Supported operators
Last Appointment	`lastAppointment`	`range`, `exists`, `not_exists`
Workflow (Active)	`activeWorkflows`	`eq`, `not_eq`, `exists`, `not_exists`
Workflow (Finished)	`finishedWorkflows`	`eq`, `not_eq`, `exists`, `not_exists`

Opportunity (nested filter)

Display name	Field + Sub-field	Operators
Pipeline	`opportunities` + `pipelineId`	`eq`, `not_eq`, `exists`, `not_exists`
Pipeline Stage	`opportunities` + `pipelineStageId`	`eq`, `not_eq`, `exists`, `not_exists`
Pipeline Status	`opportunities` + `status`	`eq`, `not_eq`, `exists`, `not_exists`

Custom fields

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

Sort

You can combine up to 2 sort criteria.

[
  { "field": "dateAdded", "direction": "desc" },
  { "field": "firstNameLowerCase", "direction": "asc" }
]

Supported sort fields

Display name	Field name
First Name (lowercase)	`firstNameLowerCase`
Last Name (lowercase)	`lastNameLowerCase`
Business Name	`businessName`
Date Created	`dateAdded`
Date Updated	`dateUpdated`
Email	`email`
DND	`dnd`
Source	`source`

Getting Started

​Endpoint

​Request body

​Sample request

​Pagination

​Standard pagination (page + pageLimit)

​Cursor-based pagination (searchAfter + pageLimit)

​Filters

​Sample filter payload

​Supported operators

​Supported filter fields

​Contact information

​Contact activity

​Opportunity (nested filter)

​Custom fields

​Sort

​Supported sort fields

Endpoint

Request body

Sample request

Pagination

Standard pagination (`page` + `pageLimit`)

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

Filters

Sample filter payload

Supported operators

Supported filter fields

Contact information

Contact activity

Opportunity (nested filter)

Custom fields

Sort

Supported sort fields