Pipedrive API Documentation

Pipedrive's API Docs

Welcome to Pipedrive's Developer Documentation. Here you'll find comprehensive guides and documentation to help you start working with Pipedrive's API, as well as the Changelog to see any relevant changes regarding the public API.

Adding a Filter

Filters can be created in Pipedrive for Deals, Persons, Organizations, Activities, and Products. To get more acquainted with how the filters work, try creating a filter in the Pipedrive web app, then make first a request to GET /filters to get the ID of the filter, and then a request to GET /filters/{id} to see how the chosen filter's conditions are defined.

In order to add a new filter, you must give values to the following parameters:

Parameter
Explanation/possible values

name

Filter's name displayed in the Pipedrive's UI

conditions

The condition parameter defines the filter's structure. conditions should be added in a JSON format. See how to add conditions.

type

Specifies the entity where the filter will be applied. One of the following:

  • deal
  • person
  • organization
  • product
  • activities

You can also use the POST /filters endpoint in our API Reference to test out the endpoint.

How to add a condition?

conditions must be added as a JSON object. The main conditions object always starts out with a glue parameter which has the value and - this is considered the first level conditioning group. Inside the first level conditioning group, there are two nested second level conditions objects with which you will need to define again the glue parameters. In second level conditioning groups, the values for glue can be and and or (both used only once).

This is how conditions would look like for a filter for seeing all Organizations whose locality contains "Tallinn" and where Organization's name contains "Pipe".

When you copy this JSON, be sure to remove all comments. Otherwise, the structure won't pass the JSON validation.

{ 
   "glue":"and",
   "conditions":[//first level conditioning group
      { 
         "glue":"and",
         "conditions": [//second level conditioning group
            {
                "object": "organization",
                "field_id": "4020",
                "operator": "LIKE '%$%'",
                "value": "Tallinn",
                "extra_value": "locality"
            }
         ]
      },
      { 
         "glue":"or",
         "conditions": [//second level conditioning group
            {
                "object": "organization",
                "field_id": "4002",
                "operator": "LIKE '%$%'",
                "value": "Pipe",
                "extra_value": null
            }
         ]
      }
   ]
}

Inside the second level conditioning groups, you must specify the values for "object", "field_id","operator", "value", "extra_value".

  • "object" is the entity whose fields will be used in the filter (e.g. Organization).
  • "field_id" - to find the needed field's ID, make a request to the specific entity's fields endpoint (e.g. OrganizationFields).
  • "operator" - to understand which operator to use for a certain field you can make a request to GET /filters/helpers endpoint which shows available operators for a certain field. E.g. name field's field_type is varchar, so these are the possible "operator" values for this type of a field:
"varchar": {
    "=": "is",
    "!=": "is not",
    "IS NULL": "is empty",
    "IS NOT NULL": "is not empty",
    "LIKE '%$%'": "contains",
    "NOT LIKE '%$%'": "does not contain",
    "LIKE '$%'": "starts with",
    "NOT LIKE '$%'": "does not start with",
    "LIKE '%$'": "ends with",
    "NOT LIKE '%$'": "does not end with"
}
  • "value" - is the value of specified filter field (e.g. "Tallinn").
  • "extra_value" - is the key of specific field type's subfield (e.g when creating a filter condition by “address” type of a field, the “extra_value” could be “locality” and the “value” would be the value of the desired filter condition e.g. "Tallinn"). You can also see the possible "extra_value"'s by using the GET /filters/helpers endpoint.
"address_field_components": {
    "subpremise": "Apartment/suite no",
    "street_number": "House number",
    "route": "Street/road name",
    "sublocality": "District/sublocality",
    "locality": "City/town/village/locality",
    "admin_area_level_1": "State/county",
    "admin_area_level_2": "Region",
    "country": "Country",
    "postal_code": "ZIP/Postal code",
    "formatted_address": "Full/combined address"
}

Full example

You can use this JSON example to add a new filter. For this request the content_type needs to be application/json. Don't forget to authentication your request and add your own values to the JSON structure.

{
    "name": "",
    "type": "",
    "conditions": {
        "glue": "and",
        "conditions": [{
                "glue": "and",
                "conditions": [{
                    "object": "",
                    "field_id": "",
                    "operator": "",
                    "value": "",
                    "extra_value": ""
                }]
            },
            {
                "glue": "or",
                "conditions": [{
                    "object": "",
                    "field_id": "",
                    "operator": "",
                    "value": "",
                    "extra_value": ""
                }]
            }
        ]
    }
}

Updated about a month ago

Adding a Filter


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.