Categorized Transactions Report

Build a report with transactions belonging to requested customer and account and fitting the provided date range. It will show all transactions enriched with category and brand information.

URL and Request Body Structure of a Categorized Transactions Report

POST /insights/v1/reports/categorization/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,
    "size" : ?Integer,
    "offset": ?Integer,
    "max_amount": ?Integer,
    "min_amount": ?Integer,
    "transaction_type": ?Enum<'DEBIT', 'CREDIT', 'DEBIT_AND_ZERO'>
    "only_main_category" : ?Boolean,
    "states": ?Array<Enum<'PROCESSED', 'PENDING', 'CANCELED', 'FAILED', 'UNKNOWN'>>
    "insights_transaction_ids": ?Array<String>,
    "category_ids": ?Array<String>,
    "brand_ids": ?Array<String>,
    "order": ?Array<ReportOptionsOrderBy>,
    "labels": ?Array<{
      "key": String,
      "value": String
    }>,
    "excluded_labels": ?Array<{
      "key": String,
      "value": String
    }>,
    "required_data_availability": ?Enum<'COMPLETE', 'PARTIAL', 'NONE'>,
    "combine_accounts": ?Enum<'NONE', 'ALL'>
}

insights_consumer_id String, required

The insights_consumer_id parameter identifies the consumer whose transactions are used to generate the report.

insights_account_ids String[], optional

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.

excluded_insights_account_ids String[], optional

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.

report_days Integer, optional

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.

from_date Date (String: "YYYY-MM-DD"), optional

The from_date parameter (in combination with the to_date parameter) will be used as the inclusive start date for this timeframe. It has to be provided in the YYYY-MM-DD format according to ISO 8601.

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.

to_date Date (String: "YYYY-MM-DD"), optional

The to_date parameter (in combination with the from_date parameter) will be used as the inclusive end date for this timeframe. It has to be provided in the YYYY-MM-DD format according to ISO 8601.

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.

size Integer, optional

Only return a maximum of size transactions in the report. The default will be unlimited.

offset Integer, optional

Returns the transaction after skipping the first offset number of transactions. Default will be 0, so no transactions will be skipped.

max_amount Integer, optional

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.

min_amount Integer, optional

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.

transaction_type Enum, optional

Filters the transaction to only include the ones with the type DEBIT or CREDIT as requested.

Since transactions with an amount of 0 always have the type CREDIT the filter type DEBIT_AND_ZERO can be used to receive transactions with the DEBIT type and also transactions that have an amount of 0.

states Enum[], optional

Filters the transactions to only include transactions with a transaction state in the given list.

insights_transaction_ids String[], optional

Filter the transactions to include only transactions with the given transaction-ids.

category_ids String[], optional

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.

only_main_category boolean, optional

Since transactions can fit into multiple categories, this option tells the report to filter the categories given in category_ids only on the most significant category for each transaction. The default for this flag is false.

brand_ids String[], optional

Filter the transactions to include only transactions matching the brands identified by the brand_ids.

order ReportOptionsOrderBy[], optional

Use this parameter to return the transactions in a specific order.

ReportOptionsOrderBy

{
    "order": ?Enum<'ASC', 'DESC'>,
    "field": Enum<'AMOUNT','DATE','CATEGORY','BRAND','AMOUNT_WITH_TYPE'>
}

order Enum, optional

Sets the direction of order: ascending or descending. The default setting is ascending.

field Enum, required

The transactions will be ordered by the field from this enum.

The difference between AMOUNT and AMOUNT_WITH_TYPE is that AMOUNT orders the transactions by amount without considering the transaction type. The AMOUNT_WITH_TYPE considers the transaction type and orders DEBIT transactions with a negative amount and CREDIT transactions with a positive amount.

labels Object[], optional

Transactions will be filtered to only contain those that have at least one of the requested key-value pairs.

labels.key String, required

The key of a label. For example "krn".

labels.value String, required

The value of a label. For example an order ID.

excluded_labels Object[], optional

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.

excluded_labels.key String, required

The key of a label. For example "krn".

excluded_labels.value String, required

The value of a label. For example an order ID.

required_data_availability Enum, optional

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 available
  • PARTIAL - some data in the timeframe must be available
  • NONE - no data in the timeframe must be available

combine_accounts Enum, optional

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 Categorized Transactions Report

{
    "data": {
        "reports": Array<CategorizedTransactionReport>
    }
}

data.reports CategorizedTransactionReport[], always present

The list of reports generated depending to the requested parameters.

CategorizedTransactionReport

{
    "type": "CATEGORIZED_TRANSACTIONS",
    "insights_consumer_id": String,
    "insights_account_ids": Array<String>,
    "transactions": Array<CategorizedTransaction>,
    "from_date": Date,
    "to_date": Date,
    "refreshed_at": DateTime,
    "data_availability": Enum<'COMPLETE', 'PARTIAL', 'NONE'>
}

