Boya Employees API Documentation

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.

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

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

• 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

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

• 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

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

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

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

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

• 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

• 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

• 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

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

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

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

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

• _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)

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.