Documentation

Categorisation as a Service

For clients who want to categorise a specific set of transactions without creating users and AIS connections within our API, we provide the option to input transactions into our categorisation engine for category assignment.

Suggest Edits

🚧

/Prerequisites

Ensure you have the scope categorisation enabled on your API client. If you haven't been given this scope yet, ask us and we can enable it for you.

Supported Account Types

The following personal account types are supported: cash, card, savings, pension, investment.

For best results

The optimal use of this endpoint is to categorise transactions that belong to the same user. Providing their identifier for accountId in subsequent calls will improve accuracy. We also recommend including the transaction identifiers in the request, as they will assist with reconciling them in the response.

Additional transaction properties

Although optional, including proprietaryTransactionCode and merchantCategoryCode can enhance the accuracy of the categorisation process.

Proprietary Transaction Code is a unique identifier used by the financial institution to categorise a given transaction. Some Examples include "DIRECT DEBIT" or numberic codes "540"

Merchant Category Code is a 4-character identifier for the type of business or service provided by the merchant. This identifier is standardised according to the ISO 18245 standard. Examples include '5411' (Grocery Stores), '5812' (Eating Places and Restaurants), and '5999' (Miscellaneous Retail Stores).

Batch Processing

We recommend batching as many transactions as possible per request. The maximum number of transactions allowed per request is 200.

API Request

To categorise a set of transactions, make a request to:

POST https://api.moneyhub.co.uk/v3/categorise-transactions

Using cURL

curl -X POST https://api.moneyhub.co.uk/v3/categorise-transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <obtained from /oidc/token endpoint>" \
  -d '{
    "accountId": "b72f2a5d-c43f-4db1-8143-6f6682ac132c",
    "accountType": "cash", // "cash" | "card" | "savings" | "pension" | "investment"
    "transactions": [
      {
        "id": "b72f2a5d-c43f-4db1-8143-6f6682ac132c",
        "description": "Amazon",
        "amount": {
          "value": -3000
        },
        "date": "2025-05-02T15:50:19.603Z",
        "proprietaryTransactionCode": "DEBIT",
        "merchantCategoryCode": "OT42"
      }
    ]
  }'

Using the moneyhub-api-client

const data = await moneyhub.categoriseTransactions({
  accountId: "b72f2a5d-c43f-4db1-8143-6f6682ac132c",
  accountType: "cash", // "cash" | "card" | "savings" | "pension" | "investment"
  transactions: [
    {
      id: "b72f2a5d-c43f-4db1-8143-6f6682ac132c",
      description: "Amazon",
      amount: {
        value: -3000,
      },
      date: "2025-05-02T15:50:19.603Z",
      proprietaryTransactionCode: "DEBIT",
      merchantCategoryCode: "OT42",
    },
    {
      id: "b72f2a5d-c43f-4db1-8143-6f6682ac133c",
      description: "Tesco",
      amount: {
        value: -3000,
      },
      date: "2025-05-02T15:50:19.603Z",
      proprietaryTransactionCode: "DEBIT",
      merchantCategoryCode: "OT42",
    },
  ],
})

After receiving the response from our API, the transactions that were successfully categorised will have a categoryId, as well as a counterpartyId if counterparty detection was successful.

Any transactions where category detection failed will appear in the failedCategorisationIds array.

{
  "accountId": "b72f2a5d-c43f-4db1-8143-6f6682ac132c",
  "accountType": "cash",
  "transactions": [
    {
      "id": "b72f2a5d-c43f-4db1-8143-6f6682ac132c",
      "description": "Amazon",
      "amount": {"value": -3000},
      "date": "2025-05-02T15:50:19.603Z",
      "counterpartyId": "ba4d83ec-3240-5d6e-b258-11e1c913da62",
      "categoryId": "std:cdc55410-176d-4c71-9bb2-6988b5d4913d",
      "proprietaryTransactionCode": "DEBIT",
      "merchantCategoryCode": "OT42"
    },
    {
      "id": "b72f2a5d-c43f-4db1-8143-6f6682ac133c",
      "description": "Tesco",
      "amount": {"value": -3000},
      "date": "2025-05-02T15:50:19.603Z",
      "counterpartyId": "26c417bc-248f-5e3f-9835-3cd9c2842f50",
      "categoryId": "std:a2d41243-ab21-4d02-ac0d-daa3621e4b49",
      "proprietaryTransactionCode": "DEBIT",
      "merchantCategoryCode": "OT42"
    }
  ],
  "failedCategorisationIds": []
}

For more information about categories and counterparties please refer to the following sections:

Categories and Categories Groups

Counterparties

More information about this endpoint can be found in our API Reference

Updated 3 days ago

What’s Next