Recurring Transactions Report
Group recurring transaction by categories, brand, amount and period.
URL and Request Body Structure of a Recurring Transactions Report
POST /insights/v1/reports/recurring-transactions/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,
"required_data_availability": ?Enum<'COMPLETE', 'PARTIAL', 'NONE'>
}
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.
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
Response Structure of Recurring Transactions Report
{
"data": {
"reports": Array<RecurringTransactionReport>
}
}
The list of reports generated depending on the requested parameters.
RecurringTransactionReport
{
"type": "RECURRING_TRANSACTIONS",
"insights_consumer_id": String,
"insights_account_ids": Array<String>,
"from_date": Date,
"to_date": Date,
"refreshed_at": DateTime,
"intervals": Array<Interval>,
"data_availability": Enum<'COMPLETE', 'PARTIAL', 'NONE'>
}
The type always contains the value "RECURRING_TRANSACTIONS" for this report.
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.
The starting date used to generate this report.
The refreshed_at shows when the data for this account were last refreshed.
A list of intervals, there is a maximum of one entry per distinct interval.
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
Interval
{
"interval": Enum<'WEEKLY', 'BIWEEKLY', 'MONTHLY', 'QUARTERLY', 'HALF_YEARLY', 'YEARLY', 'UNKNOWN'>
"income_amount": Amount,
"expense_amount": Amount,
"transaction_groups": Array<TransactionGroup>
}
An Interval contains information about how often a transaction recurs. For that similar transactions are grouped into TransactionGroup.
For example: if interval is MONTHLY and transaction_groups contains one entry there is one recurring transaction every month.
The interval that all transactions have.
WEEKLY- means that the transactions recur once every weekBIWEEKLY- means that the transactions recur once every other weekMONTHLY- means that the transactions recur once every monthQUARTERLY- means that the transactions recur once every quarterHALF_YEARLY- means that the transactions recur once every half a yearYEARLY- means that the transactions recur once every yearUNKNOWN- means that the transactions recur in unknown interval of time
The sum of all transaction group average_amount-values in this interval that are classified as income.
The sum of all transaction group average_amount-values in this interval that are classified as expense.
A list of TransactionGroup-objects that recur in the specified interval.
TransactionGroup
{
"earliest_day": Integer,
"latest_day": Integer,
"average_amount": Amount,
"transaction_ids": Array<String>,
"categories": Array<Category>,
"brand": ?Brand,
"occurences_range": {
"earliest_occurence_date": Date,
"latest_occurrence_date": Date
}
}
A group is a collection of multiple transactions that have the same categories, brand, a similar amount and dates which match the interval.
The earliest day of month that a transaction was found for this group
The latest day of month that a transaction was found for this group.
A list of transaction ids, to get all information about these transactions use the Categorized Transactions Report The length of this list depends on the amount of data available.
A list of categories that all transactions of this group have. Can be empty.
A data wrapper for the occurrences of the transactions within this group.
The earliest occurrence found of a transaction within this group.
The latest occurrence found of a transaction within this group.
Example request
{
"insights_consumer_id": "6c03aff-8fa0046-ffae74-b0cbc-4d5fd1",
"report_days": 120
}
Example response
{
"data": {
"reports": [
{
"type": "RECURRING_TRANSACTIONS",
"insights_consumer_id": "6c03aff-8fa0046-ffae74-b0cbc-4d5fd1",
"insights_account_ids": [
"3b3d678f-66b7-4b23-a2a5-0bfd275e86a1"
],
"intervals": [
{
"interval": "MONTHLY",
"income_amount": {
"amount": 120000
},
"expense_amount": {
"amount": -70000
},
"transaction_groups": [
{
"earliest_day": 2,
"latest_day": 3,
"average_amount": {
"amount": 120000,
"currency": "EUR"
},
"categories": [
{
"id": "8f7614f5-845d-5463-b145-8a1d57a40bd4",
"name": "Salary & Wages & Paycheck"
}
],
"transaction_ids": [
"26591975-811d-4fb7-8488-7e20d71a19c5",
"a0855f13-6ac9-470e-820b-eb04db06ea06"
],
"occurrences_range": {
"earliest_occurrence_date": "2023-03-03",
"latest_occurrence_date": "2023-06-02"
}
},
{
"earliest_day": 19,
"latest_day": 21,
"average_amount": {
"amount": -2000,
"currency": "EUR"
},
"categories": [
{
"id": "13e8d66c-fe7d-53c4-ac21-70274ae0de6b",
"name": "TV streaming subscriptions"
}
],
"brand": {
"id": "e716771c-729c-5545-a73c-167f27071d82",
"name": "Movie Stream"
},
"transaction_ids": [
"941db735-efbb-5a0e-b4a4-bec4972441e7",
"51e4d707-e779-4612-ad9f-88402a21d874"
],
"occurrences_range": {
"earliest_occurrence_date": "2023-03-19",
"latest_occurrence_date": "2023-06-21"
}
},
{
"earliest_day": 24,
"latest_day": 24,
"average_amount": {
"amount": -5000,
"currency": "EUR"
},
"categories": [
{
"id": "653ce528-43f2-5e60-95d5-c258f6ade300",
"name": "Mobile Phone"
}
],
"brand": {
"id": "ed558b36-3c41-5bd6-83f6-0869aedb0914",
"name": "Large Phone Company"
},
"transaction_ids": [
"e94261e5-464d-4dda-b16e-57743a7f3744",
"0c6afa7c-0385-5507-86ee-3095317108c4"
],
"occurrences_range": {
"earliest_occurrence_date": "2023-03-24",
"latest_occurrence_date": "2023-06-24"
}
}
]
}
],
"refreshed_at": "2023-06-25T09:22:02.523Z",
"from_date": "2023-02-25",
"to_date": "2023-06-25",
"data_availability": "COMPLETE"
}
]
}
}