> ## Documentation Index
> Fetch the complete documentation index at: https://docs.triqai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Categories

> Understanding Triqai's hierarchical category taxonomy

Triqai uses a comprehensive, hierarchical category system to classify transactions. This taxonomy is designed to be consistent, intuitive, and compatible with industry standards.

## Category Structure

Categories are organized in three levels:

Primary → Secondary → Tertiary

For example:

* **Primary**: Parking
* **Secondary**: Vehicle Services
* **Tertiary**: Transportation

Not every transaction will have all three levels. Triqai assigns the most specific applicable category while ensuring accuracy.

## Category Response

Each enriched transaction includes a category structure with a `confidence` object containing both a numeric `value` and explanatory `reasons`:

```json theme={null}
{
  "category": {
    "primary": {
      "name": "Shopping",
      "code": {
        "mcc": 5411,
        "sic": 5411,
        "naics": 445110
      }
    },
    "secondary": {
      "name": "Online Shopping",
      "code": {
        "mcc": 5411,
        "sic": 5411,
        "naics": 445110
      }
    },
    "tertiary": {
      "name": "Marketplace",
      "code": {
        "mcc": 5411,
        "sic": 5411,
        "naics": 445110
      }
    },
    "confidence": { "value": 95, "reasons": ["merchant_category_match"] }
  }
}
```

### Category Confidence Reasons

The `reasons` array on category confidence uses these tags:

| Tag                       | Meaning                                                                |
| ------------------------- | ---------------------------------------------------------------------- |
| `merchant_category_match` | The identified merchant has a known/linked category mapping            |
| `fallback_classification` | Category came from fallback logic rather than strong merchant evidence |
| `p2p_transfer_detected`   | Transaction detected as P2P transfer by deterministic rules            |

## Industry Codes

Each category includes standardized industry codes:

| Code      | Name                                          | Description                           |
| --------- | --------------------------------------------- | ------------------------------------- |
| **MCC**   | Merchant Category Code                        | 4-digit code used by payment networks |
| **SIC**   | Standard Industrial Classification            | Legacy classification system          |
| **NAICS** | North American Industry Classification System | Modern industry classification        |

These codes enable integration with accounting systems, compliance tools, and analytics platforms that expect standardized industry identifiers.

## Expense Categories

Triqai supports 68 expense categories across these primary groups:

<AccordionGroup>
  <Accordion title="Shopping" icon="cart-shopping">
    * General Merchandise
    * Online Shopping
    * Clothing & Apparel
    * Electronics
    * Home & Garden
    * Department Stores
    * Marketplace
  </Accordion>

  <Accordion title="Food & Dining" icon="utensils">
    * Restaurants
    * Fast Food
    * Coffee Shops
    * Bars & Nightlife
    * Groceries
    * Food Delivery
  </Accordion>

  <Accordion title="Transportation" icon="car">
    * Gas Stations
    * Parking
    * Public Transit
    * Ride Sharing
    * Tolls
    * Car Rental
    * Airlines
  </Accordion>

  <Accordion title="Entertainment" icon="film">
    * Streaming Services
    * Movies & Theater
    * Music
    * Gaming
    * Sports & Recreation
    * Events & Tickets
  </Accordion>

  <Accordion title="Bills & Utilities" icon="file-invoice-dollar">
    * Electricity
    * Gas
    * Water
    * Internet
    * Phone
    * Cable TV
    * Insurance
  </Accordion>

  <Accordion title="Health & Wellness" icon="heart-pulse">
    * Healthcare
    * Pharmacy
    * Fitness & Gym
    * Personal Care
    * Medical Services
  </Accordion>

  <Accordion title="Financial" icon="landmark">
    * Bank Fees
    * Interest
    * Investments
    * Taxes
    * Insurance Premiums
    * Loan Payments
  </Accordion>

  <Accordion title="Travel" icon="plane">
    * Hotels & Lodging
    * Airlines
    * Car Rental
    * Travel Agencies
    * Vacation Rentals
  </Accordion>

  <Accordion title="Services" icon="briefcase">
    * Professional Services
    * Software
    * Education
    * Legal Services
  </Accordion>
</AccordionGroup>

## Income Categories

Triqai supports 38 income categories including:

* **Salary & Wages**: Regular employment income
* **Freelance**: Contract and gig work payments
* **Refunds**: Returns and reimbursements
* **Interest**: Bank interest, dividends
* **Transfers**: P2P and account transfers
* **Government**: Benefits, tax refunds
* **Rental Income**: Property rental payments
* **Investments**: Capital gains, dividends

## Category Confidence

Each category assignment includes a confidence object with a `value` (0-100) and `reasons`:

| Range  | Interpretation                                         |
| ------ | ------------------------------------------------------ |
| 90-100 | Very high confidence, reliable for automated decisions |
| 70-89  | High confidence, suitable for most use cases           |
| 50-69  | Moderate confidence, may benefit from manual review    |
| 0-49   | Low confidence, recommend manual verification          |

## Fetching All Categories

You can retrieve the complete category taxonomy via the API:

<CodeGroup>
  ```typescript Node.js theme={null}
  import Triqai from "triqai";

  const triqai = new Triqai(process.env.TRIQAI_API_KEY!);

  const { categories, total, categoryVersion } = await triqai.categories.list();

  for (const cat of categories) {
    console.log(`${cat.name} (level ${cat.level}, type: ${cat.type})`);
  }
  ```

  ```bash cURL theme={null}
  curl https://api.triqai.com/v1/categories \
    -H "X-API-Key: YOUR_API_KEY"
  ```
</CodeGroup>

The response includes all categories with their hierarchy, descriptions, and industry codes.

## Category Versioning

Triqai's category taxonomy is versioned. The current version is returned in the `meta.categoryVersion` field:

```json theme={null}
{
  "meta": {
    "categoryVersion": "triqai-2026.01"
  }
}
```

When the taxonomy is updated, the version changes. This allows you to detect and adapt to changes in the category structure.

## Best Practices

<Tip>
  **Use primary categories for high-level grouping** and secondary/tertiary for detailed analysis. This provides flexibility for different reporting needs.
</Tip>

<Note>
  **Industry codes are mapped per category**, not per merchant. If you need merchant-specific MCC codes, use the payment processor's original data.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Entities" icon="building" href="/concepts/entities">
    Learn about merchant, location, and intermediary data
  </Card>

  <Card title="List Categories API" icon="code" href="/api-reference/list-categories">
    Fetch the complete category taxonomy
  </Card>
</CardGroup>