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 | /api/v1/employees | | Base
URL | https://smartway.pro | | 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 on the
authorisation server.
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.
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
the authorisation server; false creates the employee without that access. | | manager | boolean | no | Department
manager role flag. Only JSON-boolean values true or false are allowed; true creates or synchronises access with the
employee and department manager roles, even if active=false. | | 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,
"manager": 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,
"manager": 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,
"manager": 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. | | manager | boolean | Department manager role flag. true means the employee has
this role. |
Business logic
The API determines companyId only from the Bearer token.
The API determines 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 on the authorisation server and enables access to the
personal account.
active = false creates an employee without access to the personal account, that is, without a user account on the
authorisation server.
manager = true creates or synchronises access with the employee and department manager roles. If active = false is sent
at the same time, manager access takes priority and the employee is created as an active account user.
manager = false or omitting the manager field does not assign the department manager role.
manager is returned in the Employee response; after creation, this role can be changed through PATCH
/v1/employees/{employeeId}.
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
| 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. | |
manager is sent as a string or number | The API returns 400 Bad Request because manager must be JSON-boolean. | |
active=false and manager=true | Manager access takes priority; the employee is created as active. | | 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. |
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. | | 400 Bad Request | manager 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 API error. | | 503 Service Unavailable | Internal server integration
failure. |
Usage
Create an active employee with access to the personal account: active = true.
Create an employee without access to the personal account: active = false.
Create an employee with the department manager role: manager = true.
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 manager 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 API determines 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 on the authorisation server 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 account on the authorisation
server.
What does manager = true do?
The server creates or synchronises access with the employee and department manager roles. If active = false is sent at
the same time, the employee is still created as an active account user.
What happens if the email already exists?
The API returns 409 Conflict.
Do I need to send hrEmail?
No. The API determines hrEmail from the Bearer token.