type String, always present

The type always contains the value "CATEGORIZED_TRANSACTIONS" for this report.

insights_consumer_id String, always present

The insights_consumer_id is the consumer identifier for the account(s) used in this report.

insights_account_ids String, always present

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.

transactions CategorizedTransaction[], always present

List of all transactions for the account(s) in insights_account_ids with added data about categories and brands.

from_date Date (String: "YYYY-MM-DD"), always present

The starting date used to generate this report.

to_date Date (String: "YYYY-MM-DD"), always present

The end date used to generate this report.

refreshed_at DateTime, always present

The refreshed_at shows when the data for this account were last refreshed. It is provided in the YYYY-MM-DDThh:mm:ss.sssZ format according to ISO 8601 with an UTC offset, such as 2007-12-03T10:15:30.152Z.

data_availability Enum, always present

The availability of transaction data for the requested timeframe.

  • COMPLETE - data for the whole timeframe was available
  • PARTIAL - some data in the timeframe was available
  • NONE - no data in the timeframe was available

Example request

{
    "insights_consumer_id": "6c03aff-8fa0046-ffae74-b0cbc-4d5fd1",
    "insights_account_ids":
        [
            "3b3d678f-66b7-4b23-a2a5-0bfd275e86a1",
            "4c4e789g-77c8-5c34-b3b6-1cge386f97b2"
        ],
    "report_days": 60,
    "max_amount": 1000,
    "min_amount": -1000,
    "size": 3,
    "labels": [
        {
            "key": "order-id-for-company-1",
            "value": "123456789"
        }
    ],
    "excluded_labels": [
        {
            "key": "order-id-for-company-1",
            "value": "1234"
        }
    ],
    "required_data_availability": "PARTIAL",
    "combine_accounts": "ALL"
}

Example response

{
    "data": {
        "reports": [
            {
                "type": "CATEGORIZED_TRANSACTIONS",
                "insights_consumer_id": "6c03aff-8fa0046-ffae74-b0cbc-4d5fd1",
                "insights_account_ids": [
                        "3b3d678f-66b7-4b23-a2a5-0bfd275e86a1",
                        "4c4e789g-77c8-5c34-b3b6-1cge386f97b2"
                    ],
                "transactions": [
                    {
                        "ob_transaction_id": "31234-12314234",
                        "booking_date": "2020-01-01",
                        "amount": {
                                "amount": 1599,
                                "currency": "EUR"
                        },
                        "reference": "transfer to esprit online shop",
                        "bank_references": {
                            "unstructured": "esprit online  shop"
                        },
                        "type": "DEBIT",
                        "method": "UNKNOWN",
                        "bank_transaction_code": {
                            "code": "CCRD",
                            "sub_code": "CreditCardPayment",
                            "description": "Transaction is related to a payment of credit card."
                        },
                        "counter_party": {
                            "holder_name": "esprit germany",
                            "holder_address": {
                                "country": "DE"
                            }
                        },
                        "categories": [
                            {
                                "id": "a9184d59-25be-5f03-aebb-f639a5ed9a8a",
                                "name": "Clothes"
                            }
                        ],
                        "brand": {
                            "id": "664bb3a2-62c9-52b7-9ccd-81cfe904258c",
                            "name": "Esprit"
                        },
                        "labels": {
                            "order-id-for-company-1": "123456789"
                        },
                        "insights_transaction_id": "ae66102e-f4ff-5e02-8f95-ad0bbd225e19"
                    },
                    {
                        "value_date": "2020-01-01",
                        "amount": {
                                "amount": 679,
                                "currency": "EUR"
                        },
                        "reference": "rewe sagt danke",
                        "type": "DEBIT",
                        "method": "TRANSFER",
                        "state": "PROCESSED",
                        "counter_party": {
                            "holder_name": "rewe gmbh"
                        },
                        "categories": [
                            {
                                "id": "edde5df6-fbf4-5e79-afb1-97de52d93aca",
                                "name": "Groceries"
                            }
                        ],
                        "brand": {
                            "id": "71569e21-bfe3-5871-9a5a-f791cca811c0",
                            "name": "Rewe",
                            "url": "https://www.rewe.de"
                        },
                        "labels": {
                            "order-id-for-company-1": "123456789",
                            "order-id-for-company-2": "123456789",
                            "order-id-for-company-3": "123454321"
                        },
                        "insights_transaction_id": "3a1cf972-a9bb-5fc7-b36d-12ad707f29aa"
                    }
                ],
                "refreshed_at": "2021-06-15T09:22:01+0200",
                "from_date": "2021-05-21",
                "to_date": "2021-06-14",
                "data_availability": "PARTIAL"
            }
        ]
    }
}

results matching ""

    No results matching ""