Filtering and Search

Filtering

GET /objects/{object}/resources?filter[{field}]={value}

Each filter[{field}] narrows the result set. Multiple filters are combined with AND: every condition must match. OR across fields is not currently supported.

Basic filter

curl --globoff \
  -H "Authorization: api-key YOUR_API_KEY" \
  "https://api.clarify.ai/v1/workspaces/acme/objects/person/resources?filter[job_title]=VP%20Engineering"

A bare value matches exactly (the Is operator). To match on a substring, use the Contains operator (see below).

Filter with an operator

Pass the operator as a second bracket. Operator names are case-sensitive; use the exact casing shown in the tables below.

curl --globoff \
  -H "Authorization: api-key YOUR_API_KEY" \
  "https://api.clarify.ai/v1/workspaces/acme/objects/deal/resources?filter[amount][Greater%20than]=50000"

The [ ] brackets trigger curl's URL globbing. Pass --globoff to turn it off, and remember to URL-encode spaces in operator names (Greater than → Greater%20than).

If you omit the operator, the value is matched exactly (Is) for text, number, date, select, and boolean fields. Collection and multi-select fields have no exact-match operator, so you must name one explicitly (for example, Contains).

Text and long text: Is, Is not, Contains, Does not contain, Starts with, Ends with, Is empty, Is not empty

There is no Equals operator. For an exact match use Is (or just pass the bare value); for a partial match use Contains. Passing an unknown operator name returns a 400.

Number (including currency amounts): Is, Is not, Greater than, Greater than or equal, Less than, Less than or equal, Is empty, Is not empty

Date and datetime: Is, Is not, Is before, Is on or before, Is after, Is on or after, Is empty, Is not empty

Single select: Is, Is not, One of, Not one of, Is empty, Is not empty

Multi select: Contains, Does not contain, Is empty, Is not empty

Boolean (checkbox): Is, Is not, Is set, Is not set

Collections (email addresses, domains, phone numbers, labels): Contains, Does not contain, Is empty, Is not empty

Record IDs: Is, Is not, Is empty, Is not empty

Shorthand operators

For common cases you can encode the operator directly in the value instead of using a second bracket.

Shorthand	Equivalent operator	Field types
`filter[amount]=>50000`	`Greater than`	Number, date
`filter[amount]=>=50000`	`Greater than or equal`	Number, date
`filter[amount]=<50000`	`Less than`	Number, date
`filter[amount]=<=50000`	`Less than or equal`	Number, date
`filter[stage]=!=Lost`	`Is not`	Number, date, text, select, boolean
`filter[name]=Smith`	`Contains`	Text
`filter[name]=Smith*`	`Starts with`	Text
`filter[name]=*Smith`	`Ends with`	Text
`filter[stage]=Won,Negotiation`	`One of`	Select, multi select
`filter[stage]=null`	`Is empty`	Most field types
`filter[stage]=!null`	`Is not empty`	Most field types

Range queries

Combine two operators on the same field to express a range. Both conditions are ANDed together:

filter[amount][Greater than]=10000&filter[amount][Less than or equal]=50000

Examples

Find people by email:

filter[email_addresses][Contains]=jane@example.com

Find companies by domain:

filter[domains][Contains]=acme.com

Find deals above a threshold:

filter[amount][Greater than]=50000

Find deals created after a date:

filter[_created_at][Is after]=2024-01-01

Find records by select value:

filter[stage][One of]=Negotiation,Proposal

Find people with no recorded email interaction (empty field):

filter[last_email_interaction]=null

To filter by a field on a related record, use a dotted path that starts with the object you are querying, followed by the relationship field and the target field. For example, to find people whose company is named "Acme":

curl --globoff \
  -H "Authorization: api-key YOUR_API_KEY" \
  "https://api.clarify.ai/v1/workspaces/acme/objects/person/resources?filter[person.company_id.name]=Acme"

Here company_id is the relationship field on person that points to its company. Relationship filters can traverse up to three levels deep. You do not need to include the relationship to filter on it. Add include only when you also want the related record returned in the response (see below).

Including relationships

Use the include parameter to expand related records inline. Pass the relationship field name, separating multiple relationships with commas:

curl --globoff \
  -H "Authorization: api-key YOUR_API_KEY" \
  "https://api.clarify.ai/v1/workspaces/acme/objects/person/resources?include=company_id,deals"

Ordering

Sort results with the sortOrder parameter (dir is ASC or DESC):

sortOrder[column]=amount&sortOrder[dir]=DESC

See Pagination for paging through results.