How do you create an employee via the API?

POST /v1/employees creates an employee. Required body fields: email, name, surname, gender, and active. Access requires the employees.write scope.

Endpoint

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

Purpose

This endpoint is used to create a new employee within the company from the Bearer token.

The active value controls not only the business flag, but also the creation or absence of a linked user in Keycloak.

Prerequisites

The client must send a valid Bearer token.
The token must contain company context.
The token must contain the employees.write scope.
idCompany is not sent in the body or query string.
hrEmail is not sent by the external client; the BFF takes it from the Bearer token.
In the current implementation, Idempotency-Key is not used.

Request

Body parameters

Field	Type	Required	Description
email	string	yes	Employee email.
name	string	yes	Employee first name. This is the source of truth for generating fullName during creation.
surname	string	yes	Employee surname. This is the source of truth for generating fullName during creation.
gender	string	yes	Only Male or Female are allowed.
active	boolean	yes	Only JSON-boolean values true or false are allowed. true creates or synchronises personal account access through Keycloak; false creates the employee without that access.
department	string	no	Primary department. If not provided, null is stored.
departments	string[]	no	Set of departments. If not provided, the collection remains empty.
jobTitle	string	no	Primary job title. If not provided, null is stored.
jobTitles	string[]	no	Set of job titles. If not provided, the collection remains empty.
phone	string	no	Phone number. If not provided, null is stored.
notes	string	no	Notes. If not provided, null is stored.

curl example

Create an employee with primary fields and arrays

curl -X POST 'https://smartway.pro/api/v1/employees' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "email": "employee@example.com",
  "name": "Ivan",
  "surname": "Petrenko",
  "gender": "Female",
  "active": false,
  "department": "Management",
  "departments": ["КЛ"],
  "jobTitle": "Manager",
  "jobTitles": ["Coordinator"],
  "phone": "+380000000000",
  "notes": "New employee from public API"
}
JSON

Create an employee only with departments/jobTitles arrays

curl -X POST 'https://smartway.pro/api/v1/employees' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "email": "employee@example.com",
  "name": "Ivan",
  "surname": "Petrenko",
  "gender": "Male",
  "active": true,
  "departments": ["Management", "КЛ"],
  "jobTitles": ["Manager", "Coordinator"],
  "phone": "+380000000000",
  "notes": "New employee from public API"
}
JSON

Response

Successful response: 201 Created. Returns the created Employee.

{
  "employeeId": 4432,
  "candidateId": 10748,
  "email": "employee@example.com",
  "fullName": "Ivan Petrenko",
  "name": "Ivan",
  "surname": "Petrenko",
  "gender": "Female",
  "department": "Management",
  "departments": [
    "Management",
    "КЛ"
  ],
  "jobTitle": "Manager",
  "jobTitles": [
    "Coordinator",
    "Manager"
  ],
  "phone": "+380000000000",
  "active": false
}

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 determines companyId only from the Bearer token.
The BFF takes hrEmail from the Bearer token. hrEmail equals the email of the user with the HRADMIN role who created or rotated the active company API key.
If the active API key is rotated by another HRADMIN, subsequent create operations automatically start using that HRADMIN's hrEmail.
Repeating the same POST does not create a duplicate if an employee with the same email already exists; the API returns 409 Conflict.
gender accepts only Male or Female.
active accepts only JSON-boolean true or false.
active = true creates or synchronises the linked user account in Keycloak and enables access to the personal account.
active = false creates an employee without access to the personal account, that is, without a user in Keycloak.
fullName in the response is generated by the server from name + surname.
If only departments or jobTitles is provided, the first array element becomes the primary value in department or jobTitle.
If both a single field and an array are provided, the single field takes priority as primary, and the array is supplemented with unique values.
If department, jobTitle, phone, or notes is not provided, null is stored in the corresponding single field.
If departments or jobTitles is not provided, the corresponding collection remains empty.
In the response, departments and jobTitles are returned in a stable sorted order.

Edge cases

Edge cases

Scenario	API behaviour
A required field is missing	The API returns 400 Bad Request.
gender is not Male or Female	The API returns 400 Bad Request with an explanation.
active is sent as a string or number	The API returns 400 Bad Request because active must be JSON-boolean.
email already exists	The API returns 409 Conflict.
Only departments is provided	The first array element becomes department.
department and departments are provided	department remains primary, and departments is supplemented with unique values.
department or jobTitle is not provided	null is stored in the corresponding single field.
departments or jobTitles is not provided	The corresponding collection remains empty.
The client sends fullName	fullName is not described in the create request. The server generates fullName from name + surname.

Errors

Error responses

HTTP status	When it occurs
400 Bad Request	At least one required parameter is missing: email, name, surname, gender, or active.
400 Bad Request	gender is not Male or Female.
400 Bad Request	active is not a JSON-boolean value true or false.
401 Unauthorized	Bearer token is missing or invalid.
403 Forbidden	Insufficient permissions or token without company context.
409 Conflict	An Employee with this email already exists.
500 Internal Server Error	Unexpected BFF error.
503 Service Unavailable	Internal integration failure BFF -> back2.

Usage

Create an active employee with access to the personal account: active = true.
Create an employee without access to the personal account: active = false.
Send multiple departments or job titles with a defined primary value.
Synchronise employees from an external HR system.

Common mistakes

Typical integration mistakes

Common mistake	Correct approach
Sending active as the string "true" or "false"	Send true or false as a JSON boolean.
Sending gender with a value other than Male/Female	Use only Male or Female.
Sending idCompany or hrEmail	Do not send these values; the BFF takes them from the Bearer token.
Expecting idempotency through Idempotency-Key	In the current implementation, Idempotency-Key is not used.
Sending fullName instead of name and surname	Send name and surname; the server generates fullName.

FAQ

Which fields are required to create an employee?

email, name, surname, gender, and active.

What does active = true do?

The server creates or synchronises the linked user account in Keycloak and enables access to the personal account.

What does active = false do?

The employee is created without access to the personal account, that is, without a user in Keycloak.

What happens if the email already exists?

The API returns 409 Conflict.

Do I need to send hrEmail?

No. The BFF takes hrEmail from the Bearer token.

Appearance

Language