API filtration

Table of Contents

Filter types

The following filter types are available at the moment.

  • Single
  • Multiple
  • Range
  • By statuses

Different field types support different filtering approaches.

Single

The simplest filter is available. Takes a single string value.

Request example
/api/v4/leads?filter[name]=news
/api/v4/leads?filter[price]=2000

Multiple

An extended variant of the single type. Takes several values and apply ‘or’ operand.

Request example
/api/v4/leads?filter[pipeline_id]=5597036&filter[pipeline_id]=5635013

Range

Allows filtering numeric values by the FROM-TO range.

The filter is available for the following fields:

  • created_at
  • updated_at
  • closed_at
  • closest_task_at
  • next_date
Request example
/api/v4/leads?filter[created_at][from]=1668784000&filter[created_at][to]=1671165900
/api/v4/leads?filter[closed_at][from]=1669825320

By statuses

Allows filtering leads located in the passed pipeline with the passed lead statuses.

The filter takes an array, each array object has 2 mandatory fields: pipeline_id and status_id.

Request example
/api/v4/leads?filter[statuses][0][status_id]=49366085&filter[statuses][0][pipeline_id]=5597036

and to pass more than one status

/api/v4/leads?filter[statuses][0][pipeline_id]=5597036&filter[statuses][0][status_id]=49366085&filter[statuses][1][pipeline_id]=5597036&filter[statuses][1][status_id]=143

Filtering leads

Method

GET /api/v4/leads

Description

This method allows to get a list of leads filtered by the passed filter.

Authorization type

OAuth 2.0 with Access Token. Review our Step-by-step Example.

Limitations

The method is available in correspondence to the user rights.

GET parameters

Parameter Data type Description Is it a multiple filter? Is it a range filter?
query string The string to search by. ❌ ❌
filter[id] int|array Filter by lead ID ✅ ❌
filter[name] string|array Filter by lead name ✅ ❌
filter[price] object Filter by lead sale value ❌ ❌
filter[statuses] array Filter by lead status ID. Takes statuses array of pipeline_id and status_id. ✅ ❌
filter[pipeline_id] int|array Filter by pipeline ID ✅ ❌
filter[created_by] int|array Filter by ID of the user who created the entity ✅ ❌
filter[updated_by] int|array Filter by ID of the user who changed the entity last ✅ ❌
filter[responsible_user_id] int|array Filter by ID of the entity responsible user ✅ ❌
filter[created_at] object Filter by the creation date of the lead ❌ ✅
filter[updated_at] object Filter by the last update date of the lead ❌ ✅
filter[closed_at] object Filter by the lead closing date ❌ ✅
filter[closest_task_at] object Filter leads by the date of the task closest to completion ❌ ✅

Filtering contacts

Method

GET /api/v4/contacts

Description

This method allows to get a list of contacts filtered by the passed filter.

Authorization type

OAuth 2.0 with Access Token. Review our Step-by-step Example.

Limitations

The method is available in correspondence to the user rights.

GET parameters

Parameter Data type Description Is it a multiple filter? Is it a range filter?
query string The string to search by. ❌ ❌
filter[id] int|array Filter by contact ID ✅ ❌
filter[name] string|array Filter by contact name ✅ ❌
filter[created_by] int|array Filter by ID of the user who created the entity ✅ ❌
filter[updated_by] int|array Filter by ID of the user who changed the entity last ✅ ❌
filter[responsible_user_id] int|array Filter by ID of the entity responsible user ✅ ❌
filter[created_at] object Filter by the creation date of the contact ❌ ✅
filter[updated_at] object Filter by the last update date of the contact ❌ ✅
filter[closest_task_at] object Filter contacts by the date of the task closest to completion ❌ ✅

Filtering companies

Method

GET /api/v4/companies

Description

This method allows to get a list of companies filtered by the passed filter.

Authorization type

OAuth 2.0 with Access Token. Review our Step-by-step Example.

Limitations

The method is available in correspondence to the user rights.

GET parameters

Parameter Data type Description Is it a multiple filter? Is it a range filter?
query string The string to search by. ❌ ❌
filter[id] int|array Filter by company ID ✅ ❌
filter[name] string|array Filter by company name ✅ ❌
filter[created_by] int|array Filter by ID of the user who created the entity ✅ ❌
filter[updated_by] int|array Filter by ID of the user who changed the entity last ✅ ❌
filter[responsible_user_id] int|array Filter by ID of the entity responsible user ✅ ❌
filter[created_at] object Filter by the creation date of the company ❌ ✅
filter[updated_at] object Filter by the last update date of the company ❌ ✅
filter[closest_task_at] object Filter companies by the date of the task closest to completion ❌ ✅

Filtering customers

Method

GET /api/v4/customers

Description

This method allows to get a list of customers filtered by the passed filter.

Authorization type

OAuth 2.0 with Access Token. Review our Step-by-step Example.

Limitations

The method is available in correspondence to the user rights.

GET parameters

Parameter Data type Description Is it a multiple filter? Is it a range filter?
filter[id] int|array Filter by customer ID ✅ ❌
filter[name] string|array Filter by customer name ✅ ❌
filter[main_user] string|array Filter by ID of the entity responsible user ✅ ❌
filter[next_date] int|object Filter by the expected next purchase date. ❌ ✅
filter[next_date][from] int The date from which to start the selection. ❌ ✅
filter[next_date][to] int The date to which you want to select. ❌ ✅
filter[date] object Select an element by the date of creation or editing (you need to transfer an array with the parameters type, from, to) ❌ ✅
filter[date][type] string Select an item by creation or editing date. Date type: create or modify. ❌ ❌
filter[date][from] int The date from which to start the selection. The parameter is set in conjunction with the filter[date][type] parameter. ❌ ✅
filter[date][to] int The date to which you want to select. The parameter is set in conjunction with the filter[date][type] parameter. ❌ ✅
filter[created_by] int|array Filter by ID of the user who created the entity ✅ ❌
filter[modified_by] int|array Filter by ID of the user who updated the entity last ✅ ❌
Customers filter request example
/api/v4/customers?filter[next_date][from]=1673384300&filter[next_date][to]=1673384500
/api/v4/customers?filter[date][from]=1671534910&filter[date][to]=1671534920
/api/v4/customers?filter[date][type]=modify&filter[date][from]=1672224620&filter[date][to]=1672224630