REST API: Complex employee filters

From Planfix
Revision as of 13:11, 16 May 2024 by Aliona (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Complex filters in REST API Planfix are used in the "/user/list" method when obtaining a list of employees. The following set of parameters sets employee filters:

  • type — numeric filter identifier.
  • operator — filter operator, one of the list values (equal, notequal, gt, lt). Different filters may have different allowable operators.
  • value — filter value, depending on the filter type. It can be a string, number, or complex object.
  • field — identifier of the custom directory field performed by the filter.

Example of a request to get a list of employees with several filters by a custom field of type "Date" and a custom field of type "Employee" (AND logic is used):


{
  "offset": 0,
  "pageSize": 100,
  "fields": "id,name,description,3,5",
  "filters": [
    {
      "type": 5103,
      "field": 3,
      "operator": "equal",
      "value": {
        "dateType": "otherRange",
        "dateFrom": "15-12-2022",
        "dateTo": "17-12-2022"
      }
    },
    {
      "type": 5109,
      "field": 5,
      "operator": "equal",
      "value": "user:50"
    }
  ]
}


Type Name Operators Format value
9103 Employee field type "Date"
  • equal
  • notequal
  • gt
  • lt

Object :

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

dateType accepts the following values:

  • 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 the format dd-mm-yyyy in dateFrom
  • otherRange - exact period, dates are passed in the format dd-mm-yyyy in dateFrom and dateTo
  • otherDate_withTime - exact date-time, date is passed in the format "dd-mm-yyyy hh:mm" in dateFrom
  • otherRange_withTime - exact period with specified time, dates are passed in the format "dd-mm-yyyy hh:mm" in dateFrom and dateTo

Whether a date is considered in the past depends on the time zone of the employee who made the request.

Examples:

"value": {
    "dateType": "thisWeek"
}
"value": {
    "dateType": "otherRange",
    "dateFrom": "01-12-2022",
    "dateTo": "06-12-2022"
}
"value": {
    "dateType": "otherDate_withTime",
    "dateFrom": "30-12-2022 12:00",
}
9120 Employee's birth date
9108 Employee field type "Contact"
  • equal
  • notequal
string - employee/contact/group number with a prefix.

For example: “user:1”, “contact:5”, “group:3”

9109 Employee field type "Employee"
9110 Employee field Type "Counterparty"
9112 Employee field type "Group, employee, contact"
9113 Employee field type "Employee list"
9006 Employee's full name (search can be performed by part of the full name)
  • equal
  • notequal
string — contains/does not contain filter is applied
9121 Employee's first name
9122 Employee's middle name
9123 Employee's last name
9101 Employee field type "String"
  • equal
  • notequal
  • have
  • nothave
string - equal/not equal/ contains/does not contain filter is applied
9008 Employee number
  • equal
  • notequal
  • gt
  • lt

int

9102 Employee field type "Number"
9105 Employee field type "Checkbox"
  • equal
  • notequal
int — 1/0
boolean
9106 Employee field type "List"
  • equal
  • notequal
string
9107 Employee field type "Directory entry"
  • equal
  • notequal
int — entry identifier
9111 Custom field type "Value set"
  • equal
  • notequal
string - value, for condition by several values — value through; (semicolon)
9115 Employee field type "Task"
  • equal
  • notequal
int — task number
9117 Employee field type "Project"
  • equal
  • notequal
int — project number
9001 Employee group
  • equal
  • notequal
int — group identifier
9002 Employee's phone number
  • equal
  • notequal

string — contains/does not contain filter is applied

9004 Employee's short number
9003 Employee's external email
9005 Employee's position
  • equal
  • notequal
string — position name
9124 Employee's language
  • equal
  • notequal
string — language code, for example: "En"
9125 Username
  • equal
  • notequal
string - Username (username, @username, https://t.me/username)
9126 Telegram ID
  • equal
  • notequal
int - Telegram ID


Go To