API Filtration

Common information

API filtration functionality is currenly in the alpha version state, and is available to a limited list of accounts.
amoCRM Partners can send a request to access the closed alpha testing to the technical support. Each request is reviewed individually.
After successful testing, we’ll begin gradually enabling the functionality for amoCRM clients.
The functionality is available for the following lists: leads,
contacts, companies and customers.

Table of Contents

Lead list filtering

Method

GET /api/v4/leads

Description

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

Limitations

Method is available in correspondence to the user rights.

GET parameters

Parameter Data type Description Is a multiple filter? Is a range filter?
filter object Filter
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
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 by the date of the task with the closest deadline
filter[custom_fields_values] object Filter by values of custom fields Depends on the field type Depends on the field type
query string The string to search by. The parameter will be deprecated soon

Contact list filtering

Method

GET /api/v4/contacts

Description

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

Limitations

Method is available in correspondence to the user rights.

GET parameters

Parameter Data type Description Is a multiple filter? Is a range filter?
filter object Filter
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 by the date of the task with the closest deadline
filter[custom_fields_values] object Filter by values of custom fields Depends on the field type Depends on the field type
query string The string to search by. The parameter will be deprecated soon

Company list filtering

Method

GET /api/v4/companies

Description

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

Limitations

Method is available in correspondence to the user rights.

GET parameters

Parameter Data type Description Is a multiple filter? Is a range filter?
filter object Filter
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 by the date of the task with the closest deadline
filter[custom_fields_values] object Filter by values of custom fields Depends on the field type Depends on the field type
query string The string to search by. The parameter will be deprecated soon

Customer list filtering

Method

GET /api/v4/customers

Description

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

Limitations

Method is available in correspondence to the user rights.

GET parameters

Parameter Data type Description Is a multiple filter? Is a range filter?
filter object Filter
filter[id] int|array Filter by customer ID
filter[name] string|array Filter by customer name
filter[next_price] string|array Filter by the expected next purchase price
filter[next_date] object Filter by the expected next purchase date
filter[status_id] int|array Filter by customer status 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 customer
filter[updated_at] object Filter by the last update date of the customer
filter[closest_task_at] object Filter by the date of the task with the closest deadline
filter[custom_fields_values] object Filter by values of custom fields Depends on the field type Depends on the field type

Filter types

The following filter types are available at the moment.

  • Single
  • Multiple
  • Range
  • By statuses (leads only)
  • By custom fields

Will review examples of each type below.

Single

The simplest filter available. Takes a single string value.

Request example

        
/api/v4/leads/?filter[name]=Lead
        
    

Multiple

An extended variant of the single type. Takes several string values.

Request example

        
/api/v4/leads/?filter[pipeline_id][0]=15314&filter[pipeline_id][0]=21856
        
    

Range

Allows filtering numeric values by the FROM-TO range.

If the filter is set for fields containing timestamp values, the timestamp values should be passed into the filter.

The filter is available for the following fields:

  • price
  • next_price
  • next_date
  • created_at
  • updated_at
  • closed_at
  • closest_task_at
  • FIelds of the date, date_time, numeric types

Request example

        
/api/v4/leads/?filter[updated_at][from]=1575296400&filter[updated_at][to]=1589540009
        
    

By statuses

Filter that allows filtering by leads located in 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][pipeline_id]={pipeline_id}&filter[statuses][0][status_id]={status_id}
        
    

By custom fields

Filter that allows filtering leads by values of multiple custom fields.

Different field types require different values in the filter.

  • For the numeric, text, url, textarea, streetaddress type fields, the value of the field is passed into the filter
  • For the select, multiselect, radiobutton type fields, the ID of the enum value is passed into the filter
  • For the checkbox type field, 1 or 0 is passed into the filter

Different field types support different filtering approaches.

Fields that support range filter:

  • date
  • date_time
  • numeric

Fields that support multiple filter:

  • numeric
  • text
  • url
  • textarea
  • streetaddress
  • select
  • multiselect
  • radiobutton

Request example

        
/api/v4/lead?filter[custom_fields_values][{field_id}][]={value}&filter[custom_fields_values][{field_id}][]={value2}
/api/v4/lead?filter[custom_fields_values][{field_id}][]={enum_id}&filter[custom_fields_values][{field_id}][]={enum_id2}
/api/v4/lead?filter[custom_fields_values][{field_id}][from]={date_from}&filter[custom_fields_values][{field_id}][to]={date_to}