# HRMS API API Reference

> **Version:** 1.0.0 | **Base URL:** `https://hifisys.com/api/v1/hrms` | **Provider:** Hifisys

## Overview
Complete enterprise human resource management API for employee lifecycle, attendance, leaves, payroll, payslips, work logs, and analytics.

## Authentication
All requests require a valid API key passed in the request header:
```http
X-API-Key: YOUR_API_KEY
Accept: application/json
```
Alternatively, pass as a standard Bearer token:
```http
Authorization: Bearer YOUR_API_KEY
```

## Available Subscription Plans
| Plan | Price | Rate Limit | Monthly Quota | Trial |
|---|---|---|---|---|
| Free Trial | Free Trial | 60 req/min | 2,000 | 7 Days |
| Starter | USD 49.00/month | 120 req/min | 25,000 | No |
| Business | USD 149.00/month | 300 req/min | 100,000 | No |
| Enterprise | USD 399.00/month | 1000 req/min | 500,000 | No |

## API Endpoints
### `GET` /api/v1/hrms/employees
**List Company Employees**
> **Scope:** `employees:read` | **Content-Type:** `application/json`

Returns a paginated list of company employees with department, designation, and employment status.

#### Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Search by name, employee code, or email. |
| `department_id` | `integer` | No | Filter by department ID. |
| `status` | `string` | No | active, inactive, probation, terminated. |

#### Example Requests
**cURL:**
```bash
curl -X GET "https://hifisys.com/api/v1/hrms/employees?status=active" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
```
**JavaScript:**
```javascript
const res = await fetch('https://hifisys.com/api/v1/hrms/employees?status=active', {
  headers: { 'X-API-Key': 'YOUR_API_KEY', 'Accept': 'application/json' }
});
const data = await res.json();
```
**PHP:**
```php
$ch = curl_init('https://hifisys.com/api/v1/hrms/employees?status=active');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: YOUR_API_KEY', 'Accept: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
```
**Python:**
```python
import requests
res = requests.get('https://hifisys.com/api/v1/hrms/employees?status=active', headers={'X-API-Key': 'YOUR_API_KEY'})
print(res.json())
```

#### Sample Response (200 OK)
```json
{
    "success": true,
    "data": [
        {
            "id": 1,
            "employee_code": "EMP-001",
            "full_name": "Sarah Connor",
            "email": "sarah@example.com",
            "department": "Engineering",
            "designation": "Staff Engineer",
            "employment_status": "active"
        }
    ]
}
```

---

### `POST` /api/v1/hrms/attendance/clock-in
**Attendance Clock-In**
> **Scope:** `attendance:write` | **Content-Type:** `application/json`

Records employee punch-in timestamp, location coordinates/mode, and IP address.

#### Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `employee_id` | `integer` | **Yes** | Unique employee identifier. |
| `work_mode` | `string` | No | office, remote, hybrid. Default: office. |

#### Example Requests
**cURL:**
```bash
curl -X POST "https://hifisys.com/api/v1/hrms/attendance/clock-in" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"employee_id":1,"work_mode":"office"}'
```
**JavaScript:**
```javascript
const res = await fetch('https://hifisys.com/api/v1/hrms/attendance/clock-in', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ employee_id: 1, work_mode: 'office' })
});
```
**PHP:**
```php
$ch = curl_init('https://hifisys.com/api/v1/hrms/attendance/clock-in');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['employee_id' => 1, 'work_mode' => 'office']));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
```
**Python:**
```python
import requests
res = requests.post('https://hifisys.com/api/v1/hrms/attendance/clock-in', json={'employee_id': 1, 'work_mode': 'office'}, headers={'X-API-Key': 'YOUR_API_KEY'})
print(res.json())
```

#### Sample Response (200 OK)
```json
{
    "success": true,
    "message": "Clock-in recorded successfully at 09:00:00.",
    "data": {
        "attendance_id": 124,
        "clock_in": "2026-10-07 09:00:00"
    }
}
```

---

## Security Best Practices
- Store API keys in environment variables; never commit to public VCS repositories.
- Enforce TLS 1.3 across all client integrations.
- Implement exponential backoff algorithms for rate-limit handling (HTTP 429).

## Support & Contact
- **Email:** info@hifisys.com
- **Phone:** +91 8890897064
- **Website:** [Hifisys](https://hifisys.com)