# Boya API Reference Welcome to the Boya API reference. This document provides an overview of the available endpoints for managing expenses, teams, statements, and employees. ## Base URL All API requests should be made to: ``` https://api.boyahq.com/v1 ``` ## Authentication All API requests require authentication. Include your API key in the header of each request: ``` x-api-key: ``` ## Endpoints ### Expenses Manage expense reports and transactions. | Method | Endpoint | Description | | --- | --- | --- | | GET | `/expenses` | List all expenses | | GET | `/expenses/{id}` | Get a specific expense | | POST | `/expenses` | Create a new expense | | PUT | `/expenses/{id}` | Update an existing expense | | DELETE | `/expenses/{id}` | Delete an expense | | GET | `/expenses/review` | List expenses pending review | | GET | `/expenses/accepted` | List accepted expenses | | GET | `/expenses/rejected` | List rejected expenses | #### Get all expenses ``` GET /expenses?fromDate={YYYY-MM-DD}&toDate={YYYY-MM-DD}&page={page}&limit={limit} ``` Retrieves a paginated list of expenses for the specified date range. #### Get a specific expense ``` GET /expenses/{id} ``` Retrieves details of a specific expense by its ID. #### Create a new expense ``` POST /expenses ``` Creates a new expense record. The request body should include expense details such as amount, currency, description, etc. #### Update an expense ``` PUT /expenses/{id} ``` Updates an existing expense record. The request body should include the fields to be updated. #### Delete an expense ``` DELETE /expenses/{id} ``` Deletes the specified expense record. #### List expenses pending review ``` GET /expenses/review ``` Retrieves a list of expenses that are pending review. #### List accepted expenses ``` GET /expenses/accepted ``` Retrieves a list of expenses that have been accepted. #### List rejected expenses ``` GET /expenses/rejected ``` Retrieves a list of expenses that have been rejected. For detailed information on request and response formats, please refer to the [Expenses API Guide](/expenses-1). ### Teams Manage teams and team members. | Method | Endpoint | Description | | --- | --- | --- | | GET | `/teams` | List all teams | | GET | `/teams/{id}` | Get a specific team | | POST | `/teams` | Create a new team | | PUT | `/teams/{id}` | Update an existing team | | DELETE | `/teams/{id}` | Delete a team | #### Get all teams ``` GET /teams ``` Retrieves a list of all teams in the organization. #### Get a specific team ``` GET /teams/{id} ``` Retrieves details of a specific team by its ID. #### Create a new team ``` POST /teams ``` Creates a new team. The request body should include team details such as name, description, etc. #### Update a team ``` PUT /teams/{id} ``` Updates an existing team's information. The request body should include the fields to be updated. #### Delete a team ``` DELETE /teams/{id} ``` Deletes the specified team. For more details on team management, see the [Teams API Guide](/teams-1). ### Statements Access and manage financial statements. | Method | Endpoint | Description | | --- | --- | --- | | GET | `/wallet/all-in-one/{org_wallet_ref}` | List all statements | | GET | `/wallet/topup-history/{accountNumber}/{org_wallet_ref}` | Get topup statement | #### Get all statements ``` GET /wallet/all-in-one/{org_wallet_ref} ``` Retrieves a list of all available financial statements. #### Get a specific statement ``` GET /wallet/topup-history/{accountNumber}/{org_wallet_ref} ``` ### Employees Manage employee information, roles, and wallet balances. | Method | Endpoint | Description | | --- | --- | --- | | GET | `/employees` | List all employees with wallet balances for a specified date range | | POST | `/employees` | Create a new employee | | POST | `/employees/bulk` | Create multiple employees in bulk | | DELETE | `/employees/suspend` | Suspend an employee | | PATCH | `/employees/activate` | Activate a suspended employee | | POST | `/employees/addMoney` | Add funds to an employee's wallet | | POST | `/employees/deductMoney` | Deduct funds from an employee's wallet | #### Get all employees ``` GET /employees?fromDate={YYYY-MM-DD}&toDate={YYYY-MM-DD}&page={page}&limit={limit} ``` Retrieves a paginated list of employees with their wallet balances for the specified date range. #### Create a new employee ``` POST /employees ``` Creates a new employee record. Required fields in the request body: - `name` - `organization_email` - `phone_number` - `role` - `team_code` #### Create multiple employees (Bulk) ``` POST /employees/bulk ``` Creates multiple employee records in a single request. The request body should contain an array of employee objects, each with the required fields listed above. #### Suspend an employee ``` POST /employees/{employeeId}/suspend ``` Changes the status of the specified employee to SUSPENDED. #### Activate an employee ``` POST /employees/{employeeId}/activate ``` Changes the status of the specified employee to ACTIVE. #### Add funds to employee wallet ``` POST /employees/{employeeId}/wallet/add ``` Adds funds to the specified employee's wallet. The request body should include the `amount` to be added. #### Deduct funds from employee wallet ``` POST /employees/{employeeId}/wallet/deduct ``` Deducts funds from the specified employee's wallet. The request body should include the `amount` to be deducted. For detailed information on request and response formats for the Employee API, please refer to the [Employee API Guide](/employee-1). ## Rate Limits The API is subject to rate limiting. For more information, see our [Rate Limits Guide](/rate-limits). ## Error Handling For information on error codes and handling, please consult our [Error Handling Guide](/errors). ## Additional Resources - [API Changelog](https://www.boyahq.com/api-changelog) - [Developer Community](https://community.boyahq.com) - [Contact API Support](mailto:api-support@boyahq.com) For full details on request and response schemas, please refer to our OpenAPI specification.