Get employees grid
Returns a paginated, filterable, and sortable grid of all employees in the workspace.
What are Employees? Employees are internal team members from your own company. Each employee can have:
- A user account with login access (if
canLoginis true) - Team assignments for organizational structure
- Employment details (entry/exit dates, employment mode, tax class)
- Personal information (name, email, phone, address, birth date)
- Professional details (position, title, degree)
What is returned:
- Employee identification (ID, name)
- Contact information (email, phone, position, title, degree)
- Complete address details (street, city, ZIP, country, house number)
- Employment information (employment mode, entry date, exit date, income tax class)
- Status information (isActive, canLogin, roleId)
- Team assignments (teamIds array)
- Personal details (birth date, avatar)
- Timestamps (createdAt)
Filtering and search:
- Quick search across name, email, phone, position, and address fields
- Advanced filtering by active status, employment mode, position, role, teams, and many other fields
- Sorting by any sortable field (default: firstName ascending)
- Server-side pagination for large employee lists
Note: This endpoint requires the Employees.manage permission. The employees grid is separate from the contacts grid, which combines employees and organization members.
/employees/gridAuthorizationOAuth2 access token · headerrequiredapi:readAuthorizationBearer token (JWT) · headerrequiredpagenumberPage number (1-based)
pageSizenumberNumber of items per page
viewIdstringView identifier for saved grid configurations
quickSearchstringQuick search text. Searches across: firstName, lastName, email, phone, position, addressStreet, addressZip, addressCity, addressCountry, addressHouseNumber
filtersstringJSON string containing filter configuration.
Available Fields:
- id (string): Employee ID
- firstName (string): First name
- lastName (string): Last name
- email (string): Email address
- phone (string): Phone number
- position (string): Job position
- title (string): Title (e.g., Dr., Prof.)
- degree (string): Academic degree
- addressStreet (string): Street address
- addressZip (string): ZIP/Postal code
- addressCity (string): City
- addressCountry (string): Country
- addressHouseNumber (string): House number
- employmentMode (string): Employment mode (FullTime, Contract, Temporary, Freelance)
- entryDate (date): Entry date
- exitDate (date): Exit date
- incomeTaxClass (string): Income tax class
- birthDate (date): Birth date
- avatarId (string): Avatar file ID
- isActive (boolean): Whether employee is active (no exitDate or exitDate > today)
- canLogin (boolean): Whether employee can login to the system
- roleId (string): User role ID
- teamIds (array): Team IDs (array)
- createdAt (date): Creation timestamp
Filter Structure:
[
{
"type": "string|number|date|set|boolean|array|task_status|task_type",
"fieldName": "field_name",
"value": {
"comparison": "comparison_type",
"value": "filter_value"
}
}
]
Group Filters (AND/OR Combinations):
[
{
"type": "group",
"fieldName": "group0.18807479823070028",
"value": {
"type": "or",
"filters": [
{
"type": "string",
"fieldName": "fileName",
"value": {
"comparison": "contain",
"value": "aa"
}
},
{
"type": "number",
"fieldName": "rowCount",
"value": {
"comparison": ">=",
"value": 33
}
}
]
}
}
]
Available Comparison Operators:
- id (string): Employee ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty
- firstName (string): First name (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty
- lastName (string): Last name (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty
- email (string): Email address (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty
- phone (string): Phone number (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty
- position (string): Job position (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty
- title (string): Title (e.g., Dr., Prof.) (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty
- degree (string): Academic degree (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty
- addressStreet (string): Street address (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty
- addressZip (string): ZIP/Postal code (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty
- addressCity (string): City (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty
- addressCountry (string): Country (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty
- addressHouseNumber (string): House number (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty
- employmentMode (string): Employment mode (FullTime, Contract, Temporary, Freelance) (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty
- entryDate (date): Entry date (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty
- exitDate (date): Exit date (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty
- incomeTaxClass (string): Income tax class (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty
- birthDate (date): Birth date (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty
- avatarId (string): Avatar file ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty
- isActive (boolean): Whether employee is active (no exitDate or exitDate > today) (boolean filter). Available comparisons: equal, not_equal
- canLogin (boolean): Whether employee can login to the system (boolean filter). Available comparisons: equal, not_equal
- roleId (string): User role ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty
- teamIds (array): Team IDs (array) (array filter). Available comparisons: in, not_in, is_empty, is_not_empty
- createdAt (date): Creation timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty
Note: Use quickSearch parameter for simple text search instead of adding it to filters.
sortstringJSON array of sort objects.
Sortable Fields:
- id: Employee ID
- firstName: First name
- lastName: Last name
- name: Full name (firstName + lastName, virtual field)
- position: Job position
- addressCity: City
- addressCountry: Country
- employmentMode: Employment mode (FullTime, Contract, Temporary, Freelance)
- entryDate: Entry date
- exitDate: Exit date
- birthDate: Birth date
- isActive: Whether employee is active (no exitDate or exitDate > today)
- canLogin: Whether employee can login to the system
- createdAt: Creation timestamp
Sort Structure:
[
{
"field": "field_name",
"direction": "asc|desc"
}
]
Default Sort: firstName (asc)
fieldsToReturnstring[]Comma-separated list of field names to include in response items. If not provided, all fields are returned.
Available Fields: id, firstName, lastName, name, email, phone, position, title, degree, addressStreet, addressZip, addressCity, addressCountry, addressHouseNumber, employmentMode, entryDate, exitDate, incomeTaxClass, birthDate, avatarId, isActive, canLogin, roleId, teamIds, createdAt
Successfully retrieved employees grid
Unauthorized - Invalid or missing authentication token
Forbidden - Insufficient API scopes or permissions