Filtering

Some top level API resources can be filtered when listing them. Using filtering is a faster alternative to paginating through all resources. To create a search query, review the filter syntax and reference the filterable fields of the resource.

Examples

People search

Listing people by name

GET /v1/people?filter[fullName][eq]=John Doe

Listing people by email domain or with empty emails

GET /v1/people?filter[emails][like]=@folk.app&filter[emails][empty]&combinator=or

Listing people of a specific gender. Authorised values are ‘Male’, ‘Female’, ‘Other’, ‘Unknown’

GET /v1/people?filter[gender][eq]=Female

Listing people not in any group

GET /v1/people?filter[groups][empty]

Listing people in some group

GET /v1/people?filter[groups][in][id]=grp_79b6ed73-9939-4118-ba65-7f8cdf401052

Listing people in all listed groups

GET /v1/people?filter[groups][all][id]=grp_79b6ed73-9939-4118-ba65-7f8cdf401052&filter[groups][all][id]=grp_f19d5fa3-6ffb-4f1f-9298-96c19f222e2e

Listing people in a company

GET /v1/people?filter[companies][in][id]=com_f3855422-6740-4e6a-aa5e-449ac77047d0

Listing people the team last interacted with after a given date

GET /v1/people?filter[interactionMetadata.workspace.lastInteractedAt][gt]=2025-01-01

Listing people you last interacted with after a given date

GET /v1/people?filter[interactionMetadata.user.lastInteractedAt][gt]=2025-01-01

Listing people assigned to some users

GET /v1/people?filter[customFieldValues.grp_79b6ed73-9939-4118-ba65-7f8cdf401052.Owner][in][email]=[e-mail]&filter[customFieldValues.grp_79b6ed73-9939-4118-ba65-7f8cdf401052.Owner][in][email]=[e-mail]

Listing people associated to some contacts

GET /v1/people?filter[customFieldValues.grp_79b6ed73-9939-4118-ba65-7f8cdf401052.Relationships][in][id]=per_b6b9edb9-166d-4bdf-a0bf-8d7dac1de98a&filter[customFieldValues.grp_79b6ed73-9939-4118-ba65-7f8cdf401052.Relationships][in][id]=com_ee7c7212-99ba-4e8d-bd14-9ff369c87a1c

Companies search

Listing companies by name

GET /v1/companies?filter[name][eq]=ECMA

Listing companies not in any group

GET /v1/companies?filter[groups][empty]

Objects search

Objects of every type are filtered the same way. The examples below list deals, whose object type is Deals.

Listing deals by name

GET /v1/groups/grp_bc984b3f-0386-434d-82d7-a91eb6badd71/Deals?filter[name][eq]=Project Alpha

Listing deals with the status “Qualified”

GET /v1/groups/grp_bc984b3f-0386-434d-82d7-a91eb6badd71/Deals?filter[customFieldValues.Status][in]=Qualified

Tasks search

Listing tasks due after a given date

GET /v1/tasks?filter[dueAt][gt]=2025-01-01

Listing tasks not yet completed

GET /v1/tasks?filter[completedAt][empty]

Listing tasks assigned to some users

GET /v1/tasks?filter[assigneeUserId][in]=usr_79b6ed73-9939-4118-ba65-7f8cdf401052

Listing tasks linked to a person

GET /v1/tasks?filter[entity][in]=per_f3855422-6740-4e6a-aa5e-449ac77047d0

Filter syntax

The filter syntax allows you to specify conditions for the fields you want to filter by. The syntax is as follows:

?filter[<field>][<operator>]=<value>

Where:

• <field> is the field we want to filter on
• <operator> is the operation we want to perform
• <value> is the value we’re filtering against

Operators

The following operators are available for filtering:

Operator	Meaning	Applicable to
eq	field is equal to the value	Text, numbers, and dates fields
not_eq	field is not equal to the value	Text, numbers, and dates fields
gt	field is greater than the value	Numbers and dates fields
lt	field is less than the value	Numbers and dates fields
like	field matches the value	Text
not_like	field does not match the value	Text
all	field is equal to the list of values	Multi reference fields
in	field is in the list of values	Single and multi reference fields
not_in	field is not in the list of values	Single and multi reference fields
empty	field is empty	All fields
not_empty	field is not empty	All fields

Filterable fields

Select options are matched by their exact label (case-sensitive): an unknown label matches nothing.

Filterable fields for people

