Skip to content
Last updated

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: <api-key>

Endpoints

Expenses

Manage expense reports and transactions.

MethodEndpointDescription
GET/expensesList all expenses
GET/expenses/{id}Get a specific expense
POST/expensesCreate a new expense
PUT/expenses/{id}Update an existing expense
DELETE/expenses/{id}Delete an expense
GET/expenses/reviewList expenses pending review
GET/expenses/acceptedList accepted expenses
GET/expenses/rejectedList 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.

Teams

Manage teams and team members.

MethodEndpointDescription
GET/teamsList all teams
GET/teams/{id}Get a specific team
POST/teamsCreate 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.

Statements

Access and manage financial statements.

MethodEndpointDescription
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.

MethodEndpointDescription
GET/employeesList all employees with wallet balances for a specified date range
POST/employeesCreate a new employee
POST/employees/bulkCreate multiple employees in bulk
DELETE/employees/suspendSuspend an employee
PATCH/employees/activateActivate a suspended employee
POST/employees/addMoneyAdd funds to an employee's wallet
POST/employees/deductMoneyDeduct 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.

Rate Limits

The API is subject to rate limiting. For more information, see our Rate Limits Guide.

Error Handling

For information on error codes and handling, please consult our Error Handling Guide.

Additional Resources

For full details on request and response schemas, please refer to our OpenAPI specification.