Departments, Shifts, Holidays & Announcements REST API

The organization API covers all configuration objects that define how your workforce is structured and informed. Departments, shifts, and holidays form the scheduling backbone; announcements carry time-bounded communications to role-scoped audiences; permissions expose the full RBAC model. All paths are prefixed with /api/v1 and require a valid JWT.

Unless otherwise noted, every endpoint requires Authorization: Bearer <token>. Create/update operations are restricted to ADMIN or HR_OPERATIONS roles.

Departments

`GET /api/v1/departments`

Returns all departments ordered alphabetically by name. Available to any authenticated user.

[]

array

Array of DepartmentRead objects.

Show DepartmentRead fields

string

UUID of the department.

name

string

Department name.

description

string | null

Optional description.

admin_id

string | null

UUID of the department head user.

admin_name

string | null

Full name of the department head, resolved server-side.

is_active

boolean

Whether the department is currently active.

Example Response

[
  {
    "id": "d1e2f3a4-...",
    "name": "Engineering",
    "description": "Product engineering team",
    "admin_id": "a1b2c3d4-...",
    "admin_name": "Usman Tariq",
    "is_active": true
  }
]

`POST /api/v1/departments`

Creates a new department. The designated head must be an active user with role ADMIN, HR_OPERATIONS, MANAGER, or TEAM_LEAD. Auth: ADMIN role required.

name

string

required

Display name for the department.

description

string

Optional free-text description.

head_id

string

UUID of the user to assign as department head. Alias for admin_id — either field is accepted.

is_active

boolean

Defaults to true.

string

UUID of the created department.

name

string

admin_name

string | null

Resolved head name.

If the specified head_id belongs to an inactive user or a role that is ineligible (e.g. EMPLOYEE), the server returns 400 Bad Request.

Example Request Body

{
  "name": "Product Design",
  "description": "UX and visual design team",
  "head_id": "b2c3d4e5-...",
  "is_active": true
}

`GET /api/v1/departments/active`

Returns only departments where is_active is true. Useful for populating dropdown menus. Auth: Any authenticated user.

`GET /api/v1/departments/{department_id}`

Fetch a single department by UUID. Auth: Any authenticated user.

department_id

string

required

UUID of the department.

`GET /api/v1/departments/{department_id}/employees`

Returns the list of employees currently assigned to this department. Auth: Any authenticated user.

department_id

string

required

UUID of the department.

[]

array

Array of OrganizationMemberRead objects with employee details and assignment metadata.

`PATCH /api/v1/departments/{department_id}`

Update department fields. Partial updates — only send fields you want to change. Auth: ADMIN role required.

department_id

string

required

UUID of the department to update.

name

string

New department name.

description

string

Updated description.

head_id

string

UUID of the new department head. Must be an eligible active user.

is_active

boolean

Set to false to deactivate.

`DELETE /api/v1/departments/{department_id}`

Soft-deletes a department by setting is_active = false. Fails with 409 CONFLICT if any employees are still assigned to this department. Auth: ADMIN role required.

department_id

string

required

UUID of the department to deactivate.

success

boolean

Always true on success.

Departments with assigned employees cannot be deactivated. Reassign all employees to a different department first.

Shifts

Work shifts define the scheduled hours for a group of employees. Shifts carry a name, start/end times, and an optional grace window for late check-ins.

`GET /api/v1/shifts`

Lists all shifts. Pass only_active=true to filter to active shifts only. Auth: Any authenticated user.

only_active

boolean

When true, returns only shifts with is_active = true. Defaults to false.

[]

array

Array of ShiftRead objects.

Show ShiftRead fields

string

UUID.

name

string

Shift label, e.g. "Morning" or "Night".

start_time

string

Local time string HH:MM:SS.

end_time

string

Local time string HH:MM:SS.

is_active

boolean

`POST /api/v1/shifts`

Creates a new shift definition. Auth: ADMIN or HR_OPERATIONS role required.

name

string

required

Human-readable shift name.

start_time

string

required

Shift start time in HH:MM:SS format (24-hour clock).

end_time

string

required

Shift end time in HH:MM:SS format (24-hour clock).

is_active

boolean

Defaults to true.

Example Request Body

