{ "openapi": "3.0.3", "info": { "title": "AIHR BD API", "version": "1.2.0", "description": "Public read-only REST API for the AIHR BD multi-tenant HRM platform.\n\n## Authentication\n- **ApiKeyAuth** (`x-api-key` header) — generate keys from the in-app **Integrations → API Keys** page. Each key is scoped to one company and respects row-level security.\n\n## Rate limits & quotas\n- Endpoints accept `limit` up to **500** rows per call (default **100**).\n\nInternal and privileged endpoints are not documented publicly.\n", "contact": { "name": "AIHR BD Support", "url": "https://aihrbd.com/contact", "email": "support@aihrbd.com" }, "license": { "name": "Proprietary", "url": "https://aihrbd.com/terms" }, "termsOfService": "https://aihrbd.com/terms" }, "externalDocs": { "description": "AIHR BD documentation", "url": "https://aihrbd.com/docs" }, "servers": [ { "url": "https://aihrbd.com/api/public", "description": "Production" } ], "tags": [ { "name": "Public API", "description": "Read-only REST API for third-party integrations (API key required)." } ], "paths": { "/hrm": { "get": { "tags": ["Public API"], "summary": "API root / discovery", "description": "Returns API metadata and the list of available endpoints.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "API metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "AIHR BD Public API" }, "version": { "type": "string", "example": "v1" }, "endpoints": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/hrm/employees": { "get": { "tags": ["Public API"], "summary": "List employees", "description": "Returns active and former employees of the company that owns the API key.", "parameters": [ { "$ref": "#/components/parameters/Limit" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Employee" } } } }, "example": { "data": [ { "id": "8f1a2b30-c8e2-4a4d-9b97-2e1c1f3aab01", "employee_id": "EMP-0001", "name": "Rakib Hasan", "email": "rakib@example.com", "phone": "+8801712345678", "designation": "Software Engineer", "department": "Engineering", "gross_salary": 65000, "basic_salary": 39000, "join_date": "2024-03-15", "status": "Active" }, { "id": "1d6c4f10-2bc9-44a7-8a3a-9b0aa12c4efa", "employee_id": "EMP-0002", "name": "Sumaiya Akter", "email": "sumaiya@example.com", "phone": "+8801911223344", "designation": "HR Manager", "department": "Human Resources", "gross_salary": 80000, "basic_salary": 48000, "join_date": "2023-08-01", "status": "Active" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/hrm/attendance": { "get": { "tags": ["Public API"], "summary": "List attendance records", "description": "Returns attendance entries within an optional date range.", "parameters": [ { "name": "from", "in": "query", "description": "Start date (inclusive, YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "End date (inclusive, YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/Limit" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Attendance rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Attendance" } } } }, "example": { "data": [ { "id": "a1c2-...", "employee_id": "8f1a2b30-c8e2-4a4d-9b97-2e1c1f3aab01", "date": "2026-01-15", "check_in": "09:01:23", "check_out": "18:05:11", "status": "Present" }, { "id": "b2d3-...", "employee_id": "8f1a2b30-c8e2-4a4d-9b97-2e1c1f3aab01", "date": "2026-01-16", "check_in": "09:35:02", "check_out": "18:02:44", "status": "Late" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/hrm/payroll": { "get": { "tags": ["Public API"], "summary": "List payroll runs", "description": "Returns payroll rows filterable by month and year.", "parameters": [ { "name": "month", "in": "query", "description": "Month 1–12.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 } }, { "name": "year", "in": "query", "description": "4-digit year.", "schema": { "type": "integer", "minimum": 2000 } }, { "$ref": "#/components/parameters/Limit" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Payroll rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payroll" } } } }, "example": { "data": [ { "id": "p1q2-...", "employee_id": "8f1a2b30-c8e2-4a4d-9b97-2e1c1f3aab01", "month": 1, "year": 2026, "basic_salary": 39000, "net_salary": 61450, "tax": 1500, "provident_fund": 2050, "status": "paid", "paid_at": "2026-02-02T10:15:32Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/hrm/leave": { "get": { "tags": ["Public API"], "summary": "List leave requests", "description": "Leave requests for the company, newest start date first.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date filter (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date filter (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "required": false, "description": "pending | manager_approved | approved | rejected | cancelled", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max rows (1-500, default 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "uuid", "employee_id": "uuid", "leave_type": "annual", "start_date": "2026-03-01", "end_date": "2026-03-03", "days": 3, "status": "approved" } ] } } } }, "400": { "description": "Invalid parameters" }, "401": { "description": "Missing or invalid API key" } } } }, "/hrm/documents": { "get": { "tags": ["Public API"], "summary": "List employee document metadata", "description": "Document metadata only. File contents are never exposed through the public API.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "employee_id", "in": "query", "required": false, "description": "Filter by employee UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Max rows (1-500, default 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "uuid", "employee_id": "uuid", "document_type": "nid", "document_name": "NID copy", "expiry_date": null, "created_at": "2026-01-05T09:00:00Z" } ] } } } }, "400": { "description": "Invalid parameters" }, "401": { "description": "Missing or invalid API key" } } } }, "/hrm/reports/headcount": { "get": { "tags": ["Public API"], "summary": "Headcount report", "description": "Total, active, and grouped headcount by department and employment type.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "report": "headcount", "data": { "total": 124, "active": 118, "by_department": { "Finance": 12 }, "by_employment_type": { "permanent": 100 } } } } } }, "400": { "description": "Invalid parameters" }, "401": { "description": "Missing or invalid API key" } } } }, "/hrm/reports/attendance-summary": { "get": { "tags": ["Public API"], "summary": "Attendance summary report", "description": "Attendance record counts by status for a month.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "month", "in": "query", "required": false, "description": "Month 1-12 (defaults to current month)", "schema": { "type": "integer", "minimum": 1, "maximum": 12 } }, { "name": "year", "in": "query", "required": false, "description": "Four-digit year (defaults to current year)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "report": "attendance-summary", "period": { "month": 3, "year": 2026 }, "data": { "records": 2480, "present": 2300, "late": 110, "absent": 40, "on_leave": 30 } } } } }, "400": { "description": "Invalid parameters" }, "401": { "description": "Missing or invalid API key" } } } }, "/hrm/reports/payroll-summary": { "get": { "tags": ["Public API"], "summary": "Payroll summary report", "description": "Aggregated payroll totals (BDT) for a month.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "month", "in": "query", "required": false, "description": "Month 1-12 (defaults to current month)", "schema": { "type": "integer", "minimum": 1, "maximum": 12 } }, { "name": "year", "in": "query", "required": false, "description": "Four-digit year (defaults to current year)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "report": "payroll-summary", "period": { "month": 3, "year": 2026 }, "data": { "employees": 118, "gross_total": 8450000, "net_total": 7900000, "tax_total": 320000, "provident_fund_total": 230000, "paid": 118, "pending": 0 } } } } }, "400": { "description": "Invalid parameters" }, "401": { "description": "Missing or invalid API key" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Generate from in-app Integrations → API Keys." } }, "parameters": { "Limit": { "name": "limit", "in": "query", "description": "Max rows to return (default 100, max 500).", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid or revoked API key" } } }, "Employee": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "employee_id": { "type": "string", "example": "EMP-0001" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "designation": { "type": "string" }, "department": { "type": "string" }, "gross_salary": { "type": "number", "format": "double" }, "basic_salary": { "type": "number", "format": "double" }, "join_date": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": ["Active", "Inactive", "Terminated"] } } }, "Attendance": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "employee_id": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "check_in": { "type": "string", "example": "09:01:23" }, "check_out": { "type": "string", "example": "18:05:11" }, "status": { "type": "string", "enum": ["Present", "Absent", "Late", "Half Day", "Leave"] } } }, "Payroll": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "employee_id": { "type": "string", "format": "uuid" }, "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "year": { "type": "integer" }, "basic_salary": { "type": "number", "format": "double" }, "net_salary": { "type": "number", "format": "double" }, "tax": { "type": "number", "format": "double" }, "provident_fund": { "type": "number", "format": "double" }, "status": { "type": "string", "enum": ["pending", "processed", "paid"] }, "paid_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "responses": { "Unauthorized": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Invalid or revoked API key" } } } }, "ServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Internal server error" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }