REST API: Complex contact filters

From Planfix
Jump to: navigation, search

Planfix applies complex filters in the /contact/list method when getting a list of contacts using the REST API. Contact filters are defined using the following parameters:

  • type — numeric identifier of the filter.
  • operator — filter operator, value from list (equal, notequal, gt, lt). Different filters can have different possible operators.
  • value — filter value, depending on filter type can be string, number, or complex object.
  • field — custom field ID, used for filters on custom fields.
{
    "type": 12,
    "operator": "equal",
    "value": {
        "dateType": "otherDate",
        "dateValue": "01-07-2022"
    }
}


A call requesting a list of contacts with multiple filters (using AND logic):

{
  "fields": "name",
  "filters": [{
        "type": 4223,
        "operator": "equal",
        "value": {
"dateType": "otherDate",
"dateValue": "01-12-1990"
}
     },
     {
        "type": 1,
        "operator": "equal",
        "value": "user:5"
     }
  ]
}


Type Name Operators Value format
12 Creation date
  • equal
  • notequal
  • gt
  • lt

Object :

 
"value": {
    "dateType": string,
    "dateValue": string,
    "dateFrom": string,
    "dateTo": string
}

dateType takes the following values:

  • today - today
  • yesterday
  • tomorrow
  • thisWeek
  • lastWeek
  • nextWeek
  • thisMonth
  • lastMonth
  • nextMonth
  • last - last n days, n is passed in dateValue
  • next - next n days, n is passed in dateValue
  • in - in n days, n is passed in dateValue
  • otherDate - exact date, date is passed in dd-mm-yyyy format in dateFrom
  • otherRange - exact range, date is passed in dd-mm-yyyy format in dateFrom and dateTo
  • otherDate_withTime - exact date and time, date passed in dd-mm-yyyy hh:mm format in dateFrom
  • otherRange_withTime - exact range with time, date is passed in dd-mm-yyyy hh:mm format in dateFrom and dateTo

Dates are taken in the time zone of the employee making the call.

Example:

"value": {
    "dateType": "thisWeek"
}
"value": {
    "dateType": "otherRange",
    "dateFrom": "02-07-2022",
    "dateTo": "06-07-2022"
}
"value": {
    "dateType": "otherDate_withTime",
    "dateFrom": "30-06-2022 12:00",
}
38 Last modified date
4223 Date of birth (with year)
4011 Date of birth (without year)
4213 Counterparty in tasks with recent activity
4219 Counterparty without tasks with recent activity
4214 Is participating in tasks with recent activity
4220 Is not participating in tasks with recent activity
4103 Custom Date field
1 Added
  • equal
  • notequal
string - employee/contact/group number with prefix.

Example: "user:1", "contact:5", "group:3"

2 Supervisor
47 Is available to
48 Can be edited by
4108 Custom Contact field
4109 Custom Employee field
4112 Custom Group, Employee, Contact field
4113 Custom Employee List field
4006 Is a company
  • equal
int - 1

boolean - true

4007 Is a contact
4010 With Planfix access
4012 Cannot be participant in tasks
4017 Can be counterparty in tasks
4013 Cannot be a counterparty in tasks
4018 Cannot be a counterparty in tasks
4201 Counterparty with no active tasks
4202 Is not participating in active tasks
4203 Counterparty with active tasks
4204 Is participating in active tasks
4205 Counterparty in overdue tasks
4206 Is participating in overdue tasks
4001 First or last name of contact / Company name
  • equal
  • notequal
string - filter contains / doesn't contain
4002 Position
4003 Phone number
4004 Address
4005 Email
4221 Additional email
4014 Contact first name / Company name
4015 Contact last name
4101 Custom String field
4102 Custom Number field
  • equal
  • notequal
  • gt
  • lt
int
4105 Custom Checkbox field
  • equal
  • notequal
int - 1 / 0

boolean

4106 Custom List field
  • equal
  • notequal
string
4107 Custom Directory field
  • equal
  • notequal
int - entry ID
4114 Custom Directory Entry Set field
  • equal
  • notequal
int - entry ID, semicolon-delimited ;
4111 Custom Set of Values field
  • equal
  • notequal
string - string - value, semicolon-delimited;
4152 Does contain a value in a custom field
  • equal

int - field identifier

4153 Does not contain a value in a custom field
4008 Contact group
  • equal
  • notequal
int - group ID, get using /contact/groups method
4016 Contact template
  • equal
  • notequal
int - template number, get list of contact templates using /contact/templates method
4231 Contact number
  • equal
  • notequal
int - Contact number
93 Value of the data tag entry field

(depending on the field type)

  • equal
  • notequal
  • gt
  • lt
  • have
  • nothave
The value of the data tag field used for filtering and the subfilter field must be passed in the filter structure. Here's an example for filtering a data tag field type String:
{
  "offset": 0,
  "pageSize": 100,
  "filters": [
    {
      "type": 93,
      "operator": "equal",
      "value": "Test value",
      "subfilter": {
        "dataTagId": 6,
        "filter": {
          "type": 3108,
          "field": 20
        }
      }
    }
  ],
  "fields": "id,name,dataTags"
}

where:

  • dataTagId — data tag ID.
  • filter — filter object for this data tag.
  • type — filter type, in this case, a complex data tag filter for a String type field.
  • field — data tag field ID, used for filtering.
4226 Username Telegram
  • equal
  • notequal
string - Username (username, @username, https://t.me/username)
4234 Telegram ID
  • equal
  • notequal
int - Telegram ID
4026 Email (Exact match)
  • equal
  • notequal
string


Go To