Skip to main content

Data Structure

The Category object is a structured representation of the transaction category assigned by the categorization engine. For E1, the output is intentionally compact and consists of a category key, a confidence score, and optional flags.

The category object is added to the Transaction API result models. These models are described within the Account Information Transaction Data Structures.

E1 category object​

Here is a brief overview of each field within the e1 category object:

Field
Type
Description
category
string
The category assigned by the E1 engine to the transaction, for example expense.essential.groceries or income.salary. See Categories.
confidence
number (0..1)
The confidence score of the assigned category, representing how certain the engine is about the prediction.
flags
array of string or [ ]
Optional flags that add extra context to the categorization result, for example refund, reversal_payment, or payment_arrangement.
model
object
The model that categorized the transaction: its version, profile and countryCode. Absent for transactions categorized before October 2026.
reasoning
object
Why the transaction got its category and flags. Only returned when you request it with include=reasoning. See Reasoning.
info

Unlike Z2, the E1 category object does not include an entity field.

Example 1 - Transaction Model​

{
  "id": "aeeffb5c-4800-5f6f-8797-7f488351553d",
  "accountNumber": "NL12ABNA9999876523",
  "accountId": "faa409f9-ff20-4462-4729-08dbfaecde2e",
  "description": "Albert Heijn",
  "amount": -54.25,
  "currency": "EUR",
  "category": {
    "e1": {
      "category": "expense.essential.groceries",
      "confidence": 0.97,
      "flags": []
    }
  }
}

Example 2 - Transaction Model with a flag​

{
  "id": "d8906f3a-5128-54cf-840f-1a82c5562b73",
  "accountNumber": "NL12ABNA9999876523",
  "accountId": "faa409f9-ff20-4462-4729-08dbfaecde2e",
  "description": "Refund bol.com",
  "amount": 18.95,
  "currency": "EUR",
  "category": {
    "e1": {
      "category": "expense.essential.other",
      "confidence": 0.88,
      "flags": [ "refund" ]
    }
  }
}

Reasoning​

Request transactions with include=reasoning to see why each transaction got its E1 category and flags. The reasoning object only contains the fields that apply to how the category was decided:

Field
Type
Description
method
string
model: the model chose the category. fallback: the model was not confident enough, so a broader category was chosen. rule: a fixed rule decided, for example a payment to the Dutch Tax Authority. override: the counterparty is one of your own accounts.
signals
object
At most three words or phrases of the transaction that pushed the model toward its choice, each with its share (0..1) of the push the transaction text gave it. model and fallback only.
alternatives
object
At most two other categories the model considered, with their score (0..1).
fallbackFrom
string
The category the model chose before it was widened. Its score is the reported confidence. fallback only.
threshold, bucketThreshold
number (0..1)
The confidence a category needs, and the confidence a broader category needs. fallback only.
buckets
object
The broader categories that were tried, in order, up to and including the chosen one, with their score rounded down. fallback only.
rule, matched
string
The rule that decided, for example nl.tax:license_plate, and the text of the transaction it matched. rule only.
flagSignals
object
Per flag, at most three words of the transaction that pushed it toward the flag, with their share (0..1).

Example 3 - Transaction Model with reasoning​

{
  "id": "d8906f3a-5128-54cf-840f-1a82c5562b73",
  "description": "Retourpintransactie",
  "counterpartDescription": "Decathlon",
  "amount": 24.99,
  "currency": "EUR",
  "category": {
    "e1": {
      "category": "expense.lifestyle.sports",
      "confidence": 0.68,
      "flags": [ "refund" ],
      "model": { "version": "202610.004", "profile": "retail", "countryCode": "nl" },
      "reasoning": {
        "method": "model",
        "signals": { "Decathlon": 0.92 },
        "alternatives": { "expense.lifestyle.other": 0.21 },
        "flagSignals": { "refund": { "Retourpintransactie": 0.56 } }
      }
    }
  }
}

Example 4 - Reasoning after a fallback​

"reasoning": {
  "method": "fallback",
  "fallbackFrom": "expense.lifestyle.restaurants_bars",
  "threshold": 0.6,
  "bucketThreshold": 0.5,
  "buckets": { "expense.lifestyle.other": 0.59 },
  "alternatives": { "expense.essential.groceries": 0.21 },
  "signals": { "Smit & Zonen Lindehof": 0.81 }
}