How do you get an employee by ID via the API?

GET /v1/employees/{employeeId} returns one employee by ID within the tenant context from the Bearer token.

Endpoint

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

Purpose

This endpoint is used to retrieve detailed information about one employee.

The lookup is performed only within the tenant context defined by the Bearer token.

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 separately.
employeeId must belong to an employee within the current tenant.

Request

Path parameters

Parameter	Type	Required	Description
employeeId	int64	yes	Employee ID.

curl example

Get an employee by ID

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

Response

Successful response: 200 OK. Returns Employee.

{
  "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
}

Response fields

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.

Business logic

The BFF takes companyId from the Bearer token.
idCompany is not sent as a separate parameter.
Employee lookup is performed within the tenant context from the Bearer token.
If employeeId is not found in the current tenant, the API returns 404 Not Found.
Access requires the employees.read scope.
fullName is a derived field and is generated by the server from name + surname.

Edge cases

Edge cases

Scenario	API behaviour
employeeId exists in the current tenant	The API returns 200 OK and Employee.
employeeId is not found in the current tenant	The API returns 404 Not Found.
employeeId exists in another company	The API does not return an employee outside the current tenant context.
Bearer token has no company context	The API returns 403 Forbidden.
The client sends idCompany	The endpoint does not use idCompany from the client request.

Errors

Error responses

HTTP status	When it occurs
400 Bad Request	The request is invalid.
401 Unauthorized	Bearer token is missing or invalid.
403 Forbidden	Insufficient permissions or token without company context.
404 Not Found	Employee was not found within the current tenant.
500 Internal Server Error	Unexpected BFF error.
503 Service Unavailable	Internal integration failure BFF -> back2.

Usage

Retrieve an employee profile by employeeId.
Check the result of creating or updating an employee.
Synchronise one employee record in an external system.
Check whether employeeId is available within the current tenant.

Common mistakes

Typical integration mistakes

Common mistake	Correct approach
Sending idCompany together with employeeId	Do not send idCompany; the tenant is determined from the Bearer token.
Using a token without employees.read	Reading an employee requires the employees.read scope.
Expecting access to an employee from another company	The API looks up only in the current tenant context.
Treating 404 as a technical error	404 means the employee was not found in the current tenant.

FAQ

Do I need to send idCompany?

No. companyId is taken from the Bearer token.

Which scope is required?

employees.read.

What happens if employeeId is not found?

The API returns 404 Not Found.

Is fullName returned?

Yes. fullName is returned as an Employee field and is generated by the server from name + surname.

Appearance

Language