Subcategories API Documentation

Endpoint

GET https://api.boyahq.com/v1/categories

Description

Retrieves a list of all expense categories and their associated subcategories for a business.

Authentication

Required: Yes
Type: ApiKeyAuth
Header: x-api-key: <apiKey>

Headers

Header	Required	Description
`accept`	Yes	Should be set to `application/json`

Response

Success Response

Status Code: 200 OK
Content-Type: application/json

Response Body Structure

[
  {
    "_id": "string",
    "groupid": "string",
    "name": "string",
    "description": "string",
    "status": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "__v": number,
    "subcategories": [
      {
        "_id": "string",
        "group_id": "string",
        "category": "string",
        "code": "string",
        "name": "string",
        "description": "string",
        "status": "string",
        "createdAt": "string",
        "updatedAt": "string",
        "__v": number,
        "mapping_id": "string",
        "teams": ["string"]
      }
    ]
  }
]

Response Fields

Category Object

Field	Type	Description
`_id`	string	Unique identifier for the category
`groupid`	string	Group identifier
`name`	string	Category name
`description`	string	Category description
`status`	string	Category status (e.g., "ACTIVE")
`createdAt`	string	Creation timestamp
`updatedAt`	string	Last update timestamp
`__v`	number	Version number
`subcategories`	array	Array of subcategory objects

Subcategory Object

Field	Type	Description
`_id`	string	Unique identifier for the subcategory
`group_id`	string	Group identifier
`category`	string	Parent category ID
`code`	string	Subcategory code or Chart of account code (must be unique)
`name`	string	Subcategory name
`description`	string	Subcategory description
`status`	string	Subcategory status (e.g., "ACTIVE")
`createdAt`	string	Creation timestamp
`updatedAt`	string	Last update timestamp
`__v`	number	Version number
`mapping_id`	string	Mapping identifier i.e external id where applicable
`teams`	array	Array of team identifiers. When populated, only people in the selected teams can tag the subcategory

Error Responses

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing authentication token"
}

403 Forbidden

{
  "error": "Forbidden",
  "message": "Invalid business_id or insufficient permissions"
}

404 Not Found

{
  "error": "Not Found",
  "message": "No categories found for the specified business"
}

Example Categories

The API returns various category types including:

Office Expenses
Travel
Supplies & Hardware
IT & Software
Growth & Marketing
Business Meals
Business Entertainment

Each category contains relevant subcategories with specific codes and descriptions for expense tracking and management.

Notes

All timestamps are in ISO 8601 format
Category and subcategory status can be used for filtering active/inactive items
Team assignments are optional and may be empty arrays