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

• 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

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)

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.