> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ntropy.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ntropy.com/_mcp/server.

# Categories

Transaction categories describe the nature or purpose of financial transactions. They are a core component of
the enrichment output and can be found in the
[categories field](/documentation/api/transactions/post-transaction#response.body.categories). They are comprised of two
types:
- [General categories](#general-categories): Returned for all transactions.
- [Accounting categories](#accounting-categories): Specific to business transactions and returned alongside the general
  ones.

# General categories
The set of general categories available is dependent on the account holder type and vary
a great deal between them.

They are organized into two main classes: `incoming` and `outgoing` representing the subset of available categories
for transactions of that `entry_type`.
You can find the listing containing all the categories for each type below:
- [consumer](https://api.ntropy.com/v2/labels/hierarchy/consumer)
- [business](https://api.ntropy.com/v2/labels/hierarchy/business)

Transactions for which none of the categories are suitable, will be categorised
as `other`.

## Special categories
In cases where there is not enough information to accurately classify a transaction, the API will return the category
`not enough information`. This category is used when the available transaction data is insufficient to determine a
specific category. This ensures that transactions are not incorrectly categorized when the data is ambiguous or incomplete.

If no account holder is specified for a transaction, the category `missing account holder information` will be assigned.

# Accounting categories
<Note>This is a premium feature. [Reach out](/support) to us to enable it.</Note>


For business transactions, we also provide an accounting category. The available categories are the following:
- operational expenses
- cost of goods sold
- revenue
- financing
- taxes

# Custom categories
In addition to the default categories, Ntropy allows you to define and use custom categories for your specific needs.
This feature enables you to tailor our categorization system to your unique use case.

Note, that for best possible results, custom categories should be as
succinct, precise and non-overlapping as possible. It is also good practice to
add the `other` category as a "sink", in case none of the categories are suitable.

The special categories `not enough information` and `missing
account holder information` will automatically be added to the list of
custom categories.

<Warning>
If you are using recurrence, we recommend that you create a new API key.
Having different sets of categories in transaction histories might yield unexpected results.
</Warning>

## Retrieving Custom Categories

To view your current set of active categories:

<EndpointRequestSnippet endpoint="GET /v3/categories/{id}" />

<Accordion title='See the full raw output'>
    <EndpointResponseSnippet endpoint="GET /v3/categories/{id}" />
</Accordion>

The `consumer` and `business` category IDs are the default categories used based on the account
holder's type. We recommend you do not modify these and instead create new category IDs.

## Create Custom Categories

To create custom categories you need to create a JSON structure that represents your desired label organization.
The structure should contain two main categories: "incoming" and "outgoing", each containing an array of labels.
Custom categories other than `consumer` and `business` are shared between all API keys.

Here's an example of how to set a custom hierarchy:

<EndpointRequestSnippet endpoint="POST /v3/categories/{id}" />

<Accordion title='See the full raw output'>
    <EndpointResponseSnippet endpoint="POST /v3/categories/{id}" />
</Accordion>

<Note>
    NOTE: If a category ID already exists, this will overwrite the previous contents.
</Note>

## Using Custom Categories

To use your newly created custom categories, you need to create an account holder and specify the category ID.

<CodeBlocks>

**`SDK`**

```python title="SDK"
from ntropy_sdk import SDK

sdk = SDK("cd1H...Wmhl")
ah = sdk.account_holders.create(
    id="35b927b6-6fda-40aa-93b8-95b47c2b2cad",
    type="consumer",
    name="John Doe",
    category_id="my_category_id",
)
```

**`cURL`**

```bash title="cURL"
curl -X "POST" \
    "https://api.ntropy.com/v3/account_holders" \
    -H "Accept: application/json" \
    -H "X-API-KEY: cd1H...Wmhl"  \
    -H "Content-Type: application/json" \
    -d '{
        "id": "35b927b6-6fda-40aa-93b8-95b47c2b2cad",
        "type": "consumer",
        "name": "John Doe",
        "category_id": "my_category_id"
    }'

```
</CodeBlocks>

From here you can submit transactions using the account holder ID as usual.

## Delete Custom Categories

The API also allows you to delete a category set:

<EndpointRequestSnippet endpoint="POST /v3/categories/{id}/reset" />

<Accordion title='See the full raw output'>
    <EndpointResponseSnippet endpoint="POST /v3/categories/{id}/reset" />
</Accordion>


--------------------------------------------------