---
title: "Categorize transactions"
method: POST
path: "/documents/{id}/categorize"
tags: ["Documents"]
---

# Categorize transactions

`POST /documents/{id}/categorize`

## Request

- Base URL: `https://api.bankstatemently.com/v1`
- URL: `https://api.bankstatemently.com/v1/documents/{id}/categorize`
- Auth: API key in header `X-API-Key`

Categorize a document's transactions using AI. Returns cached categories if already generated (no credit charge). Otherwise deducts 1 credit and runs LLM-based categorization. Rate limit: 20 requests per minute.

## Path parameters

- `id` string, uuid, required

## Response `200`

Categories returned (cached or freshly generated).

- object
  - `id` string, uuid: Document UUID.
  - `contentHash` string: SHA-256 content hash of the original file.
  - `categories` object
    - `metadata` object
      - `categorizedAt` string, date-time: When categorization was performed.
      - `model` string: AI model used for categorization.
      - `totalTransactions` integer: Number of transactions categorized.
    - `mappings` object: Map of transaction sequence number to category ID.

## Other responses

- `401`: Authentication failed, API key revoked, or API key expired.
- `403`: Insufficient credits.
- `404`: Document not found.
- `409`: Document not ready for categorization.
- `429`: Too many requests. Wait the number of seconds indicated by the `Retry-After` header.
- `500`: An unexpected server error occurred.

---

[API](https://skmtc.dev/bankstatemently/apis/bankstatemently-api.md) · [All operations](https://skmtc.dev/bankstatemently/apis/bankstatemently-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bankstatemently/apis/bankstatemently-api/revisions/4c3b7fb26edf?raw)