Pipedrive Filters API

openapi: 3.2.0
info:
  title: Pipedrive API v1 Activities Filters API
  version: 1.0.0
  description: 'Activities are appointments/tasks/events on a calendar that can be associated with a deal, a lead, a person and an organization. Activities can be of different type (such as call, meeting, lunch or a custom type - see ActivityTypes object) and can be assigned to a particular user. Note that activities can also be created without a specific date/time.

    '
servers:
- url: https://api.pipedrive.com/v1
tags:
- name: Filters
  description: 'Each filter is essentially a set of data validation conditions. A filter of the same kind can be applied when fetching a list of deals, leads, persons, organizations or products in the context of a pipeline. Filters are limited to a maximum of 16 conditions. When applied, only items matching the conditions of the filter are returned. Detailed definitions of filter conditions and additional functionality is not yet available.

    '
paths:
  /filters:
    delete:
      summary: Delete multiple filters in bulk
      description: Marks multiple filters as deleted.
      x-token-cost: 10
      operationId: deleteFilters
      tags:
      - Filters
      security:
      - api_key: []
      - oauth2:
        - deals:full
        - activities:full
        - contacts:full
      parameters:
      - in: query
        name: ids
        required: true
        schema:
          type: string
        description: The comma-separated filter IDs to delete
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: DeleteFiltersResponse
                allOf:
                - title: baseResponse
                  type: object
                  properties:
                    success:
                      type: boolean
                      description: If the response is successful or not
                - type: object
                  properties:
                    data:
                      type: object
                      properties:
                        id:
                          type: array
                          description: The array of the IDs of the deleted filter
                          items:
                            type: integer
              example:
                success: true
                data:
                  id:
                  - 1
                  - 2
                  - 3
    get:
      summary: Get all filters
      description: Returns data about all filters.
      x-token-cost: 20
      operationId: getFilters
      tags:
      - Filters
      security:
      - api_key: []
      - oauth2:
        - deals:read
        - deals:full
        - activities:read
        - activities:full
        - contacts:read
        - contacts:full
      parameters:
      - in: query
        name: type
        schema:
          type: string
          enum:
          - deals
          - leads
          - org
          - people
          - products
          - activity
          - projects
        description: The types of filters to fetch
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: GetFiltersResponse
                allOf:
                - title: baseResponse
                  type: object
                  properties:
                    success:
                      type: boolean
                      description: If the response is successful or not
                - properties:
                    data:
                      type: array
                      description: The array of filters
                      items:
                        description: The filter object
                        type: object
                        properties:
                          id:
                            type: integer
                            description: The ID of the filter
                          name:
                            type: string
                            description: The name of the filter
                          filter_code:
                            type:
                            - string
                            - 'null'
                            description: The system code of the filter
                          is_editable:
                            type: boolean
                            description: Whether the filter can be edited by the requesting user
                          active_flag:
                            type: boolean
                            description: The active flag of the filter
                          type:
                            type: string
                            enum:
                            - deals
                            - leads
                            - org
                            - people
                            - products
                            - activity
                            - projects
                          temporary_flag:
                            type:
                            - boolean
                            - 'null'
                            description: Whether the filter is temporary
                          user_id:
                            type: integer
                            description: The owner of the filter
                          add_time:
                            type: string
                            description: The date and time when the filter was added
                          update_time:
                            type:
                            - string
                            - 'null'
                            description: The date and time when the filter was updated
                          visible_to:
                            allOf:
                            - type: string
                              enum:
                              - '1'
                              - '3'
                              - '5'
                              - '7'
                            description: The visibility group ID of who can see the filter
                          last_used_time:
                            type:
                            - string
                            - 'null'
                            description: The date and time when the filter was last used
                          custom_view_id:
                            type:
                            - integer
                            - 'null'
                            description: The custom view ID linked to the filter
              example:
                success: true
                data:
                - id: 1
                  name: All open deals
                  filter_code: null
                  is_editable: true
                  active_flag: true
                  type: deals
                  temporary_flag: null
                  user_id: 927097
                  add_time: '2019-10-15 11:01:53'
                  update_time: '2019-10-15 11:01:53'
                  visible_to: '7'
                  last_used_time: null
                  custom_view_id: null
    post:
      summary: Add a new filter
      description: Adds a new filter, returns the ID upon success. Note that in the conditions JSON object only one first-level condition group is supported, and it must be glued with 'AND', and only two second level condition groups are supported of which one must be glued with 'AND' and the second with 'OR'. Other combinations do not work (yet) but the syntax supports introducing them in future. For more information, see the tutorial for <a href="https://pipedrive.readme.io/docs/adding-a-filter" target="_blank" rel="noopener noreferrer">adding a filter</a>.
      x-token-cost: 10
      operationId: addFilter
      tags:
      - Filters
      security:
      - api_key: []
      - oauth2:
        - deals:full
        - activities:full
        - contacts:full
      parameters:
      - in: query
        name: include_field_code
        required: false
        schema:
          type: boolean
        description: If set to `true`, each condition in the response includes a `field_code` field identifying the field by its code name
      requestBody:
        content:
          application/json:
            schema:
              title: addFilterRequest
              type: object
              required:
              - name
              - conditions
              - type
              properties:
                name:
                  type: string
                  description: The name of the filter
                conditions:
                  type: object
                  description: 'The conditions of the filter as a JSON object. Please note that a maximum of 16 conditions is allowed per filter and `date` values must be supplied in the `YYYY-MM-DD` format. It requires a minimum structure as follows: `{"glue":"and","conditions":[{"glue":"and","conditions": [CONDITION_OBJECTS]},{"glue":"or","conditions":[CONDITION_OBJECTS]}]}`. Replace `CONDITION_OBJECTS` with JSON objects of the following structure: `{"object":"","field_id":"", "operator":"","value":"", "extra_value":""}` or leave the array empty. Depending on the object type you should use another API endpoint to get `field_id`. There are five types of objects you can choose from: `"person"`, `"deal"`, `"organization"`, `"product"`, `"activity"` and you can use these types of operators depending on what type of a field you have: `"IS NOT NULL"`, `"IS NULL"`, `"<="`, `">="`, `"<"`, `">"`, `"!="`, `"="`, `"LIKE ''$%''"`, `"LIKE ''%$%''"`, `"NOT LIKE ''$%''"`. To get a better understanding of how filters work try creating them directly from the Pipedrive application.'
                type:
                  type: string
                  allOf:
                  - type: string
                    enum:
                    - deals
                    - leads
                    - org
                    - people
                    - products
                    - activity
                    - projects
                  description: The type of filter to create
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: AddFiltersResponse
                allOf:
                - title: baseResponse
                  type: object
                  properties:
                    success:
                      type: boolean
                      description: If the response is successful or not
                - type: object
                  properties:
                    data:
                      type: object
                      title: Filter
                      properties:
                        id:
                          type: integer
                          description: The ID of the filter
                        name:
                          type: string
                          description: The name of the filter
                        filter_code:
                          type:
                          - string
                          - 'null'
                          description: The system code of the filter
                        is_editable:
                          type: boolean
                          description: Whether the filter can be edited by the requesting user
                        active_flag:
                          type: boolean
                          description: The activity flag of the filter
                        type:
                          type: string
                          enum:
                          - deals
                          - leads
                          - org
                          - people
                          - products
                          - activity
                          - projects
                        temporary_flag:
                          type:
                          - boolean
                          - 'null'
                          description: Whether the filter is temporary
                        user_id:
                          type: integer
                          description: The user ID of the filter owner
                        add_time:
                          type: string
                          description: The date and time when the filter was added
                        update_time:
                          type:
                          - string
                          - 'null'
                          description: The date and time when the filter was last updated
                        visible_to:
                          allOf:
                          - type: string
                            enum:
                            - '1'
                            - '3'
                            - '5'
                            - '7'
                          description: The visibility group ID of the filter
                        last_used_time:
                          type:
                          - string
                          - 'null'
                          description: The date and time when the filter was last used
                        custom_view_id:
                          type:
                          - integer
                          - 'null'
                          description: The custom view ID linked to the filter
                        conditions:
                          type: object
                          description: The conditions object of a filter
                          properties:
                            glue:
                              type: string
                              enum:
                              - and
                              description: The top-level glue is always "and"
                            conditions:
                              type: array
                              description: The condition groups
                              items:
                                type: object
                                description: A group of conditions joined by a logical operator
                                properties:
                                  glue:
                                    type: string
                                    enum:
                                    - and
                                    - or
                                    description: The logical operator joining conditions within this group
                                  conditions:
                                    type: array
                                    description: The individual conditions in this group
                                    items:
                                      type: object
                                      description: A single filter condition
                                      properties:
                                        object:
                                          type: string
                                          description: The type of entity the condition applies to (e.g. "deal", "person")
                                        field_id:
                                          type: string
                                          description: The ID of the field
                                        operator:
                                          type: string
                                          description: The operator used in the condition (e.g. "=", "IS NOT NULL")
                                        value:
                                          type:
                                          - string
                                          - 'null'
                                          description: The value of the condition
                                        extra_value:
                                          type:
                                          - string
                                          - 'null'
                                          description: An extra value for conditions that require two values
                                        json_value_flag:
                                          type: boolean
                                          description: Whether the value is JSON-encoded
                                        field_code:
                                          type:
                                          - string
                                          - 'null'
                                          description: The code name of the field. Present when `include_field_code=true` is passed as a query parameter; `null` if the field code cannot be resolved
              example:
                success: true
                data:
                  id: 1
                  name: Deal title is 'my title'
                  filter_code: null
                  is_editable: true
                  active_flag: true
                  type: deals
                  temporary_flag: false
                  user_id: 1
                  add_time: '2018-01-27 08:49:26'
                  update_time: '2018-01-27 08:49:26'
                  visible_to: '1'
                  last_used_time: null
                  custom_view_id: null
                  conditions:
                    glue: and
                    conditions:
                    - glue: and
                      conditions:
                      - object: deal
                        field_id: '123141'
                        operator: '='
                        value: my title
                        extra_value: null
                        json_value_flag: false
                        field_code: title
                    - glue: or
                      conditions: []
  /filters/helpers:
    get:
      summary: Get all filter helpers
      description: Returns all supported filter helpers. It helps to know what conditions and helpers are available when you want to <a href="/docs/api/v1/Filters#addFilter">add</a> or <a href="/docs/api/v1/Filters#updateFilter">update</a> filters. For more information, see the tutorial for <a href="https://pipedrive.readme.io/docs/adding-a-filter" target="_blank" rel="noopener noreferrer">adding a filter</a>.
      x-token-cost: 20
      operationId: getFilterHelpers
      tags:
      - Filters
      security:
      - api_key: []
      - oauth2:
        - deals:read
        - deals:full
        - activities:read
        - activities:full
        - contacts:read
        - contacts:full
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: GetFilterHelpersResponse
                type: object
                description: The rules for filters
              example:
                success: true
                data:
                  operators:
                    int:
                      '=': is
                      '!=': is not
                      '>': is more than
                      <: is less than
                      '>=': is more or equal to
                      <=: is less or equal to
                      IS NULL: is empty
                      IS NOT NULL: is not empty
                    double:
                      '=': is
                      '!=': is not
                      '>': is more than
                      <: is less than
                      '>=': is more or equal to
                      <=: is less or equal to
                      IS NULL: is empty
                      IS NOT NULL: is not empty
                    monetary:
                      '=': is
                      '!=': is not
                      '>': is more than
                      <: is less than
                      '>=': is more or equal to
                      <=: is less or equal to
                      IS NULL: is empty
                      IS NOT NULL: is not empty
                    time:
                      '=': is
                      '!=': is not
                      <: is before
                      '>': is after
                      '>=': is exactly or after than
                      <=: is exactly or before than
                      IS NULL: is empty
                      IS NOT NULL: is not empty
                    date:
                      '=': is
                      '!=': is not
                      '>': is later than
                      <: is earlier than
                      '>=': is exactly or later than
                      <=: is exactly or earlier than
                      IS NULL: is empty
                      IS NOT NULL: is not empty
                    entered_stage:
                      '=': is
                      '!=': is not
                      '>': is later than
                      <: is earlier than
                      '>=': is exactly or later than
                      <=: is exactly or earlier than
                    timerange:
                      '=': starts at
                      '!=': does not start at
                      ends_at: ends at
                      does_not_end_at: does not end at
                      <: starts before
                      <=: starts exactly on or before
                      ends_before: ends before
                      ends_e_before: ends exactly on or before
                      '>': starts after
                      ends_after: ends after
                      '>=': starts exactly or after
                      ends_e_after: ends exactly or after
                      includes: does include
                      IS NULL: is empty
                      IS NOT NULL: is not empty
                    daterange:
                      '=': starts at
                      '!=': does not start at
                      ends_at: ends at
                      does_not_end_at: does not end at
                      <: starts before
                      <=: starts exactly on or before
                      ends_before: ends before
                      ends_e_before: ends exactly on or before
                      '>': starts after
                      ends_after: ends after
                      '>=': starts exactly or after
                      ends_e_after: ends exactly or after
                      includes: does include
                      IS NULL: is empty
                      IS NOT NULL: is not empty
                    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
                    stage:
                      '=': is
                      '!=': is not
                      has_been: has been
                    title:
                      '=': is
                      LIKE '$%': starts with
                      LIKE '%$%': contains
                      NOT LIKE '$%': does not start with
                    set:
                      '=': is
                      '!=': is not
                      contains: contains
                      not_contains: does not contain
                      IS NULL: is empty
                      IS NOT NULL: is not empty
                    enum:
                    - '=': is
                    - '!=': is not
                    - IS NULL: is empty
                    - IS NOT NULL: is not empty
                    deal:
                      '=': is
                      '!=': is not
                      IS NULL: is empty
                      IS NOT NULL: is not empty
                    product:
                      '=': is
                      '!=': is not
                      IS NULL: is empty
                      IS NOT NULL: is not empty
                    user:
                      '=': is
                      '!=': is not
                      IS NULL: is empty
                      IS NOT NULL: is not empty
                      belongs_to_team: belongs to team
                    status:
                      '=': is
                      '!=': is not
                    visible_to:
                      '=': is
                      '!=': is not
                    currency:
                      '=': is
                      '!=': is not
                    pipeline:
                      '=': is
                      '!=': is not
                    person:
                      '=': is
                      '!=': is not
                      IS NULL: is empty
                      IS NOT NULL: is not empty
                    organization:
                      '=': is
                      '!=': is not
                      IS NULL: is empty
                      IS NOT NULL: is not empty
                  deprecated_operators:
                    NOT LIKE '%$%': does not contain
                    LIKE '%$': ends with
                    NOT LIKE '%$': does not end with
                  relative_dates:
                    Relative date intervals:
                      last_quarter: last quarter
                      this_quarter: this quarter
                      last_month: last month
                      this_month: this month
                      last_week: last week
                      this_week: this week
                      next_week: next week
                      next_month: next month
                    Relative dates:
                      6_months_ago: 6 months ago
                      5_months_ago: 5 months ago
                      4_months_ago: 4 months ago
                      3_months_ago: 3 months ago
                      2_months_ago: 2 months ago
                      1_months_ago: 1 month ago
                      3_weeks_ago: 3 weeks ago
                      2_weeks_ago: 2 weeks ago
                      1_week_ago: 1 week ago
                      yesterday: yesterday
                      before_today: before today
                      today: today
                      now: now
                      later_or_today: today or later
                      before_tomorrow: before tomorrow
                      tomorrow: tomorrow
                      later_or_tomorrow: tomorrow or later
                      in_1_week: in 1 week
                      in_2_weeks: in 2 weeks
                      in_3_weeks: in 3 weeks
                      in_1_month: in 1 month
                      in_2_months: in 2 months
                      in_3_months: in 3 months
                      in_4_months: in 4 months
                      in_5_months: in 5 months
                      in_6_months: in 6 months
                    Deal specific:
                      rotten_time: Rotten time
                  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
  /filters/{id}:
    delete:
      summary: Delete a filter
      description: Marks a filter as deleted.
      x-token-cost: 6
      operationId: deleteFilter
      tags:
      - Filters
      security:
      - api_key: []
      - oauth2:
        - deals:full
        - activities:full
        - contacts:full
      parameters:
      - in: path
        name: id
        description: The ID of the filter
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: DeleteFilterResponse
                allOf:
                - title: baseResponse
                  type: object
                  properties:
                    success:
                      type: boolean
                      description: If the response is successful or not
                - type: object
                  properties:
                    data:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The ID of the deleted filter
              example:
                success: true
                data:
                  id: 1
    get:
      summary: Get one filter
      description: Returns data about a specific filter. Note that this also returns the condition lines of the filter.
      x-token-cost: 2
      operationId: getFilter
      tags:
      - Filters
      security:
      - api_key: []
      - oauth2:
        - deals:read
        - deals:full
        - activities:read
        - activities:full
        - contacts:read
        - contacts:full
      parameters:
      - in: path
        name: id
        description: The ID of the filter
        required: true
        schema:
          type: integer
      - in: query
        name: include_field_code
        required: false
        schema:
          type: boolean
        description: If set to `true`, each condition in the response includes a `field_code` field identifying the field by its code name
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: GetFiltersResponse
                allOf:
                - title: baseResponse
                  type: object
                  properties:
                    success:
                      type: boolean
                      description: If the response is successful or not
                - type: object
                  properties:
                    data:
                      description: The filter object including conditions
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The ID of the filter
                        name:
                          type: string
                          description: The name of the filter
                        filter_code:
                          type:
                          - string
                          - 'null'
                          description: The system code of the filter
                        is_editable:
                          type: boolean
                          description: Whether the filter can be edited by the requesting user
                        active_flag:
                          type: boolean
                          description: The active flag of the filter
                        type:
                          type: string
                          enum:
                          - deals
                          - leads
                          - org
                          - people
                          - products
                          - activity
                          - projects
                        temporary_flag:
                          type:
                          - boolean
                          - 'null'
                          description: Whether the filter is temporary
                        user_id:
                          type: integer
                          description: The owner of the filter
                        add_time:
                          type: string
                          description: The date and time when the filter was added
                        update_time:
                          type:
                          - string
                          - 'null'
                          description: The date and time when the filter was updated
                        visible_to:
                          allOf:
                          - type: string
                            enum:
                            - '1'
                            - '3'
                            - '5'
                            - '7'
                          description: The visibility group ID of who can see the filter
                        last_used_time:
                          type:
                          - string
                     

# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pipedrive/refs/heads/main/openapi/pipedrive-filters-api-openapi.yml