---
updatedAt: 2026-05-07T15:57:00.000Z
---
# Categorise Transactions
Enrich transaction data using the Categorisation endpoint.
### Formatting Requirements
To ensure accurate processing and categorisation, please adhere to the following formatting rules when submitting transaction data:
1. Amount Sign Convention:
1. Credit (Incoming transactions): must be **negative** 🚨
2. Debit (Outgoing transactions): must be **positive** 🚨
```
{
"original_description": "Salary Payment",
"amount": -5000.00 // Credit
}
{
"original_description": "Noggin Store",
"amount": 150.75 // Debit
}
```
This convention is required for correct transaction direction detection and downstream categorisation.
2. Date Format:
1. Dates must be provided in the following format: **YYYY-MM-DD** 🚨
2. No other date formats are supported
Failure to follow these conventions may result in incorrect categorisation or rejected requests.
### Optional Fields
To enhance categorisation accuracy, you should include the following additional contextual fields in your request payload.
1. Customer Name: The name of the customer as it appears on the account.
2. Account Information: A list of bank accounts associated with the provided transactions.
Note: Omitting these fields will result in reduced accuracy.
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "Noggin API"
},
"servers": [
{
"url": "https://sandbox.api.nogginhq.com"
}
],
"paths": {
"/api/v1/categorisation": {
"post": {
"description": "Enrich transaction data using the Categorisation endpoint.",
"responses": {
"200": {
"description": "Ok. Returns categorised transactions",
"content": {
"application/json": {
"examples": {
"OK": {
"summary": "OK",
"value": "{\n \"statusCode\": 200,\n \"message\": \"Categorisation completed successfully.\",\n \"request_id\": \"0bde6474-f7aa-4b17-b38a-5510d0d9dde1\",\n \"data\": [\n {\n \"application_id\": \"44c76272-886b-4387-9da6-52e2b33a5667\",\n \"user_id\": \"a39656fa-1383-43c4-a8a9-47a0f486ed56\",\n \"original_description\": \"WWW.NWL.CO.UK\",\n \"amount\": 462.68,\n \"date\": \"2024-08-20\",\n \"noggin_merchant_name\": \"Northumbrian Water\",\n \"noggin_primary\": \"Utilities\",\n \"noggin_subcategory\": \"Water\",\n },\n {\n \"application_id\": \"44c76272-886b-4387-9da6-52e2b33a5667\",\n \"user_id\": \"a39656fa-1383-43c4-a8a9-47a0f486ed56\",\n \"original_description\": \"Jac's\",\n \"amount\": 3.75,\n \"date\": \"2025-01-21\",\n \"noggin_merchant_name\": \"Jac's\",\n \"noggin_primary\": \"Food & Drinks\",\n \"noggin_subcategory\": \"Coffee, Cafes & Bakeries\",\n },\n {\n \"application_id\": \"44c76272-886b-4387-9da6-52e2b33a5667\",\n \"user_id\": \"a39656fa-1383-43c4-a8a9-47a0f486ed56\",\n \"original_description\": \"SALARY PAYROLL - SPARROW MARKETING LTD\",\n \"amount\": -965.27,\n \"date\": \"2023-06-20\",\n \"noggin_merchant_name\": \"\",\n \"noggin_primary\": \"Income\",\n \"noggin_subcategory\": \"Wage\",\n }\n ],\n}"
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {}
},
"401": {
"description": "Unauthorized",
"content": {}
}
},
"parameters": [
{
"in": "header",
"name": "x-api-key",
"schema": {
"type": "string"
},
"description": "The API key provided for the Categorisation endpoint.",
"required": true
}
],
"summary": "Categorise Transactions",
"operationId": "post_api-v1-categorisation",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customer_name": {
"type": "string",
"description": "The name of the customer as it appears on the account. This is an optional field which can improve the categorisation of transactions.",
"default": "Millicent Fawcett"
},
"accounts": {
"type": "array",
"items": {
"properties": {
"account_reference": {
"type": "string",
"description": "Unique reference for the account within your system or your data provider. Used to correlate accounts across requests/responses. This identifier should be present within each transaction object that belongs to this account in the transactions array on the request."
},
"institution_name": {
"type": "string",
"description": "The name of the financial institution that holds the account."
},
"names_on_account": {
"type": "array",
"description": "Names of the account holder(s) exactly as they appear on the account. Include all joint holders where applicable.",
"items": {
"type": "string"
}
},
"account_type": {
"type": "integer",
"description": "Account ownership type. Only the values listed below are accepted.\n\nEnum values:\n0 — personal: Account held by a single individual.\n1 — business: Account held by a business entity.\n2 — joint: Account held by multiple individuals.",
"enum": [
0,
1,
2
]
},
"account_subtype": {
"type": "integer",
"description": "Account product category. Only the values listed below are accepted.\n\nEnum values:\n0 — checking: Current/checking account used for day-to-day transactions.\n1 — credit card: Credit card account.\n2 — savings: Savings account intended for saving money.\n3 — loans: Loan/borrowing account.\n4 — investment: Investment account (e.g., brokerage or portfolio account).",
"enum": [
0,
1,
2,
3,
4
]
},
"iso_currency_code": {
"type": "string",
"description": "The ISO currency code that is associated with the account"
},
"current_balance": {
"type": "number",
"description": "Current available balance for the account in pounds sterling (GBP).",
"format": "double"
}
},
"type": "object",
"required": [
"account_reference",
"institution_name",
"names_on_account",
"account_type",
"account_subtype",
"current_balance",
"iso_currency_code"
]
},
"description": "An optional array of bank account details linked to the provided transactions from your customer. These details can improve the categorisation of transactions. "
},
"transactions": {
"type": "array",
"items": {
"properties": {
"user_id": {
"type": "string",
"description": "The user ID you've assigned to your customer for these transactions.",
"default": "ae60d78d-bed1-4c76-b2f0-9bfc5af11420"
},
"account_reference": {
"type": "string",
"description": "A string identifier that links the transaction to a provided account in the accounts array. ",
"default": "db080c72-1c67-4f26-80e2-c088490c0420"
},
"original_description": {
"type": "string",
"description": "The original description for the transaction unaltered, as it appears on the transaction.",
"default": "WWW.NWL.CO.UK"
},
"amount": {
"type": "string",
"description": "The amount for the transaction as a floating point number. Negative for incoming credit transactions and Positive value for outgoing debit transactions",
"default": "462.68"
},
"date": {
"type": "string",
"description": "The date for the transaction in YYYY-MM-DD format.",
"default": "2024-08-20"
}
},
"type": "object",
"required": [
"user_id",
"amount",
"original_description",
"account_reference",
"date"
]
},
"description": "An array of bank transaction objects."
}
},
"required": [
"transactions"
]
},
"examples": {
"Sample request": {
"summary": "Sample request",
"value": {
"customer_name": "Millicent Fawcett",
"transactions": [
{
"user_id": "ae60d78d-bed1-4c76-b2f0-9bfc5af11420",
"account_reference": "db080c72-1c67-4f26-80e2-c088490c0420",
"original_description": "WWW.NWL.CO.UK",
"amount": "462.68",
"date": "2024-08-20"
},
{
"user_id": "a39656fa-1383-43c4-a8a9-47a0f486ed56",
"account_reference": "db080c72-1c67-4f26-80e2-c088490c0420",
"original_description": "Jac's",
"amount": "3.75",
"date": "2025-01-21"
},
{
"user_id": "a39656fa-1383-43c4-a8a9-47a0f486ed56",
"account_reference": "db080c72-1c67-4f26-80e2-c088490c0420",
"original_description": "SALARY PAYROLL - SPARROW MARKETING LTD",
"amount": "-965.27",
"date": "2023-06-20"
}
]
}
},
"Sample request with customer name and accounts": {
"summary": "Sample request with customer name and accounts",
"value": {
"customer_name": "Millicent Fawcett",
"accounts": [
{
"account_reference": "XgqabKrrZjuyxOp7Zk5MHQjn97mbKPTQg9bXb",
"institution_name": "Monzo UK",
"names_on_account": [
"Millicent Fawcett"
],
"account_type": 0,
"account_subtype": 0,
"iso_currency_code": "GBP",
"current_balance": 50
}
],
"transactions": [
{
"user_id": "ae60d78d-bed1-4c76-b2f0-9bfc5af11420",
"account_reference": "db080c72-1c67-4f26-80e2-c088490c0420",
"original_description": "WWW.NWL.CO.UK",
"amount": "462.68",
"date": "2024-08-20"
},
{
"user_id": "a39656fa-1383-43c4-a8a9-47a0f486ed56",
"account_reference": "db080c72-1c67-4f26-80e2-c088490c0420",
"original_description": "Jac's",
"amount": "3.75",
"date": "2025-01-21"
},
{
"user_id": "a39656fa-1383-43c4-a8a9-47a0f486ed56",
"account_reference": "db080c72-1c67-4f26-80e2-c088490c0420",
"original_description": "SALARY PAYROLL - SPARROW MARKETING LTD",
"amount": "-965.27",
"date": "2023-06-20"
}
]
}
}
}
}
}
},
"security": [
{
"ApiKeyAuth": []
}
]
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "x-api-key",
"description": "The API key required to authenticate with the endpoint."
}
}
},
"x-readme": {
"explorer-enabled": true,
"proxy-enabled": true
}
}
```