Overview

Regular transaction series detection is user-scoped: every detect and result message includes a userId, and result egress is always shaped as { userId, accounts[] }. A user may have multiple accounts (for example, a current account and a credit card).

To request detection, publish a message to the regular-transactions detect topic. A user-scoped result is then published to the regular-transactions result topic.

Detect messages may contain one account or several accounts for the same user. Moneyhub configures how daily batch detection is grouped for your environment; see List of configurable features.

This mirrors the affordability interface: one userId in, one user-scoped message out per detect message processed.

Request message

The Kafka message value must be a JSON object:

Each element of accounts[]:

When asOfDate is omitted, full mode uses the configured retention window of transaction history. incremental mode uses transactions from updatedAt onwards and merges with the current series.

Dated detection

asOfDate asks for the series as they stood at the end of that calendar day, using the 12 months of stored transactions ending on that date. The whole of asOfDate is included. Transactions that have not already been submitted for those dates are not part of the run.

A dated message applies to every account in accounts[]. mode and updatedAt are not used. The run does not merge with the current series, and it does not replace them. A later detection or affordability request that omits asOfDate still uses the current series. Sending the same date again replaces the series stored for that date only.

You can omit accounts and send only userId and asOfDate. Detection then runs for every account already known for that user. If userId is missing, or the user has no accounts, the message is dead-lettered and nothing is stored.

When affordability after regular transactions is enabled, a successful dated detection also requests the affordability report for the same date. You can request that report yourself by publishing the same asOfDate to the affordability calculate topic. See Affordability schema.

If historical affordability functionality is disabled for your environment, any detect message that includes asOfDate is dead-lettered and nothing is read or stored. Messages that omit asOfDate are unchanged. A value that is not a real calendar date (yyyy-MM-dd) is rejected and is not treated as today. See Errors.

The message key should be a unique identifier (UUID recommended). It is copied to the corresponding result message.

Example (detect message — single account)

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accounts": [
    {
      "accountId": "090ea264-eb48-494c-9d59-1b10b322c3e1",
      "mode": "full"
    }
  ]
}

Example (detect message for a past date)

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "asOfDate": "2025-04-01",
  "accounts": [
    {
      "accountId": "090ea264-eb48-494c-9d59-1b10b322c3e1",
      "mode": "full"
    }
  ]
}

Example (dated detection for every account of a user)

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "asOfDate": "2025-04-01"
}

Example (detect message — multiple accounts)

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accounts": [
    {
      "accountId": "090ea264-eb48-494c-9d59-1b10b322c3e1",
      "mode": "full"
    },
    {
      "accountId": "de4be182-efb4-4aad-b221-fa29631e6653",
      "mode": "incremental",
      "updatedAt": "2026-06-01T12:00:00.000Z"
    }
  ]
}

Result topic

Detection results are published to the regular-transactions result topic. Failed messages are sent to the regular-transactions dead-letter topic; see Errors for the general dead-letter envelope shape.

Result message envelope

The Kafka message value is a JSON object:

The message key is copied from the triggering detect message when present; otherwise a new UUID is generated.

Account result (accounts[])

Series object (predictions[])

Transaction object (transactions[])

Example (result message body)

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accounts": [
    {
      "accountId": "090ea264-eb48-494c-9d59-1b10b322c3e1",
      "predictions": [
        {
          "seriesId": "45f004dc-254f-5d09-b07f-8d4de4487781",
          "accountId": "090ea264-eb48-494c-9d59-1b10b322c3e1",
          "userId": "550e8400-e29b-41d4-a716-446655440000",
          "type": "payment",
          "subtype": "frequentVisit",
          "frequency": "quarterly",
          "description": "Dentist Checkup",
          "cleanedDescription": "Dentist Checkup",
          "numTxMatchedInSeries": 4,
          "gapLengthInFreqUnits": 0,
          "dateAnomaliesCount": 0,
          "numReturnedTxs": 0,
          "lastDate": "2026-01-20",
          "predictedDate": "2026-04-20",
          "predictedDateEarliest": "2026-04-20",
          "predictedDateLatest": "2026-04-21",
          "predictedTxLateOrNotDetected": false,
          "predictedAmount": -65,
          "predictedAmountLower": -65,
          "predictedAmountUpper": -65,
          "currency": "GBP",
          "counterpartyId": "203d5a9a-d4dd-5ce5-ab60-60f740336dea",
          "predictedCategoryId": "11",
          "l3CounterpartyCategory": null,
          "transactions": [
            {
              "uid": "TXN-090ea264-775",
              "date": "2026-01-20",
              "description": "Dentist Checkup",
              "amount": -65,
              "categoryId": "11",
              "cleanedDescription": "Dentist Checkup",
              "txCode": null,
              "cardPresent": false,
              "l3CounterpartyCategory": null
            },
            {
              "uid": "TXN-090ea264-774",
              "date": "2025-10-20",
              "description": "Dentist Checkup",
              "amount": -65,
              "categoryId": "11",
              "cleanedDescription": "Dentist Checkup",
              "txCode": null,
              "cardPresent": false,
              "l3CounterpartyCategory": null
            }
          ]
        }
      ]
    },
    {
      "accountId": "de4be182-efb4-4aad-b221-fa29631e6653",
      "predictions": []
    }
  ]
}