# Moneyhub Categorisation & Enrichment Engine Documentation

> A solution designed for financial institutions that wish to have proprietary transaction data categorised and enriched to power a truly personalised user experience for their customers.

Append .md to any documentation page URL to get its markdown version.

## Guides
- [Getting Started](https://docs.enrichment-engine.moneyhubenterprise.com/docs/getting-started.md): Guides for integrating with the Categorisation & Enrichment Engine, including API, Kafka, and SFTP interfaces.
- [Product Summary](https://docs.enrichment-engine.moneyhubenterprise.com/docs/product-summary.md): Overview of the Categorisation & Enrichment Engine: ML-based categorisation, counterparty detection, geotagging, and regular transaction detection.
- [List of configurable features](https://docs.enrichment-engine.moneyhubenterprise.com/docs/list-of-configurable-features.md): Configurable options for regular transaction egress, mTLS, coverage, Kafka auth, and data retention.
- [Data retention and Lifecycle policy](https://docs.enrichment-engine.moneyhubenterprise.com/docs/data-retention-and-lifecycle-policy.md): Standard 13-month data retention policy and Trust Centre documentation.
- [Multiple versions of the same transaction](https://docs.enrichment-engine.moneyhubenterprise.com/docs/multiple-versions-of-the-same-transaction.md): How at-least-once processing and transaction state changes (pending to posted) are handled.
- [Processing of joint accounts](https://docs.enrichment-engine.moneyhubenterprise.com/docs/processing-of-joint-accounts.md): Supported patterns for processing joint accounts: duplicate transactions per user or flatten to a single user.
- [Account/Product types](https://docs.enrichment-engine.moneyhubenterprise.com/docs/accountproduct-types.md): How Retail and Business account types affect categorisation model routing.
- [Architecture](https://docs.enrichment-engine.moneyhubenterprise.com/docs/txs-architecture.md): Scaling overview and API/SFTP vs Kafka interface options.
- [Supported Interfaces](https://docs.enrichment-engine.moneyhubenterprise.com/docs/txs-supported-interfaces.md): API, Kafka, and SFTP throughput (4k TPS standard) and use cases for transaction enrichment.
- [Architecture](https://docs.enrichment-engine.moneyhubenterprise.com/docs/reg-txs-architecture.md): How the engine detects recurring income and payment patterns (weekly to yearly) via a daily batch job.
- [Supported Interfaces](https://docs.enrichment-engine.moneyhubenterprise.com/docs/reg-txs-supported-interfaces.md): API, Kafka, and SFTP options for regular series detection and batch run results.
- [Moneyhub-Hosted Apache Kafka](https://docs.enrichment-engine.moneyhubenterprise.com/docs/moneyhub-hosted-kafka.md): Topic names and schemas for transaction ingress, transaction egress, and regular series egress.
- [Key concepts](https://docs.enrichment-engine.moneyhubenterprise.com/docs/key-concepts.md): Overview of transactions, categories, counterparties, and other core concepts for the Categorisation & Enrichment Engine.
- [Transactions](https://docs.enrichment-engine.moneyhubenterprise.com/docs/transactions.md): How enriched transactions are persisted, retrieved via the API, and how to request synchronous or asynchronous enrichment.
- [Enhanced Transaction Information](https://docs.enrichment-engine.moneyhubenterprise.com/docs/enhanced-transactions.md): Retrieving transactions with enhanced location and merchant data
- [Categories](https://docs.enrichment-engine.moneyhubenterprise.com/docs/categories.md): How transactions are categorised at up to four levels, from high-level taxonomy to retailer and product type.
- [Counterparties](https://docs.enrichment-engine.moneyhubenterprise.com/docs/counterparties.md): How the engine identifies and categorises counterparties (merchants, service providers) from transaction data.
- [Regular Transactions](https://docs.enrichment-engine.moneyhubenterprise.com/docs/regular-transactions.md): How the engine detects regular transaction series from patterns and delivers them via Kafka egress or the API.
- [Users and Accounts](https://docs.enrichment-engine.moneyhubenterprise.com/docs/users-and-accounts.md): How user and account identifiers group resources and how to delete user or account data.
- [External Licences](https://docs.enrichment-engine.moneyhubenterprise.com/docs/external-licences.md): Licences for geolocation data (ODbL, OpenStreetMap, Who's on First, Geonames) and Google Places API.
- [Useful Links and information](https://docs.enrichment-engine.moneyhubenterprise.com/docs/useful-links-and-information.md): Trust centre, PFM API, and Payments API documentation links.
- [Summary](https://docs.enrichment-engine.moneyhubenterprise.com/docs/summary.md): Overview of Authentication (who you are), Authorisation (what you can do), and Accounting (what you did) with Moneyhub.
- [API Authentication & Authorisation](https://docs.enrichment-engine.moneyhubenterprise.com/docs/api-authn-authz.md): Overview of OIDC, JWT, mTLS, and the difference between authentication and authorisation.
- [JSON Webkeys(JWK, JWKS and JWT)](https://docs.enrichment-engine.moneyhubenterprise.com/docs/json-webkeys-and-keystores.md): Introduction to JWK, JWKS, and JWT: key types, algorithms, and their use in API authentication.
- [Creating a JWKS](https://docs.enrichment-engine.moneyhubenterprise.com/docs/creating-jwks.md): How to create a JWKS, including using the Node.js Moneyhub API library and other language options.
- [Understanding your JWKS](https://docs.enrichment-engine.moneyhubenterprise.com/docs/understanding-jwks.md): How to distinguish public vs private JWKS and which parameters indicate a private key.
- [Storing your JWKS](https://docs.enrichment-engine.moneyhubenterprise.com/docs/storing-jwks.md): Securely storing private keys in environment variables, KMS, or encrypted config; never commit plain-text keys.
- [Sharing your Public JWKS](https://docs.enrichment-engine.moneyhubenterprise.com/docs/sharing-public-jwks.md): Two ways to provide your public keyset to Moneyhub: JWKS endpoint URI or raw JWKS in Admin Portal.
- [Why use JWKS Endpoints](https://docs.enrichment-engine.moneyhubenterprise.com/docs/jwks-endpoints.md): Why to serve a public JWKS endpoint and key principles for sharing public keys with Moneyhub.
- [Ways of serving a JWKS Endpoints](https://docs.enrichment-engine.moneyhubenterprise.com/docs/serving-a-jwks-endpoint.md): Options for serving a JWKS endpoint: managed IdP, self-hosted application, or API gateway.
- [Other methods of sharing your public JWKS with Moneyhub](https://docs.enrichment-engine.moneyhubenterprise.com/docs/raw-jwks.md): Providing public JWKS via endpoint URI or copy-paste in the Admin Portal client configuration.
- [JWKS Key Rotation](https://docs.enrichment-engine.moneyhubenterprise.com/docs/jwks-key-rotation.md): How to rotate signing keys using a JWKS endpoint and how Moneyhub resolves keys by kid and alg.
- [Clients and how to create one](https://docs.enrichment-engine.moneyhubenterprise.com/docs/create-a-client.md): This page covers why Moneyhub has clients, what they are and how to create one.
- [API Authentication](https://docs.enrichment-engine.moneyhubenterprise.com/docs/api-authentication.md): Key-based authentication, Private Key JWT, optional mTLS, and Admin Portal client configuration.
- [Authentication fundamentals](https://docs.enrichment-engine.moneyhubenterprise.com/docs/oidc-for-authentication.md): OIDC discovery, recommended specs (OpenID Connect, FAPI), and Moneyhub identity base URL.
- [Authenticating on the Token Endpoint](https://docs.enrichment-engine.moneyhubenterprise.com/docs/authenticating-on-the-token-endpoint.md): How to authenticate at the token endpoint using client_secret_basic or private_key_jwt (JWT assertion).
- [Mutual TLS](https://docs.enrichment-engine.moneyhubenterprise.com/docs/mutal-tls.md): mTLS is an extension of the standard TLS protocol that provides enhanced security by requiring both the client and server in a communication session to authenticate each other's certificates. In the financial sector, where the integrity of transactions is paramount, mTLS ensures that only verified clients can initiate requests, thereby safeguarding against unauthorised access.
- [API Authorisation](https://docs.enrichment-engine.moneyhubenterprise.com/docs/api-authorisation.md): Access token scoping, least privilege, and available CaaS scopes for transactions and related data.
- [Obtaining a client credentials access token](https://docs.enrichment-engine.moneyhubenterprise.com/docs/client-credentials.md): How to request client_credentials tokens with caas scopes and token endpoint authentication.
- [Authentication & Authorisation errors](https://docs.enrichment-engine.moneyhubenterprise.com/docs/authentication-errors.md): OAuth 2.0 error codes returned from the token endpoint (invalid_request, invalid_client, invalid_grant, etc.).
- [Kafka Authentication & Authorisation](https://docs.enrichment-engine.moneyhubenterprise.com/docs/kafka-authentication-authorisation.md): mTLS-only authentication for Moneyhub-hosted Kafka and ACL-based authorisation for ingress and egress topics.
- [Admin Portal Authentication & Authorisation](https://docs.enrichment-engine.moneyhubenterprise.com/docs/admin-portal.md): The Admin Portal is a portal for solution configuration
- [Signing up](https://docs.enrichment-engine.moneyhubenterprise.com/docs/signing-up.md): How to sign up to the Admin Portal (Google, GitHub, or email) and obtain access to create API clients.
- [Accounting](https://docs.enrichment-engine.moneyhubenterprise.com/docs/accounting.md): Rate limiting for API and Kafka, and auditing of system actions.
- [API Rate Limiting](https://docs.enrichment-engine.moneyhubenterprise.com/docs/api-rate-limiting.md): Per-client request limits (e.g. 1000/min), 429 responses, and how to respond to rate limiting.
- [End point packages](https://docs.enrichment-engine.moneyhubenterprise.com/docs/api-summary.md): Core API packages and endpoint reference for the Categorisation & Enrichment Engine.
- [Transaction Enrichment Ingress & Egress](https://docs.enrichment-engine.moneyhubenterprise.com/docs/txs-enrich-ingress-egress.md): This section documents the expected message input format and output formats.  They are consistent across all interfaces provided, API, Kafka and SFTP.
- [Ingress Message Format](https://docs.enrichment-engine.moneyhubenterprise.com/docs/ingress-message-format.md): Required and optional fields for transaction messages sent to the Kafka ingress topic.
- [Egress Message Format](https://docs.enrichment-engine.moneyhubenterprise.com/docs/egress-message-format.md): Schema for enriched transaction messages produced to the Kafka egress topic.
- [Regular Transactions Schema](https://docs.enrichment-engine.moneyhubenterprise.com/docs/regular-transactions-schema-for-egress.md): Field reference for user-scoped regular transaction series detect and result messages on Kafka.
- [Affordability Schema](https://docs.enrichment-engine.moneyhubenterprise.com/docs/affordability-result-schema.md): Field reference for user-scoped affordability calculate and result messages on Kafka.
- [Reference Data](https://docs.enrichment-engine.moneyhubenterprise.com/docs/reference-data.md): Reference schemas for counterparty and geotag data used across the solution.
- [Counterparty Schema](https://docs.enrichment-engine.moneyhubenterprise.com/docs/counterparty-schema.md): Field reference for counterparty (merchant) data in enriched output.
- [Geotag Schema](https://docs.enrichment-engine.moneyhubenterprise.com/docs/geotag-schema.md): Field reference for geotag (location) data in enriched output.
- [Errors](https://docs.enrichment-engine.moneyhubenterprise.com/docs/errors.md): Schema and handling of transaction errors (source, code, cause), dead-letter topic message formats, and how to resolve and replay failed transactions.
- [SFTP Summary](https://docs.enrichment-engine.moneyhubenterprise.com/docs/sftp-summary.md): Push and pull SFTP file transfer, supported formats (Parquet, JSON Lines, CSV), and schema alignment.

## API Reference
- [Retrieve an access token](https://docs.enrichment-engine.moneyhubenterprise.com/reference/post_oidc-token.md): Obtain a client credentials access token using `private_key_jwt` authentication.
- [OpenID Connect discovery](https://docs.enrichment-engine.moneyhubenterprise.com/reference/get_oidc-well-known-openid-configuration.md): Returns the OpenID Connect discovery document (issuer, `token_endpoint`, supported grant types, scopes, signing algorithms, and related metadata).
- [Delete all user data](https://docs.enrichment-engine.moneyhubenterprise.com/reference/delete_users-userid.md): Requires the caas:users:delete scope. Delete all enrichment data for an user ID (customer) including transactions, regular transactions and custom categories
- [Delete all account data](https://docs.enrichment-engine.moneyhubenterprise.com/reference/delete_accounts-accountid.md): Requires the caas:users:delete scope. Delete all enrichment data for an account ID including transactions, regular transactions and custom categories
- [Retrieve all standard categories](https://docs.enrichment-engine.moneyhubenterprise.com/reference/get_categories.md): Requires the caas:categories:read scope. Retrieves all standard categories that could be applied to the enriched transactions
- [Retrieve all category groups](https://docs.enrichment-engine.moneyhubenterprise.com/reference/get_category-groups.md): Requires the caas:categories:read scope. Retrieves all category groups
- [Retrieve all custom categories for a user](https://docs.enrichment-engine.moneyhubenterprise.com/reference/get_users-userid-custom-categories.md): Requires the caas:categories:read scope. Retrieves all custom categories created by the user.
- [Create a custom category for a user](https://docs.enrichment-engine.moneyhubenterprise.com/reference/post_users-userid-custom-categories.md): Requires the caas:categories:write scope. Creates a new custom category for the user. The returned category ID can be used as the userCategoryId when updating a transaction via PATCH.
- [Delete a custom category](https://docs.enrichment-engine.moneyhubenterprise.com/reference/delete_users-userid-custom-categories-categoryid.md): Requires the caas:categories:delete scope. Deletes a custom category.
- [Retrieve counterparties](https://docs.enrichment-engine.moneyhubenterprise.com/reference/get_counterparties.md): Requires the caas:transactions:read scope. Retrieves list of counterparties
- [Retrieve geotags](https://docs.enrichment-engine.moneyhubenterprise.com/reference/get_geotags.md): Requires the caas:transactions:read scope. Retrieve one or more geotags by their IDs specified in the query parameters.
- [Retrieve regular transactions](https://docs.enrichment-engine.moneyhubenterprise.com/reference/get_accounts-accountid-regular-transactions.md): Requires the caas:regular_transactions:read scope. Retrieves all regular transactions for an account.
- [Retrieve enriched transactions](https://docs.enrichment-engine.moneyhubenterprise.com/reference/get_transactions.md): Requires the caas:transactions:read scope. Retrieve all enriched transactions for a user or account. Either accountId or userId are mandatory to retrieve transactions. The `splits` field is included only when the client holds the caas:transaction_splits:read scope.
- [Update an enriched transaction](https://docs.enrichment-engine.moneyhubenterprise.com/reference/patch_accounts-accountid-transactions-transactionid.md): 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.
- [Delete all data for a single transaction](https://docs.enrichment-engine.moneyhubenterprise.com/reference/delete_accounts-accountid-transactions-transactionid.md): Requires the caas:transactions:delete scope. Delete all enrichment data for a transaction ID
- [Enrich transactions](https://docs.enrichment-engine.moneyhubenterprise.com/reference/post_transactions-enrich.md): Requires the caas:transactions:write scope. Upload transactions to be enriched by Moneyhub's Data Enrichment Engine
- [Retrieve enhanced location data](https://docs.enrichment-engine.moneyhubenterprise.com/reference/get_accounts-accountid-transactions-transactionid-enhanced.md): Requires the caas:enhanced_transactions:read scope. Retrieve enhanced location and merchant data for a transaction ID. This will fetch additional data from Google. Please note that the data returned from Google should not be cached or stored. This is a premium endpoint and incurs a cost per request.
- [Upsert transaction splits](https://docs.enrichment-engine.moneyhubenterprise.com/reference/put_accounts-accountid-transactions-transactionid-splits.md): Requires the caas:transaction_splits:write scope. Creates or replaces all splits for a transaction. Requires between 2 and 10 splits. The total of all split amounts must equal the parent transaction `amount`.
- [Delete transaction splits](https://docs.enrichment-engine.moneyhubenterprise.com/reference/delete_accounts-accountid-transactions-transactionid-splits.md): Requires the caas:transaction_splits:delete scope. Removes all splits from a transaction.