--- updatedAt: 2026-06-30T09:11:39.000Z agentTools: projectIndex: https://docs.enrichment-engine.moneyhubenterprise.com/llms.txt --- # Update an enriched transaction Requires the **caas:transactions:write** scope. Recategorise a single enriched transaction by setting a `userCategoryId`. Use the `recategorisationType` query parameter to control scope: `single` (this transaction only), `future` (this transaction and all future matching transactions), or `past-and-future` (this transaction, a future matching rule, and asynchronous recategorisation of matching historical transactions). The PATCH response returns immediately with the updated target transaction; when using `past-and-future`, historical recategorisation is processed asynchronously. A transaction with active splits, identified by its `userCategoryId` being set to the `mixed` category, cannot be recategorised: the request returns `409 Conflict`. Clear the splits with **DELETE /accounts/{accountId}/transactions/{transactionId}/splits** before recategorising. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "description": "Documentation for the Categorisation & Enrichment Engine API.", "title": "Moneyhub Categorisation & Enrichment Engine API", "version": "1.0.0", "x-build-sha": "0cafcb5" }, "externalDocs": { "description": "Developer Hub", "url": "https://docs.enrichment-engine.moneyhubenterprise.com" }, "servers": [ { "url": "https://api.moneyhub.co.uk/caas/v1" } ], "security": [ { "Bearer": [] } ], "paths": { "/accounts/{accountId}/transactions/{transactionId}": { "patch": { "operationId": "patch_accounts-accountid-transactions-transactionid", "summary": "Update an enriched transaction", "description": "Requires the **caas:transactions:write** scope. Recategorise a single enriched transaction by setting a `userCategoryId`. Use the `recategorisationType` query parameter to control scope: `single` (this transaction only), `future` (this transaction and all future matching transactions), or `past-and-future` (this transaction, a future matching rule, and asynchronous recategorisation of matching historical transactions). The PATCH response returns immediately with the updated target transaction; when using `past-and-future`, historical recategorisation is processed asynchronously. A transaction with active splits, identified by its `userCategoryId` being set to the `mixed` category, cannot be recategorised: the request returns `409 Conflict`. Clear the splits with **DELETE /accounts/{accountId}/transactions/{transactionId}/splits** before recategorising.", "parameters": [ { "$ref": "#/components/parameters/AccountIdPath" }, { "$ref": "#/components/parameters/TransactionId" }, { "in": "query", "name": "recategorisationType", "required": false, "description": "Controls recategorisation scope. `single`: this transaction only. `future`: this transaction and future matching transactions. `past-and-future`: this transaction, a future matching rule, and matching historical transactions. The PATCH response reflects only the target transaction; historical updates for `past-and-future` are processed asynchronously.", "schema": { "type": "string", "enum": [ "single", "future", "past-and-future" ] } } ], "responses": { "200": { "description": "Successful Transactions Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "$ref": "#/components/schemas/EnrichedTransaction" }, "meta": { "$ref": "#/components/schemas/CorrelationMeta" }, "links": { "$ref": "#/components/schemas/SelfLink" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorisedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "description": "Unsuccessful Response - Conflict - the transaction has active splits and cannot be recategorised", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "example": { "code": "Conflict", "message": "Cannot change the category of a transaction with active splits; use DELETE /splits to clear them first", "correlationId": "c390a94f-3824-4cdf-8d02-b0c5304d9f66" } } ] } } } } }, "tags": [ "transactions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionPatch" } } } } } } }, "components": { "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer", "description": "When authorising in this API documentation, enter only the token value. The Bearer prefix is added automatically." } }, "parameters": { "AccountIdPath": { "name": "accountId", "in": "path", "description": "The account ID as specified on the transaction", "required": true, "example": "0b4e6488-6de0-420c-8f56-fee665707d57", "schema": { "type": "string", "minLength": 8, "maxLength": 36, "pattern": "^[a-zA-Z0-9_-]+$" } }, "TransactionId": { "name": "transactionId", "in": "path", "description": "The Transaction ID", "required": true, "example": "0b4e6488-6de0-420c-8f56-fee665707d57", "schema": { "type": "string", "minLength": 8, "maxLength": 40, "pattern": "^[a-zA-Z0-9_-]+$" } } }, "schemas": { "Category": { "description": "The l2 category.", "properties": { "l2CategoryId": { "description": "The ID of the level 2 category.", "example": "22", "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31", "32", "33", "34", "35", "36", "37", "38", "39", "40", "41", "42", "43", "44", "45", "92", "94", "96", "98", "100", "102", "104", "106", "108", "110", "112", "114", "115", "116", "117", "118", "119", "120", "255", "mixed" ] }, "l2CategoryName": { "description": "The name of the level 2 category", "example": "eating-out", "type": "string", "enum": [ "automotive", "charitable", "clothing", "education", "entertainment", "gasoline", "groceries", "healthcare", "home-maintenance", "home-improvement", "insurance", "cable", "online", "loans", "mortgages", "other", "personal", "rent", "eating-out", "travel", "service", "ATM", "cheques", "hobbies", "other-bills", "telephone", "utilities", "pets", "electronics", "general", "office-supplies", "child", "taxes", "gifts", "advertising", "business", "postage", "printing", "dues", "office-maintenance", "wages", "gambling", "transfers", "savings", "credit", "securities", "other-income", "paychecks", "investment", "retirement", "interest", "expense", "benefits", "rental-income", "pension-contributions", "pension-withdrawals", "investments", "services", "dividends", "mixed", "consulting", "deposits", "sales", "rewards", "uncategorized" ] }, "l1CategoryGroupId": { "description": "The ID of the level 1 category group to which the category belongs", "example": "4", "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16" ] }, "l1CategoryGroupName": { "description": "The name of the level 1 category group", "example": "entertainment", "type": "string", "enum": [ "bills", "business", "cash", "entertainment", "gifts", "shopping", "health", "household", "income", "other", "rent", "taxes", "transfers", "transport", "repayments", "mixed" ] } }, "type": "object" }, "CategoryGroup": { "description": "The l1 category.", "properties": { "l1CategoryGroupId": { "description": "The level 1 category group to which the category belongs", "example": "4", "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16" ] }, "l1CategoryGroupName": { "description": "The Name of the level 1 category group", "example": "entertainment", "type": "string", "enum": [ "bills", "business", "cash", "entertainment", "gifts", "shopping", "health", "household", "income", "other", "rent", "taxes", "transfers", "transport", "repayments", "mixed" ] }, "l1CategoryType": { "description": "The type of the level 1 category group", "example": "expense", "type": "string", "enum": [ "expense", "income", "transfer", "deferred", "mixed", "uncategorize" ] } }, "type": "object" }, "Counterparty": { "additionalProperties": false, "type": "object", "description": "A counterparty is a business or organisation that has been identified as a counterparty to a transaction.", "properties": { "l3CounterpartyId": { "type": "string", "description": "The unique identifier for the counterparty.", "format": "uuid", "maxLength": 36, "example": "a2c7b1e3-b9ce-5c61-9eb1-be897c04cee0" }, "l3CounterpartyName": { "type": "string", "description": "Name of the counterparty", "maxLength": 128, "example": "Tesco Mobile" }, "parentId": { "type": "string", "description": "The unique identifier for the counterparty parent", "maxLength": 36, "example": "26c417bc-248f-5e3f-9835-3cd9c2842f50", "nullable": true }, "parentName": { "type": "string", "description": "Name of the counterparty parent", "maxLength": 36, "example": "Tesco", "nullable": true }, "fullCompanyName": { "type": "string", "description": "Company name", "maxLength": 128, "example": "Tesco Stores Limited", "nullable": true }, "logoUrl": { "type": "string", "description": "Logo Url of counterparty", "maxLength": 128, "example": "https://s3.eu-west-1.amazonaws.com/mft-counterparty-logos-prod/7e43257eac60348110bd15cc.svg", "nullable": true }, "website": { "type": "string", "description": "Website url of counterparty", "maxLength": 512, "example": "https://www.tescomobile.com", "nullable": true }, "registeredLocation": { "type": "string", "description": "Registered address of company", "maxLength": 128, "example": "17-21 Wenlock Road, London N1 7G", "nullable": true }, "l3CounterpartyCategory": { "type": "string", "description": "Category used to group similar counterparties", "maxLength": 32, "example": "mobile-phone" }, "l2CategoryName": { "type": "string", "description": "Most appropriate transaction category name for transactions to this counterparty", "maxLength": 32, "example": "telephone" }, "l4LoanType": { "type": "string", "description": "The level 4 loan type. Only present for loan provider counterparties", "enum": [ "Unsecured", "Secured", "Secured Vehicle", "Buy Now Pay Later", "High Cost Short Term Credit", "Debt Collection Agency/Debt Management Plan" ], "example": "Secured", "nullable": true } }, "required": [ "l3CounterpartyId" ], "example": { "l3CounterpartyId": "a7920ee2-62f4-5465-84eb-af6ef1f7074a", "l3CounterpartyName": "J P Morgan Chase", "parentId": null, "parentName": null, "fullCompanyName": "J P MORGAN CHASE & CO.", "logoUrl": "https://s3.eu-west-1.amazonaws.com/mft-counterparty-logos-prod/55faa0f4226fe84c78e011df.svg", "website": "https://www.jpmorganchase.com/", "registeredLocation": "25 Bank Street, London, United Kingdom", "l3CounterpartyCategory": "bank", "l2CategoryName": "investment" } }, "Geotag": { "additionalProperties": false, "type": "object", "properties": { "geotagId": { "type": "string", "description": "Unique identifier for geotag.", "maxLength": 36, "example": "868c58c9-7149-3fc0-bd39-cc29e52a3270" }, "counterpartyName": { "type": "string", "description": "Name of counterparty (brand).", "maxLength": 128, "nullable": true, "example": "WHSmith" }, "counterpartyLabel": { "type": "string", "description": "Name and short address of counterparty.", "maxLength": 128, "nullable": true, "example": "WHSmith, Southampton, Hampshire, United Kingdom" }, "houseNumber": { "type": "string", "description": "The building number.", "maxLength": 128, "nullable": true, "example": "123" }, "street": { "type": "string", "description": "Street the building is located on.", "maxLength": 128, "nullable": true, "example": "High Street" }, "neighbourhood": { "type": "string", "description": "Commonly a district within a town.", "maxLength": 128, "nullable": true, "example": "Shirley" }, "locality": { "type": "string", "description": "City, town or village.", "maxLength": 128, "nullable": true, "example": "Southampton" }, "city": { "type": "string", "description": "City. Can be the same value as locality.", "maxLength": 128, "nullable": true, "example": "Southampton" }, "county": { "type": "string", "description": "County. Can be the same value as city.", "maxLength": 128, "nullable": true, "example": "Southampton" }, "region": { "type": "string", "description": "Region. Can be the same value as county.", "maxLength": 128, "nullable": true, "example": "Hampshire" }, "postcode": { "type": "string", "description": "Postcode of geotag. We estimate this in the event it wasn't provided by the data source we use by considering surrounding geotags that have a postcode. While the field is optional, it's very rare we don't return it.", "maxLength": 64, "nullable": true, "example": "SO16 6YD" }, "latitude": { "type": "number", "description": "WGS84 latitude.", "nullable": true, "example": 50.933221, "multipleOf": 0.000001 }, "longitude": { "type": "number", "description": "WGS84 longitude.", "nullable": true, "example": -1.434414, "multipleOf": 0.000001 }, "l3CounterpartyCategory": { "type": "string", "description": "The name of the level 3 category (industry).", "maxLength": 32, "nullable": true, "example": "retailer" }, "postcodeEstimated": { "type": "boolean", "description": "True if we've estimated the postcode by considering surrounding geotags.", "example": true }, "postcodeErrorKm": { "type": "number", "format": "float", "description": "If we've estimated the postcode, the distance the location is from the geotag we used to estimate the postcode.", "nullable": true, "example": 0.014 } }, "required": [ "geotagId", "counterpartyName", "counterpartyLabel", "latitude", "longitude", "postcodeEstimated" ] }, "TransactionPatch": { "additionalProperties": false, "type": "object", "required": [ "userCategoryId" ], "properties": { "userCategoryId": { "type": "string", "description": "The category to assign to this transaction. Accepts a custom category UUID or a standard Moneyhub L2 category ID (e.g. \"22\"). The reserved system category \"mixed\" cannot be assigned: it is applied automatically once the transaction has splits, to signal the transaction is divided across multiple categories.", "example": "041e52b3-4011-4847-9d4b-f4bcf3385fea", "minLength": 1, "maxLength": 36, "pattern": "^[a-zA-Z0-9:-]+$" } } }, "Transaction": { "type": "object", "additionalProperties": false, "properties": { "userId": { "type": "string", "description": "Unique identifier for the customer/user.", "minLength": 8, "maxLength": 36, "pattern": "^[a-zA-Z0-9_-]+$", "nullable": true, "example": "0b4e6488-6de0-420c-8f56-fee665707d57" }, "accountId": { "type": "string", "description": "Unique identifier for the account.", "minLength": 8, "maxLength": 36, "pattern": "^[a-zA-Z0-9_-]+$", "example": "0b4e6488-6de0-420c-8f56-fee665707d58" }, "transactionId": { "type": "string", "description": "Unique identifier for the transaction.", "minLength": 8, "maxLength": 40, "pattern": "^[a-zA-Z0-9_-]+$", "example": "0b4e6488-6de0-420c-8f56-fee665707d59" }, "accountType": { "type": "string", "description": "The account type. Permitted values as follows: 'cash' - current accounts; 'card' - credit cards; 'savings' - savings accounts; 'investment' - investment accounts; 'loan' - loan accounts; 'mortgage' - mortgage accounts; 'pension' - pension accounts", "enum": [ "cash", "card", "savings", "investment", "loan", "mortgage", "pension" ], "example": "cash" }, "txCode": { "type": "string", "description": "The transaction code. Permitted values as follows: 'DEB' - general debit card transaction; 'CR' - general bank credit; 'TFR' - general transfer to/from; ')))' - contactless purchase; 'DD' - direct debit; 'SO' - standing order; 'BGC' - bank giro credit; 'ATM' - cash withdrawal; 'CHQ' - cheque; 'CHG' - bank charge. For credit card transactions or if unsure for a transaction set to the empty string. Although we do accept more codes; please supply us a list of the transaction codes you'd like to use and we'll either let you know if they are supported or how you can map onto our transaction codes.", "minLength": 0, "maxLength": 64, "nullable": true, "example": "DEB" }, "date": { "type": "string", "format": "date-time", "description": "The date and time of the transaction in ISO 8601 format.", "maxLength": 35, "example": "2025-04-29T10:51:34.747Z" }, "status": { "type": "string", "description": "The status of the transaction: e.g. pending, posted (booked)", "enum": [ "pending", "posted" ], "example": "posted" }, "description": { "type": "string", "description": "The transaction description which is commonly a combination of the merchant name and merchant location.", "maxLength": 256, "example": "TESCO STORES 1234 LONDON" }, "amount": { "type": "number", "description": "The transaction amount in major units of the currency.", "example": -60 }, "currency": { "type": "string", "description": "The currency of the transaction e.g. GBP, EUR. Defaults to GBP", "default": "GBP", "maxLength": 3, "example": "GBP" }, "balance": { "type": "number", "description": "The running account balance after this transaction has been applied, in major units of the currency. Optional; when supplied it is used by downstream insight modules (e.g. low balance and overdraft detection).", "nullable": true, "example": -60 }, "merchantCategoryCode": { "type": "string", "description": "MCC code for the merchant's primary activities. A maximum 4 digit string which we will left pad with 0s to make 4 digits if necessary.", "maxLength": 4, "nullable": true, "example": "5411" }, "cardPresent": { "type": "boolean", "description": "Indicates if the cardholder was present when the transaction occurred. Note that, online purchases are considered card holder not present. Only card holder present transactions are eligible for geotagging. Commonly derived from the POS entry mode: e.g. '07' is contactless chip read so card present. Do not specify or set to true if unknown/unsure; the engine uses this field as part of the estimation of a more accurate card present flag.", "nullable": true, "example": true }, "meta": { "type": "object", "description": "Optional object containing additional data about the transaction. This can be used to store additional information about the transaction.", "additionalProperties": true, "nullable": true, "example": null } } }, "EnrichedTransaction": { "additionalProperties": false, "type": "object", "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "$ref": "#/components/schemas/MhInsights" } ], "properties": { "splits": { "type": "array", "minItems": 2, "description": "The transaction splits. Only present when the client holds the **caas:transaction_splits:read** scope and the transaction has been split. Requires a minimum of 2 splits; the sum of split amounts must equal the parent transaction `amount`.", "items": { "$ref": "#/components/schemas/TransactionSplit" } } }, "required": [ "userId", "transactionId", "accountId", "accountType", "date", "status", "description", "amount", "currency", "cardPresent", "merchantCategoryCode", "txCode", "meta", "mhInsights" ] }, "TransactionSplit": { "additionalProperties": false, "type": "object", "properties": { "amount": { "type": "number", "description": "The split amount in major units of the parent transaction currency (e.g. -40.00 for £40.00 out). Negative means money going out of an account, positive means money coming into an account.", "example": -40 }, "userCategoryId": { "type": "string", "description": "The category assigned to this split. A custom category UUID or a standard Moneyhub L2 category ID (e.g. \"22\"). Never the reserved system category \"mixed\": that applies to the parent transaction, not to individual splits.", "example": "22", "minLength": 1, "maxLength": 36, "pattern": "^[a-zA-Z0-9:-]+$" }, "description": { "description": "A description of the transaction split", "example": "Food", "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[^<>]+$" } }, "required": [ "amount", "userCategoryId", "description" ] }, "MhInsightsCore": { "type": "object", "properties": { "l3Counterparty": { "$ref": "#/components/schemas/Counterparty", "nullable": true }, "geotags": { "type": "array", "description": "Up to 3 candidate locations where the transaction could have taken place ordered from most likely to least likely.", "items": { "$ref": "#/components/schemas/Geotag" } }, "cardPresent": { "type": "boolean", "description": "Indicates if the cardholder was present when the transaction occurred. Note that, online purchases are considered card holder not present. Only card holder present transactions are eligible for geotagging. We estimate this field from the transaction data.", "nullable": true }, "userCategoryId": { "type": "string", "description": "The category assigned to this transaction. A custom category UUID or a standard Moneyhub L2 category ID (e.g. \"22\"). The reserved system category \"mixed\" is applied automatically once the transaction has splits, to signal the transaction is divided across multiple categories.", "nullable": true, "example": "041e52b3-4011-4847-9d4b-f4bcf3385fea", "minLength": 1, "maxLength": 36, "pattern": "^[a-zA-Z0-9:-]+$" } } }, "MhInsightsTimestamps": { "type": "object", "properties": { "timestampCreated": { "type": "string", "format": "date-time", "maxLength": 24, "description": "Timestamp of when message containing the transaction was created on the Kafka raw ingest topic i.e. the topic that the Data Enrichment Engine retrieves messages from. For the API interface this is effectively when the transaction was sent to the API." }, "timestampIngress": { "type": "string", "format": "date-time", "maxLength": 24, "description": "Timestamp of when a transaction started being processed." }, "timestampEgress": { "type": "string", "format": "date-time", "maxLength": 24, "description": "Timestamp set on transaction when processing has finished and it is about to be sent to the egress topic, and in the API case sent back as the response." } } }, "MhInsightsPayload": { "type": "object", "description": "Contains the insights from Moneyhub's Data Enrichment Engine.", "allOf": [ { "$ref": "#/components/schemas/MhInsightsCore" }, { "$ref": "#/components/schemas/CategoryGroup" }, { "$ref": "#/components/schemas/Category" }, { "$ref": "#/components/schemas/MhInsightsTimestamps" } ], "required": [ "l2CategoryId", "cardPresent", "timestampCreated", "timestampIngress", "timestampEgress" ] }, "MhInsights": { "type": "object", "properties": { "mhInsights": { "$ref": "#/components/schemas/MhInsightsPayload" } } }, "Error": { "additionalProperties": false, "properties": { "code": { "description": "The error code", "type": "string" }, "message": { "description": "The error message", "type": "string" }, "correlationId": { "description": "Id that identifies the request and can be used to ask for more details related to the error", "type": "string" } }, "required": [ "code", "message", "correlationId" ], "type": "object" }, "SelfLink": { "type": "object", "additionalProperties": false, "properties": { "self": { "description": "The url of the current resource", "format": "uri", "type": "string" } }, "required": [ "self" ] }, "CorrelationMeta": { "type": "object", "additionalProperties": false, "properties": { "correlationId": { "type": "string", "description": "The correlation ID for the request" } }, "required": [ "correlationId" ] } }, "responses": { "BadRequestResponse": { "description": "Unsuccessful Response - Bad request", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "example": { "code": "BadRequest", "message": "Missing or invalid request parameter", "correlationId": "c390a94f-3824-4cdf-8d02-b0c5304d9f66" } } ] } } } }, "UnauthorisedResponse": { "description": "Unsuccessful Response - Not authorised - Missing authorisation header - Invalid access Token", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "example": { "code": "Unauthorized", "message": "Missing authorization header", "correlationId": "c390a94f-3824-4cdf-8d02-b0c5304d9f66" } } ] } } } }, "ForbiddenResponse": { "description": "Unsuccessful Response - Forbidden - Invalid scopes", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "example": { "code": "Forbidden", "message": "Invalid scopes", "correlationId": "c390a94f-3824-4cdf-8d02-b0c5304d9f66" } } ] } } } }, "NotFoundResponse": { "description": "Unsuccessful Response - Resource not found", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "example": { "code": "NotFound", "message": "The requested resource was not found", "correlationId": "c390a94f-3824-4cdf-8d02-b0c5304d9f66" } } ] } } } } } } } ```