How do you get a list of employees via the API?

GET /v1/employees returns a page of employees. If no query parameters are provided, the API applies the defaults: page = 0 and size = 50.

Endpoint

Parameter	Value
Method	GET
Path	`/api/v1/employees`
Base URL	`https://smartway.pro`
Auth	Bearer token
Required scope	`employees.read`

Purpose

This endpoint is used to retrieve a paginated list of employees within the company from the Bearer token.

The endpoint supports pagination, full-name search, and filters by department and job title.

Prerequisites

The client must send a valid Bearer token.

The token must contain company context.

The token must contain the employees.read scope.

idCompany is not sent by the external client. The API determines companyId only from the Bearer token.

Text query parameters support UTF-8 and must be sent as a standard URL-encoded query string.

Request

Query parameters

Parameter	Type	Required	Description
`page`	int32	no	Page number. Default value: `0`.
`size`	int32	no	Page size. Default value: `50`.
`q`	string	no	Partial-match search by full name. Search by email is not supported.
`department`	string	no	Department filter.
`jobTitle`	string	no	Job title filter.

curl example

Call without parameters

curl -X GET 'https://smartway.pro/api/v1/employees' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json'

Call with parameters

curl -X GET 'https://smartway.pro/api/v1/employees?page=0&size=20&q=Ivan' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json'

Call with multiple UTF-8 parameters

curl -G 'https://smartway.pro/api/v1/employees' \
  --data-urlencode 'page=0' \
  --data-urlencode 'size=20' \
  --data-urlencode 'q=Ivan' \
  --data-urlencode 'department=Управління' \
  --data-urlencode 'jobTitle=Manager' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json'

Response

Successful response: 200 OK. Returns EmployeeListResponse.

{
  "data": [
    {
      "employeeId": 4329,
      "candidateId": 10602,
      "email": "employee@example.com",
      "fullName": "Name Surname",
      "name": "Name",
      "surname": "Surname",
      "gender": "Female",
      "department": "КЛ",
      "departments": [
        "КЛ"
      ],
      "jobTitle": "Manager",
      "jobTitles": [
        "Manager"
      ],
      "phone": "+380000000000",
      "active": true,
      "manager": true
    }
  ],
  "meta": {
    "page": 0,
    "size": 50,
    "totalElements": 385,
    "totalPages": 8,
    "hasNext": true
  }
}

Response fields

EmployeeListResponse

Field	Type	Description
`data`	Employee[]	List of employees on the current page.
`meta`	object	Pagination metadata.

Employee

Field	Type	Description
`employeeId`	int64	Employee ID.
`candidateId`	int64	Linked candidate ID.
`email`	string	Employee email.
`fullName`	string	Full name generated by the server from `name + surname`.
`name`	string	First name.
`surname`	string	Surname.
`gender`	string	Gender.
`department`	string	Primary department.
`departments`	string[]	Set of departments.
`jobTitle`	string	Primary job title.
`jobTitles`	string[]	Set of job titles.
`phone`	string	Phone number.
`active`	boolean	Active flag.
`manager`	boolean	Department manager role flag. `true` means the employee has this role on the authorisation server.

Pagination meta

Field	Type	Description
`page`	int32	Current page number. Numbering is 0-based.
`size`	int32	Page size.
`totalElements`	int64	Total number of matched elements.
`totalPages`	int32	Total number of pages.
`hasNext`	boolean	Indicates whether there is a next page.

Business logic

All query parameters are optional.

If the endpoint is called without parameters, the API returns the first page of employees: page = 0, size = 50.

The page parameter is 0-based: page = 0 is the first page, page = 1 is the second page.

The API determines companyId only from the Bearer token.

idCompany is not sent by the external client.

q searches by full name using a partial match.

Search by email is not supported.

q, department, and jobTitle support UTF-8.

Parameters can be combined. The combined set of parameters is applied with AND logic.

Access requires the employees.read scope.

Edge cases

Scenario	API behaviour
No query parameters are provided	The API applies `page = 0` and `size = 50`.
`page = 0`	The first page is returned.
`page = 1`	The second page is returned.
`q` is provided	The API searches by full name using a partial match.
Email is passed in `q`	Search by email is not supported.
`department` and `jobTitle` are provided	Filters are combined with AND logic.
A UTF-8 value is provided, for example `department=Управління`	The value is valid if sent as a URL-encoded query string.
Token has no company context	The API returns `403 Forbidden`.

Errors

Error responses

HTTP status	When it occurs
`400 Bad Request`	Query parameters are invalid.
`401 Unauthorized`	Bearer token is missing or invalid.
`403 Forbidden`	Insufficient permissions or token without company context.
`500 Internal Server Error`	Unexpected API error.
`503 Service Unavailable`	Internal server integration failure.

Usage

Without query parameters.

Get the next page with page.

Change the page size with size.

Search for an employee by full name with q.

Filter employees by department or jobTitle.

Combine search and filters to narrow the result set.

Common mistakes

Typical integration mistakes

Common mistake	Correct approach
Assuming `page = 1` is the first page	Use `page = 0` for the first page.
Searching for an employee by email using `q`	`q` supports full-name search, not email search.
Sending `idCompany` in the query string	Do not send `idCompany`; `companyId` is taken from the Bearer token.
Not encoding UTF-8 values in the URL	Send text parameters as a URL-encoded query string.
Using a token without `employees.read`	This endpoint requires the `employees.read` scope.

FAQ

Can the endpoint be called without query parameters?

Yes. The API applies page = 0 and size = 50.

Which page does pagination start from?

It starts from page = 0.

Is search by email supported?

No. The q parameter searches by full name using a partial match.

Can filters be combined?

Yes. Parameters are combined with AND logic.

Do I need to send idCompany?

No. The API determines companyId from the Bearer token.