Field	Usage	Supported operators
fullName	?filter[fullName][like]=John	eq, not_eq, like, not_like, empty, not_empty
firstName	?filter[firstName][eq]=John	eq, not_eq, like, not_like,empty, not_empty
lastName	?filter[lastName][not_eq]=Doe	eq, not_eq, like, not_like,empty, not_empty
jobTitle	?filter[jobTitle][like]=Developer	eq, not_eq, like, not_like,empty, not_empty
birthday	?filter[birthday][gt]=1990-01-01	eq, not_eq, gt, lt, empty, not_empty
description	?filter[description][like]=team player	eq, not_eq, like, not_like,empty, not_empty
emails	?filter[emails][like]=@folk.app	eq, not_eq, like, not_like,empty, not_empty
phones	?filter[phones][eq]=[phone]	eq, not_eq, like, not_like,empty, not_empty
addresses	?filter[addresses][not_like]=Paris	eq, not_eq, like, not_like,empty, not_empty
urls	?filter[urls][not_eq]=https://example.com	eq, not_eq, like, not_like,empty, not_empty
companies	?filter[companies][in][id]=com_c5993dec-0375-407e-9e0a-a310d39f65bd	all, in, not_in, empty, not_empty
groups	?filter[groups][in][id]=grp_c5993dec-0375-407e-9e0a-a310d39f65bd	all, in, not_in, empty, not_empty
createdAt (day precision)	?filter[createdAt][gt]=2020-01-01	eq, not_eq, gt, lt, empty, not_empty
createdBy	?filter[createdBy][in][email]=[e-mail]&filter[createdBy][in][id]=usr_c5993dec-0375-407e-9e0a-a310d39f65bd	in, not_in, empty, not_empty
interactionMetadata.workspace.lastInteractedAt (day precision)	?filter[interactionMetadata.workspace.lastInteractedAt][gt]=2025-01-01	eq, not_eq, gt, lt, empty, not_empty
interactionMetadata.user.lastInteractedAt (day precision)	?filter[interactionMetadata.user.lastInteractedAt][gt]=2025-01-01 This field is scoped to the user behind the API key. The same request made with API keys from different workspace users can return different results.	eq, not_eq, gt, lt, empty, not_empty
customFieldValues.{groupId}.Text	?filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Text][like]=team player	eq, not_eq, like, not_like,empty, not_empty
customFieldValues.{groupId}.Date	?filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Date][gt]=2020-01-01	eq, not_eq, gt, lt, empty, not_empty
customFieldValues.{groupId}.Number	?filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Number][lt]=200	eq, not_eq, gt, lt, empty, not_empty
customFieldValues.{groupId}.Status	?filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Status][in]=In Progress	in, not_in, empty, not_empty
customFieldValues.{groupId}.Tags	?filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Tags][in]=B2B&filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Tags][in]=B2C	all, in, not_in, empty, not_empty
customFieldValues.{groupId}.Relationships	?filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Relationships][in][id]=per_a858d1bd-19d3-486d-87a4-c3b13d5b9a99	all, in, not_in, empty, not_empty
customFieldValues.{groupId}.Assign	?filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Assign][in][email]=[e-mail]&filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Assign][in][id]=usr_d24b4748-8a5f-4a46-89fe-f19cff553a22	all, in, not_in, empty, not_empty
customFieldValues.{groupId}.Deals	?filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Deals][in][id]=obj_5ef2bef1-5234-4e09-bc15-f830697604b8	all, in, not_in, empty, not_empty

Filterable fields for companies

