> For the complete documentation index, see [llms.txt](https://docs.beeoclock.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.beeoclock.com/services/absence-management/api.md).

# API Documentation

## Overview

The Absence Management API provides endpoints for managing staff absences within the Bee O'clock platform. This API allows businesses to create, update, retrieve, and delete absence records for their members, with support for both individual member absences and business-wide closures.

## Base URL

```
/api/v1/absence
```

## Authentication

All endpoints require:

* **Bearer Token**: JWT authentication token
* **Business-Tenant-Id**: Header specifying the business tenant ID

## API Endpoints

### 1. Get Paginated Absences

**Endpoint:** `GET /paged`

**Description:** Retrieves a paginated list of absences for the authenticated tenant.

**Query Parameters:**

* `page` (number, optional): Page number (default: 1)
* `pageSize` (number, optional): Number of items per page (default: 10)
* Additional pagination parameters from `AbsencePaginationDto`

**Response:**

```typescript
{
  items: AbsenceDto[],
  totalSize: number,
  page: number,
  pageSize: number
}
```

**Permissions Required:** `READ_ABSENCE`

**Access Control:**

* Users with `OWN` scope can only see their own absences
* Users with `ANY` scope can see all absences
* Business-wide absences are visible to all authorized users

***

### 2. Get Absence by ID

**Endpoint:** `GET /:id`

**Description:** Retrieves a specific absence by its ID.

**Path Parameters:**

* `id` (string): The unique identifier of the absence

**Response:** `AbsenceDto`

**Permissions Required:** `READ_ABSENCE`

**Access Control:**

* Users can only access absences they are assigned to or business-wide absences
* Returns `null` if absence not found or access denied

***

### 3. Create Absence

**Endpoint:** `POST /`

**Description:** Creates a new absence record.

**Request Body:** `AbsenceDto`

**Required Fields:**

* `start`: Start date/time (ISO string)
* `end`: End date/time (ISO string)
* `type`: Absence type (vacation, holiday, break)
* `timeZone`: Timezone identifier

**Optional Fields:**

* `note`: Description or notes about the absence
* `entireBusiness`: Boolean indicating if this affects the entire business
* `members`: Array of member IDs affected (required if not entireBusiness)
* `locations`: Array of affected locations

**Response:** `void` (201 Created)

**Permissions Required:** `CREATE_ABSENCE`

**Validation Rules:**

* End date must be after start date
* Must specify either `entireBusiness: true` or at least one member
* Users with `OWN` scope can only create absences for themselves

***

### 4. Update Absence

**Endpoint:** `PUT /:id`

**Description:** Updates an existing absence record.

**Path Parameters:**

* `id` (string): The unique identifier of the absence

**Request Body:** `AbsenceDto` (complete object with `_id` field)

**Response:** `void` (200 OK)

**Permissions Required:** `EDIT_ABSENCE`

**Access Control:**

* Users can only update absences they have access to
* Business-wide absences require appropriate permissions

***

### 5. Delete Absence

**Endpoint:** `DELETE /:id`

**Description:** Soft deletes an absence record by updating its state history.

**Path Parameters:**

* `id` (string): The unique identifier of the absence

**Response:** `void` (200 OK)

**Permissions Required:** `DELETE_ABSENCE`

**Access Control:**

* Users can only delete absences they have access to
* Performs soft delete by updating state history to 'deleted'

## Data Transfer Objects

### AbsenceDto

```typescript
{
  _id?: string;
  object?: 'AbsenceDto';
  note?: string;
  start: string;           // ISO date string
  end: string;             // ISO date string
  type?: AbsenceTypeEnum;  // 'vacation' | 'holiday' | 'break'
  entireBusiness?: boolean;
  members?: MemberDto[];
  locations?: LocationDto[];
  timeZone?: string;
  meta?: MetaDto;
  createdAt?: string;
  updatedAt?: string;
}
```

### AbsenceTypeEnum

```typescript
enum AbsenceTypeEnum {
  vacation = 'vacation',
  holiday = 'holiday',
  break = 'break'
}
```

## Error Responses

### Common HTTP Status Codes

* **400 Bad Request**: Invalid request data or validation errors
* **401 Unauthorized**: Missing or invalid authentication token
* **403 Forbidden**: Insufficient permissions
* **404 Not Found**: Absence not found or access denied
* **500 Internal Server Error**: Server-side processing error

### Error Response Format

```typescript
{
  statusCode: number;
  message: string | string[];
  error?: string;
}
```

## Permission System

The absence management system uses a role-based permission system with the following permissions:

* **READ\_ABSENCE**: View absence records
* **CREATE\_ABSENCE**: Create new absence records
* **EDIT\_ABSENCE**: Modify existing absence records
* **DELETE\_ABSENCE**: Delete absence records

### Permission Scopes

* **OWN**: User can only manage their own absences
* **ANY**: User can manage any absences within their tenant

## Business Rules

1. **Date Validation**: End date must be greater than start date
2. **Assignment Validation**: Must specify either `entireBusiness: true` or at least one member
3. **Permission Enforcement**: Users can only manage absences they have permission to access
4. **Soft Deletion**: Absences are not physically deleted but marked as deleted in state history
5. **Timezone Support**: All dates are stored with timezone information
6. **Business-wide Impact**: Setting `entireBusiness: true` affects all operations regardless of member assignments

## Integration Points

* **Message Queue**: Publishes events for absence creation, updates, and deletions
* **WebSocket**: Real-time notifications sent to connected clients
* **Cache**: Automatic cache invalidation for affected queries
* **Audit Trail**: State history tracking for all changes

## Rate Limiting

Standard API rate limiting applies to all endpoints. Refer to the main API documentation for specific limits.

## Examples

### Create a Personal Absence

```javascript
POST /api/v1/absence
{
  "start": "2024-12-25T09:00:00.000Z",
  "end": "2024-12-25T17:00:00.000Z",
  "type": "vacation",
  "note": "Christmas vacation",
  "timeZone": "America/New_York",
  "members": [
    { "_id": "member-id-123" }
  ]
}
```

### Create a Business-wide Closure

```javascript
POST /api/v1/absence
{
  "start": "2024-12-25T00:00:00.000Z",
  "end": "2024-12-25T23:59:59.000Z",
  "type": "holiday",
  "note": "Christmas Day - Business Closed",
  "timeZone": "America/New_York",
  "entireBusiness": true
}
```