{
  "name": "Morning Shift",
  "start_time": "09:00:00",
  "end_time": "17:00:00",
  "is_active": true
}

`GET /api/v1/shifts/{shift_id}`

Fetch a single shift by UUID. Auth: Any authenticated user.

shift_id

string

required

UUID of the shift.

`PATCH /api/v1/shifts/{shift_id}`

Update shift fields. Only the provided fields are changed. Auth: ADMIN or HR_OPERATIONS role required.

shift_id

string

required

UUID of the shift to update.

name

string

Updated shift name.

start_time

string

Updated start time HH:MM:SS.

end_time

string

Updated end time HH:MM:SS.

is_active

boolean

Set to false to deactivate.

`POST /api/v1/shifts/assign/{user_id}`

Assigns a shift to a specific employee. Pass shift_id as a query parameter; omit it to unassign. Auth: ADMIN or HR_OPERATIONS role required.

user_id

string

required

UUID of the employee to assign the shift to.

shift_id

string

UUID of the shift to assign. Omit to clear the user’s shift assignment.

message

string

Always "Shift assigned successfully" on success.

`GET /api/v1/shifts/{shift_id}/employees`

Returns the list of employees assigned to this shift. Auth: Any authenticated user.

shift_id

string

required

UUID of the shift.

[]

array

Array of OrganizationMemberRead objects.

`DELETE /api/v1/shifts/{shift_id}`

Deactivates a shift by setting is_active = false. Auth: ADMIN or HR_OPERATIONS role required.

shift_id

string

required

UUID of the shift to deactivate.

success

boolean

Always true on success.

Holidays

Public holidays are calendar entries that inform leave calculations and attendance rules.

`GET /api/v1/holidays`

Returns all holiday records. Auth: Any authenticated user.

[]

array

Array of HolidayRead objects.

Show HolidayRead fields

string

UUID.

name

string

Holiday name, e.g. "Eid ul-Fitr".

description

string | null

holiday_date

string

ISO date YYYY-MM-DD.

is_active

boolean

`POST /api/v1/holidays`

Creates a new public holiday entry. Auth: ADMIN role required.

name

string

required

Holiday name.

holiday_date

string

required

Date in ISO format YYYY-MM-DD.

description

string

Optional description.

is_active

boolean

Defaults to true.

Example Request Body

{
  "name": "Pakistan Day",
  "holiday_date": "2025-03-23",
  "description": "National holiday",
  "is_active": true
}

Example Response

{
  "id": "h1i2j3k4-...",
  "name": "Pakistan Day",
  "description": "National holiday",
  "holiday_date": "2025-03-23",
  "is_active": true
}

`GET /api/v1/holidays/active`

Returns only holidays where is_active is true. Auth: Any authenticated user.

`GET /api/v1/holidays/upcoming`

Returns the next N active holidays from the given anchor date. Useful for dashboard widgets. Auth: Any authenticated user.

limit

integer

Maximum number of holidays to return. Defaults to 5.

from_date

string

ISO date anchor. Defaults to today.

`PATCH /api/v1/holidays/{holiday_id}`

Update holiday fields. Only the provided fields are changed. Auth: ADMIN role required.

holiday_id

string

required

UUID of the holiday to update.

name

string

Updated holiday name.

holiday_date

string

Updated date ISO YYYY-MM-DD.

description

string

Updated description.

is_active

boolean

Set to false to deactivate.

`DELETE /api/v1/holidays/{holiday_id}`

Deactivates a holiday by setting is_active = false. Auth: ADMIN role required.

holiday_id

string

required

UUID of the holiday to deactivate.

success

boolean

Always true on success.

Announcements

Announcements are time-bounded messages broadcast to specific role audiences. The server automatically filters which announcements a user can see based on their role.

`GET /api/v1/announcements`

Returns all active announcements visible to the authenticated user based on their role. Expired or future-dated announcements are excluded. Auth: Any authenticated user.

[]

array

Array of AnnouncementRead objects.

Show AnnouncementRead fields

string

UUID.

title

string

content

string

audience

string

One of: all, employee, admin, hr_operations, manager, team_lead, intern, junior_employee.

start_date

string | null

ISO date when announcement becomes active.

end_date

string | null

ISO date when announcement expires.

is_active

boolean

created_by

string

UUID of the creating user.