Field	Usage	Supported operators
name	?filter[name][like]=ECMA	eq, not_eq, like, not_like,empty, not_empty
description	?filter[description][like]=prospect	eq, not_eq, like, not_like,empty, not_empty
emails	?filter[emails][like]=@folk.app	eq, not_eq, like, not_like,empty, not_empty
phones	?filter[phones][eq]=[phone]	eq, not_eq, like, not_like,empty, not_empty
addresses	?filter[addresses][not_like]=Paris	eq, not_eq, like, not_like,empty, not_empty
urls	?filter[urls][not_eq]=https://example.com	eq, not_eq, like, not_like,empty, not_empty
groups	?filter[groups][in][id]=grp_c5993dec-0375-407e-9e0a-a310d39f65bd	all, in, not_in, empty, not_empty
createdAt (day precision)	?filter[createdAt][gt]=2020-01-01	eq, not_eq, gt, lt, empty, not_empty
createdBy	?filter[createdBy][in][email]=[e-mail]&filter[createdBy][in][id]=usr_c5993dec-0375-407e-9e0a-a310d39f65bd	in, not_in, empty, not_empty
fundingRaised	?filter[fundingRaised][gt]=2000000	eq, not_eq, gt, lt, empty, not_empty
lastFundingDate	?filter[lastFundingDate][gt]=2020-01-01	eq, not_eq, gt, lt, empty, not_empty
foundationYear	?filter[foundationYear][gt]=1999	eq, not_eq, gt, lt, empty, not_empty
industry	?filter[industry][like]=tech	eq, not_eq, like, not_like,empty, not_empty
employeeRange	?filter[employeeRange][like]=tech	eq, not_eq, like, not_like,empty, not_empty
customFieldValues.{groupId}.Text	?filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Text][like]=team player	eq, not_eq, like, not_like,empty, not_empty
customFieldValues.{groupId}.Date	?filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Date][gt]=2020-01-01	eq, not_eq, gt, lt, empty, not_empty
customFieldValues.{groupId}.Number	?filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Number][lt]=200	eq, not_eq, gt, lt, empty, not_empty
customFieldValues.{groupId}.Status	?filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Status][in]=In Progress	in, not_in, empty, not_empty
customFieldValues.{groupId}.Tags	?filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Tags][in]=B2B&filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Tags][in]=B2C	all, in, not_in, empty, not_empty
customFieldValues.{groupId}.Relationships	?filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Relationships][in][id]=per_a858d1bd-19d3-486d-87a4-c3b13d5b9a99	all, in, not_in, empty, not_empty
customFieldValues.{groupId}.Assign	?filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Assign][in][email]=[e-mail]&filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Assign][in][id]=usr_d24b4748-8a5f-4a46-89fe-f19cff553a22	all, in, not_in, empty, not_empty
customFieldValues.{groupId}.Deals	?filter[customFieldValues.grp_c5993dec-0375-407e-9e0a-a310d39f65bd.Deals][in][id]=obj_5ef2bef1-5234-4e09-bc15-f830697604b8	all, in, not_in, empty, not_empty

Filterable fields for objects

These fields apply to objects of every type, such as deals. Custom fields are named without a group ID, since an object belongs to a single group.

Field	Usage	Supported operators
name	?filter[name][like]=Project Alpha	eq, not_eq, like, not_like,empty, not_empty
people	?filter[people][in][id]=per_a858d1bd-19d3-486d-87a4-c3b13d5b9a99	all, in, not_in, empty, not_empty
companies	?filter[companies][in][id]=com_c5993dec-0375-407e-9e0a-a310d39f65bd	all, in, not_in, empty, not_empty
createdAt (day precision)	?filter[createdAt][gt]=2020-01-01	eq, not_eq, gt, lt, empty, not_empty
createdBy	?filter[createdBy][in][email]=[e-mail]&filter[createdBy][in][id]=usr_c5993dec-0375-407e-9e0a-a310d39f65bd	in, not_in, empty, not_empty
customFieldValues.Text	?filter[customFieldValues.Text][like]=team player	eq, not_eq, like, not_like,empty, not_empty
customFieldValues.Date	?filter[customFieldValues.Date][gt]=2020-01-01	eq, not_eq, gt, lt, empty, not_empty
customFieldValues.Number	?filter[customFieldValues.Number][lt]=200	eq, not_eq, gt, lt, empty, not_empty
customFieldValues.Status	?filter[customFieldValues.Status][in]=In Progress	in, not_in, empty, not_empty
customFieldValues.Tags	?filter[customFieldValues.Tags][in]=B2B&filter[customFieldValues.Tags][in]=B2C	all, in, not_in, empty, not_empty
customFieldValues.Assign	?filter[customFieldValues.Assign][in][email]=[e-mail]&filter[customFieldValues.Assign][in][id]=usr_d24b4748-8a5f-4a46-89fe-f19cff553a22	all, in, not_in, empty, not_empty

Unlike people and companies, objects cannot be filtered on relationship (contactField) custom fields, and object types have no object (objectField) custom fields. To find the objects linked to a person or a company, filter on people or companies. To find the people or companies linked to an object, filter people or companies on the object type field, such as customFieldValues.{groupId}.Deals above.

Filterable fields for tasks

Field	Usage	Supported operators
dueAt	?filter[dueAt][gt]=2025-01-01	eq, not_eq, gt, lt
createdAt	?filter[createdAt][gt]=2025-01-01	gt, lt
assigneeUserId	?filter[assigneeUserId][in]=usr_79b6ed73-9939-4118-ba65-7f8cdf401052	in, not_in
entity	?filter[entity][in]=per_f3855422-6740-4e6a-aa5e-449ac77047d0	in, not_in
completedAt	?filter[completedAt][empty]	empty, not_empty, gt, lt

Filterable fields for enrichments

Field	Usage	Supported operators
status	?filter[status][in]=pending&filter[status][in]=in_progress	eq, not_eq, in, not_in
createdAt	?filter[createdAt][gt]=2026-09-01	gt, lt
finishedAt	?filter[finishedAt][empty]	empty, not_empty, gt, lt