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). On a collection field such as email_addresses or domains, that means one of the stored values equals the filter value. 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).

Operators by field type

If you omit the operator, the value is matched exactly (Is) for text, number, date, select, boolean, and collection fields. 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): Is, Is not, Contains, Does not contain, Is empty, Is not empty

Is matches when one of the stored values equals the filter value, and uses the same normalization as writes (email addresses and domains are trimmed and lowercased, so Jane@Acme.com finds jane@acme.com). Contains is a case-insensitive substring match across the stored values: acme.com also matches john@acme.com and acme.com.au. Use Is to look a record up by email or domain; it is also the faster of the two.

Is and Is not apply to collections of text values. Collections of structured values, such as meeting participants or message attachment_metadata, only support Contains and Does not contain; a bare value or Is on those fields returns a 400.

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, collection
`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 a person by email (exact match):

filter[email_addresses]=jane@example.com

Find a company by domain (exact match):

filter[domains]=acme.com

Find people whose email is on a domain (substring match):

filter[email_addresses][Contains]=@example.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.

On this page