`POST /api/v1/announcements`

Creates a new announcement and broadcasts an announcement_created realtime event to all connected WebSocket clients matching the audience. Auth: ADMIN or HR_OPERATIONS role required.

title

string

required

Announcement headline.

content

string

required

Full announcement body.

audience

string

required

Target audience. Must be one of: all, employee, admin, hr_operations, manager, team_lead, intern, junior_employee.

start_date

string

ISO date for when the announcement starts displaying. Optional.

end_date

string

ISO date for when the announcement stops displaying. Optional.

is_active

boolean

Defaults to true. Set to false to create a draft.

When is_active is true, an announcement_created WebSocket event is automatically pushed to all connected clients whose role matches the audience value.

Example Request Body

{
  "title": "Office Closed — Public Holiday",
  "content": "The office will be closed on 23rd March 2025 for Pakistan Day.",
  "audience": "all",
  "start_date": "2025-03-22",
  "end_date": "2025-03-24",
  "is_active": true
}

`GET /api/v1/announcements/visible`

Returns a limited list of active, non-expired announcements for dashboard panels. Auth: Any authenticated user.

limit

integer

Number of announcements to return. Defaults to 5.

include_expired

boolean

When true, also returns expired announcements. Defaults to false.

`GET /api/v1/announcements/all`

Returns all announcements regardless of active/expired status or audience. Intended for admin management views. Auth: ADMIN or HR_OPERATIONS role required.

[]

array

All AnnouncementRead objects ordered by creation time descending.

`PATCH /api/v1/announcements/{announcement_id}`

Update or archive an existing announcement. Only provided fields are changed. Auth: ADMIN or HR_OPERATIONS role required.

announcement_id

string

required

UUID of the announcement to update.

title

string

Updated headline.

content

string

Updated body text.

audience

string

Updated audience. Must be a valid audience string.

start_date

string

Updated start date ISO YYYY-MM-DD.

end_date

string

Updated end date ISO YYYY-MM-DD.

is_active

boolean

Set to false to archive the announcement.

Permissions

The permissions system maps role keys to capability strings. These records are seeded at startup and managed exclusively by system administrators.

`GET /api/v1/permissions`

Lists all registered permission keys and their descriptions. Auth: Requires the permissions.manage permission (Admin only in practice).

[]

array

Array of permission descriptor objects.

Show Permission fields

key

string

Dot-notation permission key, e.g. analytics.view_org.

description

string | null

Human-readable description of the permission.

Example Response

[
  { "key": "analytics.view_org", "description": "View org-wide analytics" },
  { "key": "analytics.view_team", "description": "View team analytics" },
  { "key": "permissions.manage", "description": "Manage role and user permissions" }
]

`GET /api/v1/permissions/role/{role}`

Returns the list of permission keys assigned to a specific role. Auth: permissions.manage permission required.

role

string

required

Role identifier, e.g. admin, manager, employee.

[]

array

Sorted list of permission key strings assigned to the role.

`POST /api/v1/permissions/user-override`

Grants or revokes a specific permission for an individual user, overriding their role defaults. Auth: permissions.manage permission required.

user_id

string

required

UUID of the target user.

permission_key

string

required

The permission key to override, e.g. analytics.view_org.

granted

boolean

true to grant, false to revoke. Defaults to true.

message

string

Confirmation message indicating the action taken and the affected user.

`GET /api/v1/permissions/user/{user_id}`

Returns the full resolved permission set for a user, merging their role permissions with any individual overrides. Auth: permissions.manage permission required.

user_id

string

required

UUID of the user to inspect.

user_id

string

role

string

permissions

array

Sorted list of granted permission key strings.

Example Response

{
  "user_id": "a1b2c3d4-...",
  "role": "manager",
  "permissions": [
    "analytics.view_team",
    "attendance.view_team",
    "reports.view_team"
  ]
}

Error Reference

HTTP Status	Error Code	Reason
`401`	`AUTH_ERROR`	Missing or invalid JWT
`403`	`PERMISSION_ERROR`	Insufficient role or permission
`404`	`NOT_FOUND`	Resource not found
`409`	`CONFLICT`	Department has assigned employees
`422`	`VALIDATION_ERROR`	Invalid audience or field values

Overview

Endpoints

Departments

