Group-by-Category Report
Build a report with transactions grouped by category. Each category will have multiple data fields with information about the transactions for this category.
URL and Request Body Structure of a Group by Category Report
POST /insights/v1/reports/groupy-by-category/create HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Token <Token>
Host: <Host>
{
"insights_consumer_id": String,
"insights_account_ids": ?Array<String>,
"excluded_insights_account_ids": ?Array<String>,
"report_days": ?Integer,
"from_date": ?Date,
"to_date": ?Date,
"only_main_category" : ?Boolean,
"states": ?Array<Enum<'PROCESSED', 'PENDING', 'CANCELED', 'FAILED', 'UNKNOWN'>>
"split_by": ?Enum<'MONTH'>,
"split_by_month_adjusted_day": ?Integer,
"excluded_categories": ?Array<String>,
"max_amount": ?Integer,
"min_amount": ?Integer,
"category_ids": ?Array<String>,
"labels": ?Array<{
"key": String,
"value": String
}>,
"excluded_labels": ?Array<{
"key": String,
"value": String
}>,
"order": ?Array<OrderBy>,
"required_data_availability": ?Enum<'COMPLETE', 'PARTIAL', 'NONE'>,
"combine_accounts": ?Enum<'NONE', 'ALL'>,
"transaction_type": ?Enum<'CREDIT', 'DEBIT'>
}
The insights_consumer_id parameter identifies the consumer whose transactions are used to generate the report.
The list of accounts, identified by the insights_account_id, which will filter all transactions from the consumer to only those accounts. If missing, all accounts of the insights_consumer_id will be used to generate the report(s). The insights_account_ids parameter must be empty if the excluded_insights_account_ids parameter is set.
The list of insights_account_ids which will be excluded from the report generation. The excluded_insights_account_ids parameter must be empty if the insights_account_ids parameter is set.
This parameter offers to provide a timeframe without need to calculate dates. If the report_days property is set, the parameters from_date and to_date will be derived from current day (today) minus the given number of days.
The timeframe for which the report should be generated can be set by specifying either the from_date and to_date parameters or this report_days parameter. If no timeframe is specified, the default timeframe of the last 62 days will be used.
The from_date parameter (in combination with the to_date parameter) will be used as the inclusive start date for this timeframe.
The timeframe for which the report should be generated can be set by specifying either the from_date and to_date parameters or the report_days parameter. If no timeframe is specified, the default timeframe of the last 62 days will be used.
The to_date parameter (in combination with the from_date parameter) will be used as the inclusive end date for this timeframe.
The timeframe for which the report should be generated can be set by specifying either the from_date and to_date parameters or the report_days parameter. If no timeframe is specified, the default timeframe of the last 62 days will be used.
Since transactions can fit into multiple categories, this option tells the report to only consider the most significant category. The default for this flag is false.
Filters the transactions to only include transactions with a transaction state in the given list.
Split each report into multiple reports depending on the requested timeframe and this parameter, resulting reports will be ordered ascending by timeframe.
For example: Setting this parameter to MONTH, from_date to 2021-01-01 and to_date to 2021-03-31 results in three reports, one for each month.
MONTH: Split by month, default start day of a month is the 1. That can be changed withsplit_by_month_adjusted_day.
Adjust the month start day. Valid values are 1-31, default is 1.
Excludes every transaction that has a category-ID which matches against one from this list of category-ID's. Only valid ID's can be passed.
If only_main_category is set to true, it will only exclude transactions that have their main category-ID matching against one from this list of category-ID's.
Filter the transactions to include only transactions with amount less or equal the max_amount parameter.
The amount needs to be provided in the smallest unit of currency. See the amount parameter of the amount object.
Filter the transactions to include only transactions with an amount of at least min_amount.
The amount needs to be provided in the smallest unit of currency. See the amount parameter of the amount object.
Filter the transactions to include only transactions matching the categories identified by the category_ids. The id must match a category from the Category List.
Included transactions will be filtered to only contain those that have at least one of the requested key-value pairs.
Included transactions will be filtered to only contain those that have none one of the listed key-value pairs.
If a transaction is included by the labels parameter and excluded by the excluded_labels parameter in the same request it will be excluded.
Use this parameter to return the categories in a specific order. If this field is not set the default order will be AMOUNT & DESC. Chaining the order is available.
Filters the transactions to only include transactions that are either CREDIT transactions or DEBIT transactions. Default is that both types will be included.
Defines minimum requirement for transaction data that must be available in the given timeframe. The default is COMPLETE.
COMPLETE- data for the whole timeframe must be availablePARTIAL- some data in the timeframe must be availableNONE- no data in the timeframe must be available
OrderBy
{
"order": ?Enum<'ASC', 'DESC'>,
"field": Enum<'TOTAL_AMOUNT','TOTAL_COUNT','NAME'>
}
Sets the direction of order: ascending or descending. The default setting is ascending (ASC).
Can be used to combine the available accounts for a consumer to present the response in different ways. Default value is NONE.
NONE- Does not combine any accounts. The response will include separate reports for each account that is available.ALL- Combines all available accounts and presents a combined result.
Response Structure of Group by Category Report
{
"data": {
"reports": Array<GroupByCategoryReport>
}
}
The list of reports generated depending on the requested parameters.
Group by Category Report
{
"type": "GROUP_BY_CATEGORY",
"insights_consumer_id": String,
"insights_account_ids": Array<String>,
"categories": Array<CategoryInfo>,
"from_date": Date,
"to_date": Date,
"refreshed_at": DateTime,
"total_amount_sum": Amount,
"credit_amount_sum": Amount,
"debit_amount_sum": Amount,
"split_by_month": ?Month,
"data_availability": Enum<'COMPLETE', 'PARTIAL', 'NONE'>
}
The insights_consumer_id is the consumer identifier for the account(s) used in this report.
The insights_account_ids is used to identify a specific account within Account Insights.
Depending on type of report and requested account-settings this could be a list of ids.
List of all category found for the account with count and sum of the corresponding transactions.
The starting date used to generate this report.
The refreshed_at shows when the data for this account were last refreshed.
The total sum of the amounts of all transactions included in the report. This sum can be a positive or negative number.
The sum of the amounts of all CREDIT transactions included in the report. This amount will always be zero or a positive number.
The sum of the amounts of all DEBIT transactions included in the report. This amount will always be zero or a positive number.
The month this report represents. Is only returned if split_by is set to MONTH.
The availability of transaction data for the requested timeframe.
COMPLETE- data for the whole timeframe was availablePARTIAL- some data in the timeframe was availableNONE- no data in the timeframe was available
CategoryInfo
{
"id": String,
"name": String,
"total_count": Integer,
"total_amount_sum": Amount,
"credit_count": Integer,
"credit_amount_sum": Amount,
"debit_count": Integer,
"debit_amount_sum": Amount
}
The unique identifier of the category. Further details about a category will be provided by the Category List call.
The sum of the amounts of all transactions included in this category. This sum can be a positive or negative number.
The sum of the amounts of all CREDIT transactions included in this category. This amount will always be zero or a positive number.
The sum of the amounts of all DEBIT transactions included in this category. This amount will always be zero or a positive number.
Example request
{
"insights_consumer_id": "6c03aff-8fa0046-ffae74-b0cbc-4d5fd1",
"report_days": 30,
"only_main_category": true,
"order": [
{
"order": "DESC",
"field": "TOTAL_AMOUNT"
}
],
"labels": [
{
"key": "order-id-for-company-1",
"value": "123456789"
}
],
"excluded_labels": [
{
"key": "order-id-for-company-1",
"value": "1234"
}
],
"combine_accounts": "ALL"
}
Example response
{
"data": {
"reports": [
{
"type": "GROUP_BY_CATEGORY",
"insights_consumer_id": "6c03aff-8fa0046-ffae74-b0cbc-4d5fd1",
"insights_account_ids": [
"3b3d678f-66b7-4b23-a2a5-0bfd275e86a1",
"d111084f-04ef-4808-9455-939a7694c3be"
],
"refreshed_at": "2021-06-15T09:22:02.523Z",
"total_amount_sum": {
"amount": 296105,
"currency": "EUR"
},
"credit_amount_sum": {
"amount": 300000,
"currency": "EUR"
},
"debit_amount_sum": {
"amount": 3895,
"currency": "EUR"
},
"categories": [
{
"name": "Salary & Wages & Paycheck",
"id": "8f7614f5-845d-5463-b145-8a1d57a40bd4",
"total_count": 1,
"total_amount_sum": {
"amount": 300000,
"currency": "EUR"
},
"credit_count": 1,
"credit_amount_sum": {
"amount": 300000,
"currency": "EUR"
},
"debit_count": 0,
"debit_amount_sum": {
"amount": 0,
"currency": "EUR"
}
},
{
"name": "Clothes",
"id": "a9184d59-25be-5f03-aebb-f639a5ed9a8a",
"total_count": 1,
"total_amount_sum": {
"amount": -3895,
"currency": "EUR"
},
"credit_count": 0,
"credit_amount_sum": {
"amount": 0,
"currency": "EUR"
},
"debit_count": 1,
"debit_amount_sum": {
"amount": 3895,
"currency": "EUR"
}
}
],
"from_date": "2021-05-21",
"to_date": "2021-06-14",
"data_availability": "COMPLETE"
}
]
}
}
Example request with splitBy
{
"insights_consumer_id": "6c03aff-8fa0046-ffae74-b0cbc-4d5fd1",
"insights_account_ids": [
"3b3d678f-66b7-4b23-a2a5-0bfd275e86a1",
"d111084f-04ef-4808-9455-939a7694c3be"
],
"from_date": "2021-01-01",
"to_date": "2021-02-28",
"split_by": "MONTH",
"combine_accounts": "NONE"
}
Example response with splitBy
{
"data": {
"reports": [
{
"type": "GROUP_BY_CATEGORY",
"insights_consumer_id": "6c03aff-8fa0046-ffae74-b0cbc-4d5fd1",
"insights_account_ids": [
"3b3d678f-66b7-4b23-a2a5-0bfd275e86a1"
],
"refreshed_at": "2021-06-15T09:22:02.523Z",
"total_amount_sum": {
"amount": -1438,
"currency": "EUR"
},
"credit_amount_sum": {
"amount": 0,
"currency": "EUR"
},
"debit_amount_sum": {
"amount": 1438,
"currency": "EUR"
},
"categories": [
{
"id": "8f1f56e6-a312-454d-b0ee-e20350cb5c1c",
"name": "Bank charges",
"total_count": 4,
"total_amount_sum": {
"amount": -1438,
"currency": "EUR"
},
"credit_count": 0,
"credit_amount_sum": {
"amount": 0,
"currency": "EUR"
},
"debit_count": 4,
"debit_amount_sum": {
"amount": 1438,
"currency": "EUR"
}
}
],
"from_date": "2021-01-01",
"to_date": "2021-01-31",
"split_by_month": "2021-01",
"data_availability": "COMPLETE"
},
{
"type": "GROUP_BY_CATEGORY",
"insights_consumer_id": "6c03aff-8fa0046-ffae74-b0cbc-4d5fd1",
"insights_account_ids": [
"3b3d678f-66b7-4b23-a2a5-0bfd275e86a1"
],
"refreshed_at": "2021-06-15T09:22:02.523Z",
"total_amount_sum": {
"amount": -14527,
"currency": "EUR"
},
"credit_amount_sum": {
"amount": 0,
"currency": "EUR"
},
"debit_amount_sum": {
"amount": 14527,
"currency": "EUR"
},
"categories": [
{
"id": "0723e731-132d-4f00-a655-d9768dddc9b3",
"name": "Health insurance",
"total_count": 1,
"total_amount_sum": {
"amount": -14527,
"currency": "EUR"
},
"credit_count": 0,
"credit_amount_sum": {
"amount": 0,
"currency": "EUR"
},
"debit_count": 1,
"debit_amount_sum": {
"amount": 14527,
"currency": "EUR"
}
}
],
"from_date": "2021-02-01",
"to_date": "2021-02-28",
"split_by_month": "2021-02",
"data_availability": "COMPLETE"
},
{
"type": "GROUP_BY_CATEGORY",
"insights_consumer_id": "6c03aff-8fa0046-ffae74-b0cbc-4d5fd1",
"insights_account_ids": [
"d111084f-04ef-4808-9455-939a7694c3be"
],
"refreshed_at": "2021-06-15T09:22:02.523Z",
"total_amount_sum": {
"amount": -1438,
"currency": "EUR"
},
"credit_amount_sum": {
"amount": 0,
"currency": "EUR"
},
"debit_amount_sum": {
"amount": 1438,
"currency": "EUR"
},
"categories": [
{
"id": "8f1f56e6-a312-454d-b0ee-e20350cb5c1c",
"name": "Bank charges",
"total_count": 4,
"total_amount_sum": {
"amount": -1438,
"currency": "EUR"
},
"credit_count": 0,
"credit_amount_sum": {
"amount": 0,
"currency": "EUR"
},
"debit_count": 4,
"debit_amount_sum": {
"amount": 1438,
"currency": "EUR"
}
}
],
"from_date": "2021-01-01",
"to_date": "2021-01-31",
"split_by_month": "2021-01",
"data_availability": "COMPLETE"
},
{
"type": "GROUP_BY_CATEGORY",
"insights_consumer_id": "6c03aff-8fa0046-ffae74-b0cbc-4d5fd1",
"insights_account_ids": [
"d111084f-04ef-4808-9455-939a7694c3be"
],
"refreshed_at": "2021-03-05T09:22:02.523Z",
"total_amount_sum": {
"amount": -456789,
"currency": "EUR"
},
"credit_amount_sum": {
"amount": 0,
"currency": "EUR"
},
"debit_amount_sum": {
"amount": 456789,
"currency": "EUR"
},
"categories": [
{
"id": "0723e731-132d-4f00-a655-d9768dddc9b3",
"name": "Groceries",
"total_count": 3,
"total_amount_sum": {
"amount": -456789,
"currency": "EUR"
},
"credit_count": 0,
"credit_amount_sum": {
"amount": 0,
"currency": "EUR"
},
"debit_count": 3,
"debit_amount_sum": {
"amount": 456789,
"currency": "EUR"
}
}
],
"from_date": "2021-02-01",
"to_date": "2021-02-28",
"split_by_month": "2021-02",
"data_availability": "COMPLETE"
}
]
}
}