# Boya Employees API Documentation

## Overview

The Boya Employees API provides endpoints for managing employees in the Boya platform. This API allows you to perform various operations related to employee management, including listing employees, creating new employees, managing employee profiles, and handling employee wallet transactions.

## Base URL

The base URL for the API is not specified in the provided OpenAPI specification. Please refer to the `api.yaml` file for server information.

## Authentication

The API uses API Key authentication. Include your API key in the `X-API-KEY` header for all requests.

## Endpoints

### 1. List all employees [API](/employee)

- **GET** `/employees`
- **Parameters:**
  - `page` (query): Page number for pagination
  - `limit` (query): Number of items per page
- **Responses:**
  - 200: Successful response (Array of Employee objects)
  - 400: Bad Request
  - 401: Unauthorized


### 2. Create a new employee

- **POST** `/employees`
- **Request Body:** EmployeeInput object
- **Responses:**
  - 201: Created (Employee object)
  - 400: Bad Request
  - 401: Unauthorized


### 3. Get a specific employee profile and balance

- **GET** `/employees?employee_id={employee_id}`
- **Parameters:**
  - `employee_id` (query, required): Employee ID
  - `org_wallet_ref` (query, required): Organization wallet reference
- **Responses:**
  - 200: Successful response (Employee object)
  - 401: Unauthorized
  - 404: Not Found


### 4. Suspend an employee

- **DELETE** `/employees/suspend`
- **Parameters:**
  - `employee_id` (query, required): Employee ID
- **Responses:**
  - 200: Employee suspended successfully
  - 401: Unauthorized
  - 404: Not Found


### 5. Activate an employee

- **PATCH** `/employees/activate`
- **Parameters:**
  - `employee_id` (query, required): Employee ID
- **Responses:**
  - 200: Employee activated successfully
  - 401: Unauthorized
  - 404: Not Found


### 6. Add money to an employee wallet

- **POST** `/employees/addMoney`
- **Request Body:** TransferFunds object
- **Responses:**
  - 200: Allocation successful
  - 401: Unauthorized
  - 404: Not Found


### 7. Deduct money from employee wallet

- **POST** `/employees/deductMoney`
- **Request Body:** TransferFunds object
- **Responses:**
  - 200: Deduction successful
  - 401: Unauthorized
  - 404: Not Found


### 8. Get employee balances for a specified date range

- **GET** `/employees/balances`
- **Parameters:**
  - `from` (query, required): Start date and time for the balance period (format: date-time)
  - `to` (query, required): End date and time for the balance period (format: date-time)
  - `page` (query): Page number for pagination
  - `limit` (query): Number of items per page
- **Responses:**
  - 200: Successful response (EmployeeBalancesResponse object)
  - 400: Bad Request
  - 401: Unauthorized


### 9. Get employee allocation/deduction transfer status

- **GET** `/employees/transfers/status?reference=$ref `
- **Parameters:**
  - `reference` (query, required): reference of allocation or deduction
- **Responses:**
  - 200: Successful response (TransferFundsStatus object)
  - 400: Bad Request
  - 401: Unauthorized


## Data Models

### Employee

- `id` (string)
- `name` (string)
- `email` (string)
- `role` (string)
- `status` (string): Enum values: active, suspended
- `createdAt` (string, format: date)


The `createdAt` field represents the date when the employee record was created in the system. It is stored as a string in the date format (e.g., "YYYY-MM-DD"). This field can be useful for:

1. Tracking when an employee was added to the system
2. Auditing purposes
3. Generating reports on employee onboarding


### EmployeeInput

- `name` (string, required)
- `organization_email` (string, required)
- `phone_number` (string, required)
- `team_code` (string, required)
- `role` (string, required): Enum values: CARD USER


### TransferFunds

- `accountref` (integer, required): org_wallet_ref (default: 1)
- `amount` (number, required)
- `description` (string, required)
- `employee_id` (string, required)
- `reference` (string, optional)


### TransferFundsStatus

- `amount` (number, required)
- `description` (string, required)
- `employee_id` (string, required)
- `reference` (string, optional)
- `status` (string)


### EmployeeBalancesResponse

- `openingEmployeeWalletsTotal` (number)
- `closingEmployeeWalletsTotal` (number)
- `employees` (object)
  - `docs` (array of EmployeeBalance objects)
  - `total` (integer)
  - `limit` (string)
  - `page` (string)
  - `pages` (integer)


### EmployeeBalance

- `_id` (string)
- `name` (string)
- `employee_id` (string)
- `accno` (string)
- `invited_on` (string, format: date-time)
- `organization_email` (string)
- `phone` (string)
- `status` (string)
- `role` (string)
- `id` (string)
- `openingBalance` (string)
- `closingBalance` (string)
- `teamName` (string)
- `teamOID` (string)


## Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests. Common error responses include:

- 400: Bad Request
- 401: Unauthorized
- 404: Not Found


For detailed error information, refer to the `api.yaml` file referenced in the OpenAPI specification.