Complete REST API reference for the LeaveFlow v1 API. The API supports machine-to-machine integrations with bearer token authentication.
Interactive API Explorer: Open Swagger UI to browse endpoints, view schemas, and explore requests interactively.
All API endpoints require a Bearer token in the Authorization header.
Authorization: Bearer YOUR_API_TOKEN
Tokens are SHA-256 hashed in the database. The raw token cannot be retrieved after generation. Tokens are company-scoped — they can only access data for the company they were created in.
| State | Behavior |
|---|---|
| Active | Authenticates requests |
| Revoked | Returns 401 Unauthorized |
| Expired | Returns 401 Unauthorized |
To revoke a token, navigate to Admin → API Tokens, open the token detail page, and click Revoke. Revocation is immediate.
https://your-leaveflow-domain.com/api/v1
Replace your-leaveflow-domain.com with your LeaveFlow installation domain.
All endpoints respond with Content-Type: application/json.
| Code | Meaning | Description |
|---|---|---|
200 |
OK | Request successful |
201 |
Created | Resource created successfully |
204 |
No Content | Request successful, no body returned |
400 |
Bad Request | Malformed request body |
401 |
Unauthorized | Missing, expired, or revoked bearer token |
403 |
Forbidden | Token does not have access to this resource |
404 |
Not Found | Resource not found or belongs to a different company |
422 |
Unprocessable Entity | Validation failed — field errors in body |
500 |
Internal Server Error | Server error |
All errors return a consistent JSON body:
{
"error": true,
"message": "Description of what went wrong"
}
Validation errors (422) include field-level detail:
{
"error": true,
"message": "Validation failed",
"violations": [
{
"field": "email",
"message": "This value is not a valid email address."
}
]
}
Retrieve all active employees for the authenticated company.
GET /api/v1/employees
Authorization: Bearer YOUR_API_TOKEN
Success (200 OK): Array of employee resources.
[
{
"id": 1,
"name": "Maya Manager",
"employeeNumber": "EMP-001",
"email": "manager@leaveflow.test",
"locationId": 1,
"locationName": "Berlin Office",
"joinedAt": "2024-01-01",
"leftAt": null,
"weeklyHours": 40.0,
"userId": 2
},
{
"id": 2,
"name": "Erik Employee",
"employeeNumber": "EMP-002",
"email": "employee@leaveflow.test",
"locationId": 1,
"locationName": "Berlin Office",
"joinedAt": "2024-03-01",
"leftAt": null,
"weeklyHours": 30.0,
"userId": 3
}
]
| Field | Type | Description |
|---|---|---|
id |
integer | Internal employee ID |
name |
string | Full name |
employeeNumber |
string | Unique employee number within the company |
email |
string or null | Email address of the linked user account (null if no user linked) |
locationId |
integer | ID of the assigned location |
locationName |
string | Name of the assigned location |
joinedAt |
string (date) | Start date — format YYYY-MM-DD |
leftAt |
string (date) or null | Exit date — null if employee is still active |
weeklyHours |
float | Contracted weekly hours |
userId |
integer or null | ID of the linked user account (null if no login account) |
curl -X GET "https://your-domain.com/api/v1/employees" \
-H "Authorization: Bearer YOUR_API_TOKEN"
Retrieve a single employee by ID.
GET /api/v1/employees/{id}
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
integer | Yes | Employee ID |
Success (200 OK): Single employee resource (same schema as list).
Error (404 Not Found): Employee does not exist or belongs to a different company.
curl -X GET "https://your-domain.com/api/v1/employees/1" \
-H "Authorization: Bearer YOUR_API_TOKEN"
Create a new employee with a linked user account.
POST /api/v1/employees
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
name |
string | Yes | max 150 chars | Full name |
email |
string | Yes | valid email | Email for the linked user account |
employeeNumber |
string | Yes | max 50 chars, unique per company | Employee number |
locationId |
integer | Yes | positive integer | ID of the location to assign |
joinedAt |
string | Yes | date format YYYY-MM-DD |
Start date |
weeklyHours |
float | No | positive, default 40.0 |
Contracted weekly hours |
role |
string | No | employee, manager, admin; default employee |
Role for the user account |
Success (201 Created): The created employee resource.
Error (422 Unprocessable Entity): Validation failed (e.g., duplicate email or employee number).
curl -X POST "https://your-domain.com/api/v1/employees" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Anna New",
"email": "anna.new@example.com",
"employeeNumber": "EMP-010",
"locationId": 1,
"joinedAt": "2026-07-01",
"weeklyHours": 40.0,
"role": "employee"
}'
employeeNumber must be unique within the company. Duplicate values return a 422 error.locationId must belong to the same company as the API token.Partially update an employee record. Only the provided fields are updated.
PATCH /api/v1/employees/{id}
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
integer | Yes | Employee ID |
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
All fields are optional. Only fields present in the request body are updated.
| Field | Type | Constraints | Description |
|---|---|---|---|
name |
string or null | max 150 chars | Update full name |
locationId |
integer or null | positive integer | Reassign to a different location |
weeklyHours |
float or null | positive | Update contracted weekly hours |
Success (200 OK): The updated employee resource.
Error (404 Not Found): Employee does not exist or belongs to a different company.
# Update location
curl -X PATCH "https://your-domain.com/api/v1/employees/1" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"locationId": 2}'
# Update weekly hours
curl -X PATCH "https://your-domain.com/api/v1/employees/1" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"weeklyHours": 32.0}'
Deactivate an employee by setting their exit date. This does not delete the employee — their leave history is retained. The linked user account is deactivated if the exit date is today or in the past.
DELETE /api/v1/employees/{id}
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
integer | Yes | Employee ID |
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
exitDate |
string | No | Exit date in YYYY-MM-DD format. Defaults to today if omitted. |
2026-12-31 |
Success (204 No Content): Employee deactivated. No body returned.
Error (404 Not Found): Employee does not exist or belongs to a different company.
# Deactivate today
curl -X DELETE "https://your-domain.com/api/v1/employees/5" \
-H "Authorization: Bearer YOUR_API_TOKEN"
# Deactivate on a future date
curl -X DELETE "https://your-domain.com/api/v1/employees/5?exitDate=2026-12-31" \
-H "Authorization: Bearer YOUR_API_TOKEN"
exitDate is today or in the past, the linked user account is deactivated immediately.exitDate is in the future, the user account remains active until the scheduled deactivation job runs.