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	/v1/employees
Base URL	https://smartway.pro/api
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 BFF takes 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
    }
  ],
  "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.

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 BFF takes 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

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 BFF error.
503 Service Unavailable	Internal integration failure BFF -> back2.

Usage

Run the first integration test 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 BFF takes companyId from the Bearer token.

Appearance

Language