`GET /api/v1/departments`

`POST /api/v1/departments`

`GET /api/v1/departments/active`

`GET /api/v1/departments/{department_id}`

`GET /api/v1/departments/{department_id}/employees`

`PATCH /api/v1/departments/{department_id}`

`DELETE /api/v1/departments/{department_id}`

Shifts

`GET /api/v1/shifts`

`POST /api/v1/shifts`

`GET /api/v1/shifts/{shift_id}`

`PATCH /api/v1/shifts/{shift_id}`

`POST /api/v1/shifts/assign/{user_id}`

`GET /api/v1/shifts/{shift_id}/employees`

`DELETE /api/v1/shifts/{shift_id}`

Holidays

`GET /api/v1/holidays`

`POST /api/v1/holidays`

`GET /api/v1/holidays/active`

`GET /api/v1/holidays/upcoming`

`PATCH /api/v1/holidays/{holiday_id}`

`DELETE /api/v1/holidays/{holiday_id}`

Announcements

`GET /api/v1/announcements`

`POST /api/v1/announcements`

`GET /api/v1/announcements/visible`

`GET /api/v1/announcements/all`

`PATCH /api/v1/announcements/{announcement_id}`

Permissions

`GET /api/v1/permissions`

`GET /api/v1/permissions/role/{role}`

`POST /api/v1/permissions/user-override`

`GET /api/v1/permissions/user/{user_id}`

Error Reference

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Departments

​GET /api/v1/departments

​POST /api/v1/departments

​GET /api/v1/departments/active

​GET /api/v1/departments/{department_id}

​GET /api/v1/departments/{department_id}/employees

​PATCH /api/v1/departments/{department_id}

​DELETE /api/v1/departments/{department_id}

​Shifts

​GET /api/v1/shifts

​POST /api/v1/shifts

​GET /api/v1/shifts/{shift_id}

​PATCH /api/v1/shifts/{shift_id}

​POST /api/v1/shifts/assign/{user_id}

​GET /api/v1/shifts/{shift_id}/employees

​DELETE /api/v1/shifts/{shift_id}

​Holidays

​GET /api/v1/holidays

​POST /api/v1/holidays

​GET /api/v1/holidays/active

​GET /api/v1/holidays/upcoming

​PATCH /api/v1/holidays/{holiday_id}

​DELETE /api/v1/holidays/{holiday_id}

​Announcements

​GET /api/v1/announcements

​POST /api/v1/announcements

​GET /api/v1/announcements/visible

​GET /api/v1/announcements/all

​PATCH /api/v1/announcements/{announcement_id}

​Permissions

​GET /api/v1/permissions

​GET /api/v1/permissions/role/{role}

​POST /api/v1/permissions/user-override

​GET /api/v1/permissions/user/{user_id}

​Error Reference

Build docs developers (and LLMs) love

Departments

`GET /api/v1/departments`

`POST /api/v1/departments`

`GET /api/v1/departments/active`

`GET /api/v1/departments/{department_id}`

`GET /api/v1/departments/{department_id}/employees`

`PATCH /api/v1/departments/{department_id}`

`DELETE /api/v1/departments/{department_id}`

Shifts

`GET /api/v1/shifts`

`POST /api/v1/shifts`

`GET /api/v1/shifts/{shift_id}`

`PATCH /api/v1/shifts/{shift_id}`

`POST /api/v1/shifts/assign/{user_id}`

`GET /api/v1/shifts/{shift_id}/employees`

`DELETE /api/v1/shifts/{shift_id}`

Holidays

`GET /api/v1/holidays`

`POST /api/v1/holidays`

`GET /api/v1/holidays/active`

`GET /api/v1/holidays/upcoming`

`PATCH /api/v1/holidays/{holiday_id}`

`DELETE /api/v1/holidays/{holiday_id}`

Announcements

`GET /api/v1/announcements`

`POST /api/v1/announcements`

`GET /api/v1/announcements/visible`

`GET /api/v1/announcements/all`

`PATCH /api/v1/announcements/{announcement_id}`

Permissions

`GET /api/v1/permissions`

`GET /api/v1/permissions/role/{role}`

`POST /api/v1/permissions/user-override`

`GET /api/v1/permissions/user/{user_id}`

Error Reference