Adding a Filter via Pipedrive API
1. Introduction
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.
To add a new filter, use the POST /filters
endpoint and ensure you give values to the following parameters:
Parameter | Explanation/possible values |
| Filter's name displayed in the Pipedrive's UI |
| The condition parameter defines the filter's structure. |
| Specifies the entity where the filter will be applied. One of the following:
|
2. 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).
Each filter can have a maximum of 16 conditions.
3. JSON structure for filters
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".
{
"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 toGET /filters/helpers
endpoint which shows available operators for a certain field. E.g.name
field'sfield_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",
"LIKE '$%'": "starts with",
"NOT LIKE '$%'": "does not start 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 theGET /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"
}
4. Full code 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 authenticate your request and add your own values to the JSON structure.
//All tutorial Node.Js code examples are for reference only and shouldn't be used in production code as is. In production, a new new pipedrive.ApiClient() instance should be initialised separately for each request.
const pipedrive = require('pipedrive');
const defaultClient = new pipedrive.ApiClient();
// Configure authorization by settings api key
// PIPEDRIVE_API_KEY is an environment variable that holds real api key
defaultClient.authentications.api_key.apiKey = process.env.PIPEDRIVE_API_KEY;
async function addFilter() {
try {
console.log('Sending request...');
const api = new pipedrive.FiltersApi(defaultClient);
const conditions = {
glue: 'and',
conditions: [
{
glue: 'and',
conditions: [
{
object: 'deal',
field_id: 12456,
operator: '>',
value: 1000,
extra_value: null
}
]
},
{
glue: 'or',
conditions: [
{
object: 'deal',
field_id: 12464,
operator: '=',
value: 'won',
extra_value: null
}
]
}
]
}
const data = {
name: 'Api Filter',
conditions,
type: 'deals' // deals, org, people, products, activity
}
const response = await api.addFilter(data);
console.log('Filter was added successfully!', response);
} catch (err) {
const errorToLog = err.context?.body || err;
console.log('Adding failed', errorToLog);
}
}
addFilter();