API Documentation (Legacy v1.0)
Introduction
Welcome to the HR System API documentation. This API provides comprehensive access to all HR management features including employee management, attendance tracking, leave management, payroll, and more.
http://127.0.0.1:8000/api
Total Endpoints: 70+
Authentication: API Key + Bearer Token (Laravel Sanctum)
Authentication
All API requests require two layers of authentication:
1. API Key (Required for ALL requests)
Include the API key in the request header:
X-API-KEY: your-api-key-here2. Bearer Token (Required for protected endpoints)
After login, include the bearer token:
Authorization: Bearer your-sanctum-token-here• Public endpoints (register, login): 30 requests/minute
• Protected endpoints: 600 requests/minute
Authentication Endpoints
Register a new employee account with email or phone number.
Request Body:
{
"email": "employee@example.com",
"phone": "+201234567890",
"password": "Password123!",
"password_confirmation": "Password123!"
}Success Response (201):
{
"success": true,
"message": "Registration successful. Please verify your OTP.",
"data": {
"user_id": 1,
"email": "employee@example.com",
"requires_verification": true
}
}cURL Example:
curl -X POST http://127.0.0.1:8000/api/auth/register \
-H "X-API-KEY: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"email": "employee@example.com",
"password": "Password123!",
"password_confirmation": "Password123!"
}'Verify the OTP sent to email/phone after registration.
Request Body:
{
"identifier": "employee@example.com",
"otp": "123456"
}Success Response (200):
{
"success": true,
"message": "OTP verified successfully.",
"data": {
"verified": true
}
}Authenticate user and receive access token.
Request Body:
{
"email": "employee@example.com",
"password": "Password123!"
}Success Response (200):
{
"success": true,
"message": "Login successful.",
"data": {
"token": "1|abcdef123456...",
"user": {
"id": 1,
"email": "employee@example.com",
"role": "employee",
"profile_complete": false
}
}
}Logout current session (revoke current token).
Headers Required:
X-API-KEY: your-api-key
Authorization: Bearer your-sanctum-tokenSuccess Response (200):
{
"success": true,
"message": "Logged out successfully."
}Request OTP for password reset.
Request Body:
{
"identifier": "employee@example.com"
}Permanently delete user account and all associated data.
Profile Management
Get current user's employee profile.
Complete employee profile with required information.
Request Body:
{
"first_name": "Ahmad",
"last_name": "Hassan",
"date_of_birth": "1990-05-15",
"gender": "male",
"national_id": "12345678901234",
"address": "123 Main St, Cairo",
"department_id": 1,
"position": "Software Engineer",
"employment_date": "2024-01-01",
"salary": 15000
}Update employee profile information.
Departments
Get list of all departments.
Get specific department details.
Create a new department.
Request Body:
{
"name": "Engineering",
"description": "Software development team",
"manager_id": 2
}Update department information.
Delete a department.
Attendance Management
Track employee check-in, check-out, and attendance history.
Check in for the current day.
Check out for the current day.
Get today's attendance record.
Get attendance history with pagination.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
| start_date | date | Filter from date (YYYY-MM-DD) |
| end_date | date | Filter to date (YYYY-MM-DD) |
| page | integer | Page number for pagination |
Get all employees' attendance records (Manager/Admin).
Generate attendance report for all employees.
Leave Management
Get available leave types (annual, sick, emergency, etc.).
Request a new leave.
Request Body:
{
"leave_type": "annual",
"start_date": "2024-02-01",
"end_date": "2024-02-05",
"reason": "Family vacation"
}Get leave balance and quota.
Get all pending leave requests for approval.
Approve or reject leave request.
Request Body:
{
"status": "approved",
"notes": "Approved for vacation"
}Task Management
Get assigned tasks for the current employee.
Create and assign a new task.
Request Body:
{
"title": "Implement new feature",
"description": "Add user authentication module",
"assigned_to": 5,
"due_date": "2024-02-15",
"priority": "high",
"status": "pending"
}Update task status (in_progress, completed, etc.).
Add comment to a task.
Upload attachment to a task.
Payroll Management
Get employee's payroll history.
Get specific payslip details.
Generate payroll for a specific month.
Request Body:
{
"month": "2024-01",
"employee_ids": [1, 2, 3]
}Internal Messaging
Get inbox messages.
Send a message to another employee.
Request Body:
{
"recipient_id": 3,
"subject": "Project Update",
"body": "The new feature is ready for testing."
}Notifications
Get all notifications for the current user.
Mark notification as read.
Mark all notifications as read.
Dashboard & Analytics
Get employee dashboard statistics.
Get manager dashboard with team statistics.
Get admin dashboard with full company statistics.
Get employee burnout risk statistics.
Reports (Admin Only)
Generate comprehensive attendance report.
Generate leave usage report.
Generate payroll summary report.
Generate expense summary report.
Expense Management
Submit a new expense claim.
Request Body:
{
"amount": 500.00,
"category": "travel",
"description": "Client meeting transportation",
"date": "2024-01-15",
"receipt_url": "uploads/receipts/receipt123.pdf"
}Get pending expenses for approval.
Approve or reject expense claim.
Office Assets
Get assets assigned to the current employee.
Add a new asset to the system.
Request Body:
{
"name": "MacBook Pro",
"asset_id": "COMP-001",
"category": "computer",
"purchase_date": "2024-01-01",
"value": 3000.00
}Assign asset to an employee.
File Uploads
Upload profile image.
Request (multipart/form-data):
image: [file]Upload expense receipt.
Upload task attachment.
Upload multiple files at once.
Delete an uploaded file.
Error Handling
All API errors follow a consistent format:
{
"success": false,
"message": "Error description",
"errors": {
"field_name": ["Validation error message"]
}
}Common HTTP Status Codes:
| Code | Meaning | Description |
|---|---|---|
| 200 | OK | Request successful |
| 201 | Created | Resource created successfully |
| 400 | Bad Request | Invalid request data |
| 401 | Unauthorized | Authentication required or failed |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource not found |
| 422 | Unprocessable Entity | Validation errors |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Server Error | Internal server error |