# Cash Flow Analytics
source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/cash-flow-analytics/index.md
## Overview {#overview}
Cash Flow Analytics (CFA) analyzes up to 24 months of credits and debits in connected accounts to surface cash-flow health and trends - such as inflows, outflows, net cash flow, seasonality, and NSF events - to assess capacity to pay and volatility. For business and personal use cases (CRA or non-CRA), CFA returns model-ready attributes over the desired time intervals.
Learn more about Mastercard's [Cash Flow](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#cash-flow) products.
### Key Product Features {#key-product-features}
* **Account Owner:** See the listed account owner name and address to assist in fraud reduction
* **Data History** : Up to 24 months of categorized transaction data based on availability from the FI(s). Length of history is customizable using the `fromDate` and defaults to 24 months
* **Cash Flow Analytics:** Includes debit and credit breakouts, net cash flow attributes, and revenue assessment (for business versions of the report only)
* **Non-Sufficient Funds (NSF) Summary**: The presence of NSFs can be a key indicator of financial distress
* **Time Interval Type:** The periodicity at which attributes will be calculated. Available options range from Daily all the way to Historical (a report would include one set of attributes covering the entire history). Up to 2 time intervals may be requested per report. Defaults to Monthly Calendar
* **Connected Accounts Summary:** Includes information such as the financial institution (FI) name, last four digits of the account number, account type, and balance
* **FI Certification Type** : Transaction Aggregation (TA). Each FI goes through a certification process to make sure the right data is consistently provided to make the product successful. See [the list of certified FIs](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md) for this product.
* **Report Generation Time (median):** Less than 20 seconds
* **Report Refreshes:** This report can be refreshed with new data as long as the accounts are still connected, and consent is active. Refreshes are provided at no cost within 60 days after the first report is created. A report pulled after this period will incur a new charge
* **Supported Account Types**: Checking, Savings, Money Market, CD, Investment account types, Mortgage, Loan, Credit Card, Line of Credit, Payroll, Student Loan, Education Savings, Health Savings Account
* **Supported Report Format:** JSON and PDF
Note: This report may ONLY be furnished for a Fair Credit Reporting Act (FCRA) purpose such as credit, insurance, or employment, and only pursuant to a permissible purpose certification by the report user. Provision and use of this report is subject to all applicable obligations of the FCRA.
### Use Cases {#use-cases}
The Cash Flow Analytics product can be used for the following use cases:
* Auto
* Credit Card Issuance
* Credit Line Management
* Customer / Portfolio Monitoring
* Debt Collection
* Personal Financial Management
* Personal Lending
* Servicing
* Small and Medium Business
* Tenant Screening
## How it Works {#how-it-works}
### Prerequisites {#prerequisites}
This product is dependent on the customer linking their bank accounts
via Data Connect. Refer to [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md)
for more information.
* [Generate the required credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) to call the API.
* [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token)
* [Create a customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers).
* [Create a consumer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) record for consumer FCRA use cases and for business use cases where the applicant is personally guaranteeing the loan.
* [Create and link a business record to the customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#businesses) if a business use case.
* [Generate a Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and [link customer accounts](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#the-data-connect-flow).
### Generate a Cash Flow Analytics Report {#generate-a-cash-flow-analytics-report}
To generate or refresh a Cash Flow Analytics report, use the following endpoint:
API Reference: `POST /decisioning/v2/customers/{customerId}/reports/cashflow-analytics/userTypes/{userType}`
The response will include the status of the report generation and a report ID. A notification is sent when report generation is finished (see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)).
#### Implementation Notes {#implementation-notes}
* Use the `fromDate` parameter to customize the transaction history included in the report.
By default, 24 months of history will be aggregated as available.
* Customize which accounts are included in the report using the `accountIds` parameter. By default, the report includes all supported account types.
* The `Revenue` attribute is only provided when `userType` = `business`.
* Use the `timeIntervalType` to select the periodicity at which attributes will be calculated. Defaults to Monthly Calendar.
Customize the type of Cash Flow Analytics report received based on inputs provided when generating the report:
| Report Type | User Type/Experience | For CRA Purpose | Applicant is Personal Guarantor | Consumer Required | Customer Required | Business Required |
|-------------|----------------------|-----------------|---------------------------------|-------------------|-------------------|-------------------|
| cfrpcra | personal | true | N/A | true | true | false |
| cfrpnoncra | personal | false | N/A | false | true | false |
| cfrbcra | business | true | true | true | true | true |
| cfrbftc | business | true | false | false | true | true |
| cfrbnoncra | business | false | false | false | true | true |
### Get Cash Flow Analytics Reports {#get-cash-flow-analytics-reports}
Once the report is generated, retrieve the report using one of the [Get Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) endpoints.
#### Example Report {#example-report}
The Get Report APIs response contains different data depending on the type of report requested. The following example shows what a successful JSON response could look like for this report. Examples are meant for reference only and may lag production changes.
```json
{
"id": "n1siaxtrn1ni-cfrpcra",
"customerType": "testing",
"customerId": 1011077785,
"requestId": "m8ks9vjq2u",
"requesterName": "Open Banking API Tests",
"endUser": {
"name": "ABC Apartments",
"address": "123 Main St",
"city": "Murray",
"state": "UT",
"zip": "84123",
"phone": "555-2106",
"email": "customerservice@example.com",
"url": "example.com"
},
"title": "Mastercard Open Banking Cash Flow Analytics",
"consumerId": "8d510370aae83d459da0b905ee59e714",
"consumerSsn": "1147",
"disputeStatement": "Invalid data present.",
"type": "cfrpcra",
"status": "success",
"constraints": {
"analyticsReportData": {
"forCraPurpose": true,
"timeIntervalTypes": [
"MONTHLY_CALENDAR"
]
}
},
"createdDate": 1721813301,
"startDate": 1658654901,
"endDate": 1721813301,
"days": 730,
"institutions": [
{
"id": 102105,
"name": "FinBank Profiles - A",
"urlHomeApp": "http://www.bank.example.com",
"accounts": [
{
"id": 3027530342,
"ownerName": "JNC PROPERTIES LLC",
"ownerAddress": "1944 JAKETOWN RD DONNELLSON IL 62019",
"ownerAsOfDate": 1721818584,
"name": "Business Investment",
"number": "1101",
"type": "investment",
"aggregationStatusCode": 0,
"currentBalance": 100000,
"balanceDate": 1721813305,
"transactions": [],
"analytics": null,
"currency": "USD"
},
{
"id": 3027530343,
"ownerName": "NSF USER",
"ownerAddress": "123 VINE ST MURRAY, UT 84123",
"ownerAsOfDate": 1721813301,
"name": "NSF Checking",
"number": "0111",
"type": "checking",
"aggregationStatusCode": 0,
"currentBalance": 37700.65,
"availableBalance": 38000.45,
"balanceDate": 1721813306,
"transactions": [
{
"id": 101402234899,
"amount": -34,
"postedDate": 1708776000,
"description": "INSUFFICIENT FUNDS FEE FOR A $12",
"memo": ".07 ITEM - DETAILS: ALLSTATE INS",
"normalizedPayee": "Allstate",
"institutionTransactionId": "0000000000",
"category": "Low Balance"
},
{
"id": 101402234924,
"amount": -34,
"postedDate": 1706961600,
"description": "INSUFFICIENT FUNDS FEE FOR A $21",
"memo": ".50 ITEM - DETAILS: HK Paymt",
"normalizedPayee": "Insufficient",
"institutionTransactionId": "0000000000",
"category": "Low Balance"
},
{
"id": 101402234869,
"amount": -34,
"postedDate": 1679140800,
"description": "INSUFFICIENT FUNDS FEE FOR A $64",
"memo": ".64 ITEM - DETAILS: UI WEB PAYME",
"normalizedPayee": "Insufficient",
"institutionTransactionId": "0000000000",
"category": "Low Balance"
},
{
"id": 101402234923,
"amount": 34,
"postedDate": 1659009600,
"description": "INSUFFICIENT FUNDS FEE REFUND",
"normalizedPayee": "Insufficient",
"institutionTransactionId": "0000000000",
"category": "Low Balance"
}
],
"analytics": {
"transactionalAttributes": [
{
"attributeName": "CASH_OUTFLOW",
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 0,
"endDate": "2022-07-31",
"startDate": "2022-07-28"
},
{
"count": 5,
"endDate": "2022-08-31",
"max": -24,
"mean": -42.6,
"median": -34,
"min": -90,
"standardDeviation": 26.847718711279736,
"startDate": "2022-08-01",
"sum": -213
},
{
"count": 4,
"endDate": "2024-06-30",
"max": -26.23,
"mean": -31.0575,
"median": -32,
"min": -34,
"standardDeviation": 3.7300435654292294,
"startDate": "2024-06-01",
"sum": -124.23
},
{
"count": 3,
"endDate": "2024-07-24",
"max": -28,
"mean": -30.666666666666668,
"median": -30,
"min": -34,
"standardDeviation": 3.0550504633038935,
"startDate": "2024-07-01",
"sum": -92
}
],
"timeIntervalType": "MONTHLY_CALENDAR"
}
],
"streamIds": [
"68bdc784-89d6-4704-9ded-d3e0f706f9e1"
],
"transactionIds": [
"101402234901",
"101402234939",
"101402234879"
]
},
{
"attributeName": "CASH_INFLOW",
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 1,
"endDate": "2022-07-31",
"max": 34,
"mean": 34,
"median": 34,
"min": 34,
"startDate": "2022-07-28",
"sum": 34
},
{
"count": 0,
"endDate": "2022-08-31",
"startDate": "2022-08-01"
},
{
"count": 0,
"endDate": "2024-06-30",
"startDate": "2024-06-01"
},
{
"count": 0,
"endDate": "2024-07-24",
"startDate": "2024-07-01"
}
],
"timeIntervalType": "MONTHLY_CALENDAR"
}
],
"streamIds": [
"3dfd89be-33cc-484d-acbf-69587a0c44e6"
],
"transactionIds": [
"101402234943"
]
},
{
"attributeName": "ALL_CASH_FLOWS",
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 1,
"endDate": "2022-07-31",
"max": 34,
"mean": 34,
"median": 34,
"min": 34,
"startDate": "2022-07-28",
"sum": 34
},
{
"count": 5,
"endDate": "2022-08-31",
"max": -24,
"mean": -42.6,
"median": -34,
"min": -90,
"standardDeviation": 26.847718711279736,
"startDate": "2022-08-01",
"sum": -213
},
{
"count": 4,
"endDate": "2024-06-30",
"max": -26.23,
"mean": -31.0575,
"median": -32,
"min": -34,
"standardDeviation": 3.7300435654292294,
"startDate": "2024-06-01",
"sum": -124.23
},
{
"count": 3,
"endDate": "2024-07-24",
"max": -28,
"mean": -30.666666666666668,
"median": -30,
"min": -34,
"standardDeviation": 3.0550504633038935,
"startDate": "2024-07-01",
"sum": -92
}
],
"timeIntervalType": "MONTHLY_CALENDAR"
}
],
"streamIds": [
"bb12a859-09b7-4021-8ac5-522e01d00159"
],
"transactionIds": [
"101402234901",
"101402234883",
"101402234928",
"101402234879"
]
},
{
"attributeName": "NSF_FEE_CHARGES",
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 0,
"endDate": "2022-07-31",
"startDate": "2022-07-28"
},
{
"count": 5,
"endDate": "2022-08-31",
"max": -24,
"mean": -42.6,
"median": -34,
"min": -90,
"standardDeviation": 26.847718711279736,
"startDate": "2022-08-01",
"sum": -213
},
{
"count": 4,
"endDate": "2024-06-30",
"max": -26.23,
"mean": -31.0575,
"median": -32,
"min": -34,
"standardDeviation": 3.7300435654292294,
"startDate": "2024-06-01",
"sum": -124.23
},
{
"count": 3,
"endDate": "2024-07-24",
"max": -28,
"mean": -30.666666666666668,
"median": -30,
"min": -34,
"standardDeviation": 3.0550504633038935,
"startDate": "2024-07-01",
"sum": -92
}
],
"timeIntervalType": "MONTHLY_CALENDAR"
}
],
"streamIds": [
"68bdc784-89d6-4704-9ded-d3e0f706f9e1"
],
"transactionIds": [
"101402234891",
"101402234914",
"101402234900",
"101402234876"
]
},
{
"attributeName": "NSF_FEE_REVERSALS",
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 0,
"endDate": "2022-07-31",
"startDate": "2022-07-28"
},
{
"count": 0,
"endDate": "2022-08-31",
"startDate": "2022-08-01"
},
{
"count": 0,
"endDate": "2024-06-30",
"startDate": "2024-06-01"
},
{
"count": 0,
"endDate": "2024-07-24",
"startDate": "2024-07-01"
}
],
"timeIntervalType": "MONTHLY_CALENDAR"
}
],
"streamIds": [],
"transactionIds": []
}
],
"stateAttributes": [
{
"attributeName": "NET_CASH_FLOW",
"reportedByTimePeriods": [
{
"periods": [
{
"beginningValue": 34,
"count": 4,
"endDate": "2022-07-31",
"endingValue": 0,
"max": 34,
"mean": 8.5,
"median": 0,
"min": 0,
"standardDeviation": 17,
"startDate": "2022-07-28",
"sum": 34
},
{
"beginningValue": 0,
"count": 31,
"endDate": "2022-08-31",
"endingValue": 0,
"max": 0,
"mean": -6.870967741935484,
"median": 0,
"min": -90,
"standardDeviation": 20.144051124312725,
"startDate": "2022-08-01",
"sum": -213
},
{
"beginningValue": 0,
"count": 30,
"endDate": "2024-06-30",
"endingValue": 0,
"max": 0,
"mean": -4.141,
"median": 0,
"min": -34,
"standardDeviation": 10.804814492016813,
"startDate": "2024-06-01",
"sum": -124.23
},
{
"beginningValue": 0,
"count": 24,
"endDate": "2024-07-24",
"endingValue": 0,
"max": 0,
"mean": -3.8333333333333335,
"median": 0,
"min": -34,
"standardDeviation": 10.3992753370719,
"startDate": "2024-07-01",
"sum": -92
}
],
"timeIntervalType": "MONTHLY_CALENDAR"
}
]
}
],
"streams": [
{
"cadence": 0,
"id": "68bdc784-89d6-4704-9ded-d3e0f706f9e1",
"payee": "non-sufficient",
"payor": "NSF USER",
"recency": 696,
"transactionIds": [
"101402234865"
]
}
]
},
"currency": "USD"
}
],
"oauthEnabled": false
}
],
"customerAnalytics": {
"transactionalAttributes": [
{
"attributeName": "CASH_OUTFLOW",
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 18,
"endDate": "2022-07-31",
"max": -2.47,
"mean": -53.702222222222225,
"median": -22.965,
"min": -167.86,
"standardDeviation": 58.32137067254321,
"startDate": "2022-07-24",
"sum": -966.64
},
{
"count": 37,
"endDate": "2022-08-31",
"max": -2.5,
"mean": -62.64945945945946,
"median": -27.39,
"min": -1150,
"standardDeviation": 185.22983467912306,
"startDate": "2022-08-01",
"sum": -2318.03
},
{
"count": 10,
"endDate": "2024-06-30",
"max": -26.23,
"mean": -509.856,
"median": -300,
"min": -1358.11,
"standardDeviation": 597.0070650838229,
"startDate": "2024-06-01",
"sum": -5098.5599999999995
},
{
"count": 9,
"endDate": "2024-07-24",
"max": -28,
"mean": -562.9255555555555,
"median": -300,
"min": -1358.11,
"standardDeviation": 607.6863589079302,
"startDate": "2024-07-01",
"sum": -5066.33
}
],
"timeIntervalType": "MONTHLY_CALENDAR"
}
],
"streamIds": [
"bb12a859-09b7-4021-8ac5-522e01d00159",
"d0bbf017-2c98-4eb1-835c-66dbe0998b02",
"e19e1671-19a1-42b3-91f0-277c0a9dba89",
"68bdc784-89d6-4704-9ded-d3e0f706f9e1"
],
"transactionIds": [
"101402234822",
"101402234883",
"101402235089",
"101402234758"
]
},
{
"attributeName": "CASH_INFLOW",
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 2,
"endDate": "2022-07-31",
"max": 224,
"mean": 129,
"median": 129,
"min": 34,
"standardDeviation": 134.35028842544403,
"startDate": "2022-07-24",
"sum": 258
},
{
"count": 12,
"endDate": "2022-08-31",
"max": 522,
"mean": 243.70833333333334,
"median": 224,
"min": 130,
"standardDeviation": 104.15274149347228,
"startDate": "2022-08-01",
"sum": 2924.5
},
{
"count": 9,
"endDate": "2024-06-30",
"max": 1070,
"mean": 396.6666666666667,
"median": 60,
"min": 60,
"standardDeviation": 505,
"startDate": "2024-06-01",
"sum": 3570
},
{
"count": 9,
"endDate": "2024-07-24",
"max": 1070,
"mean": 396.6666666666667,
"median": 60,
"min": 60,
"standardDeviation": 505,
"startDate": "2024-07-01",
"sum": 3570
}
],
"timeIntervalType": "MONTHLY_CALENDAR"
}
],
"streamIds": [
"6c3fb158-b6c2-44f7-a528-28ebd60d4eb1"
],
"transactionIds": [
"101402235114",
"101402234793",
"101402235014",
"101402235455"
]
},
{
"attributeName": "ALL_CASH_FLOWS",
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 20,
"endDate": "2022-07-31",
"max": 224,
"mean": -35.432,
"median": -22.63,
"min": -167.86,
"standardDeviation": 84.59117856210726,
"startDate": "2022-07-24",
"sum": -708.64
},
{
"count": 49,
"endDate": "2022-08-31",
"max": 522,
"mean": 12.376938775510204,
"median": -21.82,
"min": -1150,
"standardDeviation": 214.3270055138106,
"startDate": "2022-08-01",
"sum": 606.47
},
{
"count": 19,
"endDate": "2024-06-30",
"max": 1070,
"mean": -80.45052631578946,
"median": -26.23,
"min": -1358.11,
"standardDeviation": 712.6092459208832,
"startDate": "2024-06-01",
"sum": -1528.5599999999997
},
{
"count": 18,
"endDate": "2024-07-24",
"max": 1070,
"mean": -83.12944444444443,
"median": 16,
"min": -1358.11,
"standardDeviation": 733.1695588612839,
"startDate": "2024-07-01",
"sum": -1496.3299999999997
}
],
"timeIntervalType": "MONTHLY_CALENDAR"
}
],
"streamIds": [
"3136487d-d9a7-4f89-a1f0-6e9415e053e7",
"3efccc82-01b9-497b-bf3f-27f215db2d96"
],
"transactionIds": [
"101402234891",
"101402234747",
"101402234831",
"101402235000"
]
},
{
"attributeName": "NSF_FEE_CHARGES",
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 2,
"endDate": "2022-07-31",
"max": -35,
"mean": -35,
"median": -35,
"min": -35,
"standardDeviation": 0,
"startDate": "2022-07-24",
"sum": -70
},
{
"count": 6,
"endDate": "2022-08-31",
"max": -24,
"mean": -41.333333333333336,
"median": -34.5,
"min": -90,
"standardDeviation": 24.21294419657937,
"startDate": "2022-08-01",
"sum": -248
},
{
"count": 5,
"endDate": "2022-09-30",
"max": -34,
"mean": -34.2,
"median": -34,
"min": -35,
"standardDeviation": 0.4472135954999579,
"startDate": "2022-09-01",
"sum": -171
},
{
"count": 3,
"endDate": "2022-10-31",
"max": -30,
"mean": -32.666666666666664,
"median": -34,
"min": -34,
"standardDeviation": 2.309401076758503,
"startDate": "2022-10-01",
"sum": -98
},
{
"count": 3,
"endDate": "2022-11-30",
"max": -34,
"mean": -34,
"median": -34,
"min": -34,
"standardDeviation": 0,
"startDate": "2022-11-01",
"sum": -102
},
{
"count": 3,
"endDate": "2022-12-31",
"max": -28,
"mean": -32,
"median": -34,
"min": -34,
"standardDeviation": 3.4641016151377544,
"startDate": "2022-12-01",
"sum": -96
},
{
"count": 3,
"endDate": "2023-01-31",
"max": -30,
"mean": -32.666666666666664,
"median": -34,
"min": -34,
"standardDeviation": 2.309401076758503,
"startDate": "2023-01-01",
"sum": -98
},
{
"count": 4,
"endDate": "2024-06-30",
"max": -26.23,
"mean": -31.0575,
"median": -32,
"min": -34,
"standardDeviation": 3.7300435654292294,
"startDate": "2024-06-01",
"sum": -124.23
},
{
"count": 3,
"endDate": "2024-07-24",
"max": -28,
"mean": -30.666666666666668,
"median": -30,
"min": -34,
"standardDeviation": 3.0550504633038935,
"startDate": "2024-07-01",
"sum": -92
}
],
"timeIntervalType": "MONTHLY_CALENDAR"
}
],
"streamIds": [
"bb12a859-09b7-4021-8ac5-522e01d00159",
"d0bbf017-2c98-4eb1-835c-66dbe0998b02",
"68bdc784-89d6-4704-9ded-d3e0f706f9e1"
],
"transactionIds": [
"101402234952",
"101402235803",
"101402235249",
"101402235478"
]
},
{
"attributeName": "NSF_FEE_REVERSALS",
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 0,
"endDate": "2022-07-31",
"startDate": "2022-07-24"
},
{
"count": 0,
"endDate": "2022-08-31",
"startDate": "2022-08-01"
},
{
"count": 0,
"endDate": "2024-06-30",
"startDate": "2024-06-01"
},
{
"count": 0,
"endDate": "2024-07-24",
"startDate": "2024-07-01"
}
],
"timeIntervalType": "MONTHLY_CALENDAR"
}
],
"streamIds": [],
"transactionIds": []
}
],
"stateAttributes": [
{
"attributeName": "NET_CASH_FLOW",
"reportedByTimePeriods": [
{
"periods": [
{
"beginningValue": -220.48000000000002,
"count": 8,
"endDate": "2022-07-31",
"endingValue": -329.4,
"max": 201.69,
"mean": -88.58,
"median": -84.805,
"min": -329.4,
"standardDeviation": 169.11989534055417,
"startDate": "2022-07-24",
"sum": -708.64
},
{
"beginningValue": 321,
"count": 31,
"endDate": "2022-08-31",
"endingValue": -43.64,
"max": 646,
"mean": 19.563548387096777,
"median": 0,
"min": -923.38,
"standardDeviation": 251.584474289762,
"startDate": "2022-08-01",
"sum": 606.47
},
{
"beginningValue": 0,
"count": 30,
"endDate": "2024-06-30",
"endingValue": 0,
"max": 3390,
"mean": -50.952,
"median": 0,
"min": -4974.33,
"standardDeviation": 1117.177412711036,
"startDate": "2024-06-01",
"sum": -1528.56
},
{
"beginningValue": 0,
"count": 24,
"endDate": "2024-07-24",
"endingValue": 0,
"max": 3390,
"mean": -62.34708333333333,
"median": 0,
"min": -4974.33,
"standardDeviation": 1254.1757580473845,
"startDate": "2024-07-01",
"sum": -1496.33
}
],
"timeIntervalType": "MONTHLY_CALENDAR"
}
]
}
],
"streams": [
{
"cadence": 0,
"id": "d0bbf017-2c98-4eb1-835c-66dbe0998b02",
"payee": "verizon",
"payor": "NSF USER",
"recency": 589,
"transactionIds": [
"101402234898"
]
},
{
"cadence": 5,
"id": "0139e287-041d-4c45-b51d-108d204c05e2",
"payee": "Account Owner (Name Unavailable)",
"payor": "capital1 bob jones",
"recency": 4,
"transactionIds": [
"101402235180"
]
},
{
"cadence": 73,
"id": "071c8894-460c-4b55-a0dd-783d420be32d",
"payee": "murphy express",
"payor": "Roberta Prohaska",
"recency": 307,
"transactionIds": [
"101402235534"
]
},
{
"cadence": 122,
"id": "649504d3-f9ef-4476-9743-ebf45563158d",
"payee": "renttrk-inco",
"payor": "Roberta Prohaska",
"recency": 322,
"transactionIds": [
"101402235506"
]
}
]
},
"gseEnabled": true
}
```
A human-readable PDF version of the report is available which is great for underwriters or any other manual viewing of the report.
How to read a Cash Flow Analytics report:
[Cash_Flow_Analytics_HTR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/Cash_Flow_Analytics_HTR.pdf) (4MB)
## Reading a Cash Flow Analytics JSON Report {#reading-a-cash-flow-analytics-json-report}
This section provides a detailed description of the structure and format of the JSON version of Cash Flow Analytics. It explains the key elements, fields, and their usage. Developers should use this as a reference when integrating, parsing, or processing the JSON report.
### Cashflow Analytics Attributes {#cashflow-analytics-attributes}
The above sample demonstrates some, if not all, Cashflow Analytics
attributes from the following table:
| Attribute | Definition | Type |
|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
| REVENUE | An identification of all transactions that are classified as business revenue. This is not applicable for personal cashflow report. | Transactional |
| NSF_FEE_CHARGES | Fees charged to the customer, by their financial institution - resulting from a lack of sufficient funds or low balance to cover a purchase. | Transactional |
| NSF_FEE_REVERSALS | Credit transaction of an NSF fee charged earlier. | Transactional |
| CASH_INFLOW | Credit transactions in a customer's account | Transactional |
| CASH_OUTFLOW | Debit/ Spend transactions in a customer's account | Transactional |
| ALL_CASH_FLOWS | This is an umbrella attribute which sums: - CASH_INFLOW - CASH_OUTFLOW | Transactional |
| NET_CASH_FLOW | Total Credits less Total Debits over a period of time and across all accounts owned by an individual or business. Calculation of net cash flow into or out of a customer's account(s). | State |
#### Time Interval types {#time-interval-types}
A report supports up to two time interval types currently. If you request
more than two interval types, the endpoint returns an
error `More than 2 intervalTypes passed request`. If the time
interval type is not specified, the default is `MONTHLY_CALENDAR`.
The following table shows all possible time interval types you can request a report for:
| Time Interval Type | Description | First (Earliest) period may be partial | First (Most Recent) period may be partial | Shortest possible period length | Longest possible period length |
|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|-------------------------------------------|---------------------------------|--------------------------------|
| DAILY | The report will be broken up into one period for every calendar date in the report time period | NO | NO | 1 | 1 |
| WEEKLY_CALENDAR | The report time period will be broken up into periods of 7 calendar dates, each beginning on Monday and ending on Sunday, except the first and last periods which may be partial | YES | YES | 1 | 7 |
| WEEKLY_ROLLING_7 | The report time period will be broken up into periods of 7 calendar dates, counting backwards from the report end date | YES | NO | 1 | 7 |
| BI_WEEKLY_CALENDAR | The report time period will be broken up into periods of 14 calendar dates, each beginning on a Monday and ending on the 2nd subsequent Sunday, except the first and last periods which may be partial | YES | YES | 1 | 14 |
| BI_WEEKLY_ROLLING_14 | The report time period will be broken up into periods of 14 calendar dates, counting backwards from the report end date | YES | NO | 1 | 14 |
| SEMI_MONTHLY_CALENDAR | The report time period will be broken up into exactly 2 periods per calendar month, where both the first and last period may be partial, and periods will alternate between representing the 1st-15th and the 16th-end of the month | YES | YES | 1 | 16 |
| MONTHLY_CALENDAR | The report time period will be broken up into 1 period per calendar month | YES | YES | 1 | 31 |
| MONTHLY_ROLLING_30 | The report time period will be broken up into 11 periods of 30 calendar dates followed by 1 period of 35 (or 36 for leap years) calendar dates to make one full calendar year, starting backwards from the report end date | YES | NO | 1 | 36 |
| QUARTERLY_CALENDAR | The report time period will be broken up into 1 period per 3 calendar months, where both the first and last period may be partial | YES | YES | 1 | 92 |
| QUARTERLY_ROLLING_90 | The report time period will be broken up into 3 periods of 90 calendar dates followed by 1 period of 95 (or 96 for leap years) calendar dates to make one full calendar year, starting backwards from the report end date | YES | NO | 1 | 96 |
| ANNUALLY | The report time period will be broken up into periods of 365 calendar dates (or 366 for leap years), starting backwards from the report end date | YES | NO | 1 | 366 |
| HISTORICALLY | The report time period will be represented by exactly 1 period covering the duration of report data | NO | NO | 1 | Duration of report data |
The following JSON snippet shows an example of how time interval type is
requested:
* Json
```json
{
"constraints": {
"analyticsReportData": {
"timeIntervalTypes": [
"MONTHLY_CALENDAR",
"ANNUALLY"
]
}
}
}
```
### JSON report structure - Analytics section {#json-report-structure---analytics-section}
Analytics will be provided at both the account level, grouped by
(financial) institution, and at an aggregated customer level, similar to
how most other Lend and OBB products work today. The following examples
show a customer with two accounts that contain transactions.
* Json
```json
"accounts": [
{
"id": 1065737689
},
{
"id": 1065737690
}
]
```
The analytics section is divided into 3 sections:
1. Transactional attributes
2. State attributes
3. Streams
#### Account-level analytics structure {#account-level-analytics-structure}
* Json
```json
"analytics": {
"transactionalAttributes": [...
],
"stateAttributes": [...
],
"streams": [...
]
}
```
Note: This section will be for each of the customer accounts.
#### Customer-level analytics structure {#customer-level-analytics-structure}
* Json
```json
"customerAnalytics": {
"transactionalAttributes": [...
],
"stateAttributes": [...
],
"streams": [...
]
}
```
### Transactional attributes {#transactional-attributes}
Transactional attributes are based on a unit of data being a transaction
itself. They are evaluated as events in time. A transactional attribute
represents some classification or categorization of a customer's
underlying transactions. As an example, an attribute called
DWELLING_EXPENSES may be a classification of all transactions that we
assume to be a customer paying towards a mortgage, rent, home insurance,
etc. Transactional attributes will be reported by one of the below time
interval type specified in the constraints by the requesting partner.
The following JSON snippets are for transactional attributes on accounts and
customer level. Please note the following:
1. For demonstration purposes, the below snippets show transaction data
of 1 month for MONTHLY_CALENDAR time interval type. The actual
report will have all transaction stats for all the months.
2. The period array for ANNUALLY will show aggregated data for all the
months between the specified start and end dates.
3. Not all attributes are showcased. Please access the attribute table
above to see all the Cashflow Analytics attributes.
4. The data in the below snippets are for *Cashflow_Analytics* report
which is attached above.
* Json
```json
"transactionalAttributes": [
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 2,
"endDate": "2023-12-31",
"max": -12.11,
"mean": -12.21,
"median": -12.21,
"min": -12.31,
"standardDeviation": 0.14142135623731025,
"startDate": "2023-12-01",
"sum": -24.42,
"comparedToCohorts": []
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-12-01",
"endDate": "2023-12-31",
"cohortValues": []
}
]
},
{
"periods": [
{
"count": 18,
"endDate": "2024-06-23",
"max": -1.2,
"mean": -6.9911111111111115,
"median": -7.140000000000001,
"min": -12.31,
"standardDeviation": 3.617743672656446,
"startDate": "2023-06-24",
"sum": -125.84,
"comparedToCohorts": []
}
],
"timeIntervalType": "ANNUALLY",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-06-24",
"endDate": "2024-06-23",
"cohortValues": []
}
]
}
],
"attributeName": "CASH_OUTFLOW",
"streamIds": [
"ae6bec67-e1a0-4ff4-8220-8439398a373e"
],
"transactionIds": [
"128512270764",
"128512270796",
"128512270747",
"128512270771",
"128512270746",
"128512270756",
"128512270773",
"128512270780",
"128512270798",
"128512270758",
"128512268825",
"128512270797",
"128512270776",
"128512268830",
"128512268821",
"128512268816",
"128512268815",
"128512268829"
],
"projectedValues": [],
"streamConfidences": null
},
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 2,
"endDate": "2023-12-31",
"max": 12.21,
"mean": 12.11,
"median": 12.11,
"min": 12.01,
"standardDeviation": 0.14142135623731025,
"startDate": "2023-12-01",
"sum": 24.22,
"comparedToCohorts": []
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-12-01",
"endDate": "2023-12-31",
"cohortValues": []
}
]
},
{
"periods": [
{
"count": 19,
"endDate": "2024-06-23",
"max": 12.21,
"mean": 6.6352631578947365,
"median": 6.24,
"min": 1.1,
"standardDeviation": 3.5608962174353,
"startDate": "2023-06-24",
"sum": 126.07,
"comparedToCohorts": []
}
],
"timeIntervalType": "ANNUALLY",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-06-24",
"endDate": "2024-06-23",
"cohortValues": []
}
]
}
],
"attributeName": "CASH_INFLOW",
"streamIds": [
"e6ea8ff3-6995-440f-8c6e-9d26bb61b2a4"
],
"transactionIds": [
"128512270757",
"128512270751",
"128512268827",
"128512270770",
"128512270769",
"128512268812",
"128512268817",
"128512268819",
"128512270752",
"128512270753",
"128512270790",
"128512270792",
"128512270768",
"128512268824",
"128512268828",
"128512270791",
"128512270772",
"128512270783",
"128512270784"
],
"projectedValues": [],
"streamConfidences": null
},
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 4,
"endDate": "2023-12-31",
"max": 12.21,
"mean": -0.04999999999999982,
"median": -0.04999999999999982,
"min": -12.31,
"standardDeviation": 14.041633333293769,
"startDate": "2023-12-01",
"sum": -0.1999999999999993,
"comparedToCohorts": []
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-12-01",
"endDate": "2023-12-31",
"cohortValues": []
}
]
},
{
"periods": [
{
"count": 37,
"endDate": "2024-06-23",
"max": 12.21,
"mean": 0.006216216216216155,
"median": 1.1,
"min": -12.31,
"standardDeviation": 7.75851587731949,
"startDate": "2023-06-24",
"sum": 0.22999999999999776,
"comparedToCohorts": []
}
],
"timeIntervalType": "ANNUALLY",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-06-24",
"endDate": "2024-06-23",
"cohortValues": []
}
]
}
],
"attributeName": "ALL_CASH_FLOWS",
"streamIds": [
"ae6bec67-e1a0-4ff4-8220-8439398a373e",
"e6ea8ff3-6995-440f-8c6e-9d26bb61b2a4"
],
"transactionIds": [
"128512270764",
"128512270796",
"128512270747",
"128512270771",
"128512270746",
"128512270756",
"128512270773",
"128512270780",
"128512270798",
"128512270758",
"128512268825",
"128512270797",
"128512270776",
"128512268830",
"128512268821",
"128512268816",
"128512268815",
"128512268829",
"128512270757",
"128512270751",
"128512268827",
"128512270770",
"128512270769",
"128512268812",
"128512268817",
"128512268819",
"128512270752",
"128512270753",
"128512270790",
"128512270792",
"128512270768",
"128512268824",
"128512268828",
"128512270791",
"128512270772",
"128512270783",
"128512270784"
],
"projectedValues": [],
"streamConfidences": null
}
]
```
* Json
```json
"transactionalAttributes": [
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 2,
"endDate": "2023-12-31",
"max": -12.11,
"mean": -12.21,
"median": -12.21,
"min": -12.31,
"standardDeviation": 0.14142135623731025,
"startDate": "2023-12-01",
"sum": -24.42,
"comparedToCohorts": []
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-12-01",
"endDate": "2023-12-31",
"cohortValues": []
}
]
},
{
"periods": [
{
"count": 18,
"endDate": "2024-06-23",
"max": -1.2,
"mean": -6.9911111111111115,
"median": -7.140000000000001,
"min": -12.31,
"standardDeviation": 3.617743672656446,
"startDate": "2023-06-24",
"sum": -125.84,
"comparedToCohorts": []
}
],
"timeIntervalType": "ANNUALLY",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-06-24",
"endDate": "2024-06-23",
"cohortValues": []
}
]
}
],
"attributeName": "CASH_OUTFLOW",
"streamIds": [
"9ef16f42-baa9-47ba-a936-564ce19fb9ee"
],
"transactionIds": [
"128512270962",
"128512270955",
"128512270954",
"128512270956",
"128512268805",
"128512270976",
"128512270940",
"128512270960",
"128512268803",
"128512268800",
"128512268799",
"128512270943",
"128512270942",
"128512270938",
"128512268808",
"128512268807",
"128512268793",
"128512270953"
],
"projectedValues": [],
"streamConfidences": null
},
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 2,
"endDate": "2023-12-31",
"max": 12.21,
"mean": 12.11,
"median": 12.11,
"min": 12.01,
"standardDeviation": 0.14142135623731025,
"startDate": "2023-12-01",
"sum": 24.22,
"comparedToCohorts": []
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-12-01",
"endDate": "2023-12-31",
"cohortValues": []
}
]
},
{
"periods": [
{
"count": 19,
"endDate": "2024-06-23",
"max": 12.21,
"mean": 6.6352631578947365,
"median": 6.24,
"min": 1.1,
"standardDeviation": 3.5608962174353,
"startDate": "2023-06-24",
"sum": 126.07,
"comparedToCohorts": []
}
],
"timeIntervalType": "ANNUALLY",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-06-24",
"endDate": "2024-06-23",
"cohortValues": []
}
]
}
],
"attributeName": "CASH_INFLOW",
"streamIds": [
"2efb4258-4457-4391-8f40-4bfd973af49a"
],
"transactionIds": [
"128512268809",
"128512270973",
"128512270963",
"128512270935",
"128512268798",
"128512270951",
"128512270961",
"128512270941",
"128512270972",
"128512268801",
"128512270959",
"128512270932",
"128512270939",
"128512268794",
"128512270967",
"128512270952",
"128512270946",
"128512270948",
"128512268802"
],
"projectedValues": [],
"streamConfidences": null
},
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 4,
"endDate": "2023-12-31",
"max": 12.21,
"mean": -0.04999999999999982,
"median": -0.04999999999999982,
"min": -12.31,
"standardDeviation": 14.041633333293769,
"startDate": "2023-12-01",
"sum": -0.1999999999999993,
"comparedToCohorts": []
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-12-01",
"endDate": "2023-12-31",
"cohortValues": []
}
]
},
{
"periods": [
{
"count": 37,
"endDate": "2024-06-23",
"max": 12.21,
"mean": 0.006216216216216155,
"median": 1.1,
"min": -12.31,
"standardDeviation": 7.75851587731949,
"startDate": "2023-06-24",
"sum": 0.22999999999999776,
"comparedToCohorts": []
}
],
"timeIntervalType": "ANNUALLY",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-06-24",
"endDate": "2024-06-23",
"cohortValues": []
}
]
}
],
"attributeName": "ALL_CASH_FLOWS",
"streamIds": [
"9ef16f42-baa9-47ba-a936-564ce19fb9ee",
"2efb4258-4457-4391-8f40-4bfd973af49a"
],
"transactionIds": [
"128512268809",
"128512270973",
"128512270963",
"128512270935",
"128512268798",
"128512270951",
"128512270961",
"128512270941",
"128512270972",
"128512268801",
"128512270959",
"128512270932",
"128512270939",
"128512268794",
"128512270967",
"128512270952",
"128512270946",
"128512270948",
"128512268802"
],
"projectedValues": [],
"streamConfidences": null
}
]
```
##### JSON fields description {#json-fields-description}
| Key (Datatype) | Description | Applicable for Cashflow Analytics |
|-------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|
| **aggregatedByTimePeriods** (object) | An object that contains periods object data, comparedToCohorts object data, and time interval type. | Yes |
| **periods** (object) | Statistics of aggregated transactions over some time period. | Yes |
| **count** (number) | For the selected time interval type, the number of transaction events that occurred during the period. For example, for monthly time interval, count will be shown for each month of a year. | Yes |
| **endDate** (string) | For the selected time interval type, the final day (inclusive) of the period being reported. For example, for monthly time interval, endDate will be shown for each month of a year. | Yes |
| **max** (number) | For the selected time interval type, the maximum value of all transaction amounts in the period. For example, for monthly time interval, max will be shown for each month of a year. | Yes |
| **mean** (number) | For the selected time interval type, the mean value of all transaction amounts in the period. For example, for monthly time interval, mean will be shown for each month of a year. | Yes |
| **median** (number) | For the selected time interval type, the median value of all transaction amounts in the period. For example, for monthly time interval, median will be shown for each month of a year. | Yes |
| **min** (number) | For the selected time interval type, the minimum value of all transaction amounts in the period. For example, for monthly time interval, min will be shown for each month of a year. | Yes |
| **standardDeviation** (number) | For the selected time interval type, the standard deviation of all transaction amounts in the period. For example, for monthly time interval, standardDeviation will be shown for each month of a year. | Yes |
| **startDate** (string) | For the selected time interval type, the first day (inclusive) of the period being reported. For example, for monthly time interval, startDate will be shown for each month of a year. | Yes |
| **sum** (number) | For the selected time interval type, the arithmetic sum of the amounts of all transactions in the period. For example, for monthly time interval, sum will be shown for each month of a year. | Yes |
| **comparedToCohorts** (object) | An array of elements comparing the customer's spending during a time period to the average customer's spending in various cohorts, such as postal code, during the same time period. | No |
| **cohortType** (string) | Describes the type of cohort being compared to for this period, e.g. POSTAL_CODE | No |
| **totalDifferenceToCohort** (number) | Reflects the difference between the customer's spending for the period minus that of the average spending in this cohort. | No |
| **percentageDifferenceToCohort** (number) | Reflects the percentage difference between the customer's sum value for the period and the average of the cohort | No |
| **timeIntervalType** (string) | See *Time Interval Types* above for how each period is defined. | Yes |
| **cohortBenchmarkPeriods** (object) | A list of objects where each object is a period of the same duration as those in aggregatedByTimePeriods, describing the spending of cohorts in the customer's zip code during that period for an attribute. | Yes |
| **startDate** (string) | The first day of the cohort benchmark period. | Yes |
| **endDate** (string) | The final day of the cohort benchmark period. | Yes |
| **cohortValues** (object) | An object that contains type and value of a cohort benchmark period. | No |
| **cohortType** (string) | For each cohort benchmark period, the type of cohort we have a representative metric for, e.g. POSTAL_CODE. | No |
| **value** (number) | For each cohort benchmark period, the average spending of the cohort during this time period. | No |
| **attributeName** (string) | Name of the attribute that we are reporting the numbers for. Refer to the attributes list above. | Yes |
| **streamIds** | List of stream IDs associated with the attribute. See more details about "Streams" below | Yes |
| **transactionIds** (object) | List of transaction IDs associated with the attribute. | Yes |
| **projectedValues** (object) | List of projection objects, where each object indicates the projected sum value of the attribute over some coming period of time. | No |
| **timeUnit** (string) | The unit of time being described, e.g. MONTHS | No |
| **timeValue** (number) | The number of timeUnit units for which we are projecting, e.g. 12 (for 12 months) | No |
| **projectionValue** (number) | The predicted sum value of the attribute over the coming timeValue number of timeUnits. | No |
| **streamConfidences** (object) | List of stream confidences, indicating the confidence in which we believe each stream is correctly associated with this attribute. | No |
| **streamId** (string) | The stream ID we are reporting the confidence for. | No |
| **confidence** (number) | A float value between 0 and 100 indicating the confidence over whether a stream is correctly associated to an income attribute | No |
### State attributes {#state-attributes}
The unit of data for state attributes is some generic "state" at a point
in time. Whereas transactional attributes are based on specific events
(the posting of a transaction), state attributes make some inference
about a point in time based on some assembly of underlying data.
Examples of state attributes might include something like the balance of
an account over time, a calculation based on underlying transactions in
a time period (e.g. net cash flow), or some other calculation such as a
debt to income ratio.
The following JSON snippets for transactional attributes on accounts and
customer level. Please note the following:
1. For demonstration purposes, the below snippets show transaction data
of 1 month for MONTHLY_CALENDAR time interval type. The actual
report will have all transaction stats for all the months.
2. The period array for ANNUALLY will show aggregated data for all the
months between the specified start and end dates.
3. The data in the below snippets are for *Cashflow_Analytics* report
which is attached above.
* Json
```json
"stateAttributes": [
{
"attributeName": "NET_CASH_FLOW",
"reportedByTimePeriods": [
{
"periods": [
{
"beginningValue": 12.01,
"count": 31,
"endDate": "2023-12-31",
"endingValue": -12.31,
"max": 12.21,
"mean": -0.006451612903225784,
"median": 0.0,
"min": -12.31,
"standardDeviation": 4.44038703147004,
"startDate": "2023-12-01",
"sum": -0.1999999999999993,
"comparedToCohorts": []
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-12-01",
"endDate": "2023-12-31",
"cohortValues": []
}
]
},
{
"periods": [
{
"beginningValue": 6.24,
"count": 366,
"endDate": "2024-06-23",
"endingValue": 0.0,
"max": 12.21,
"mean": 0.000628415300546442,
"median": 0.0,
"min": -12.31,
"standardDeviation": 2.436596410931794,
"startDate": "2023-06-24",
"sum": 0.22999999999999776,
"comparedToCohorts": []
}
],
"timeIntervalType": "ANNUALLY",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-06-24",
"endDate": "2024-06-23",
"cohortValues": []
}
]
}
],
"projectedValues": []
}
]
```
* Json
```json
"stateAttributes": [
{
"attributeName": "NET_CASH_FLOW",
"reportedByTimePeriods": [
{
"periods": [
{
"beginningValue": 12.01,
"count": 31,
"endDate": "2023-12-31",
"endingValue": -12.31,
"max": 12.21,
"mean": -0.006451612903225784,
"median": 0.0,
"min": -12.31,
"standardDeviation": 4.44038703147004,
"startDate": "2023-12-01",
"sum": -0.1999999999999993,
"comparedToCohorts": []
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-12-01",
"endDate": "2023-12-31",
"cohortValues": []
}
]
},
{
"periods": [
{
"beginningValue": 6.24,
"count": 366,
"endDate": "2024-06-23",
"endingValue": 0.0,
"max": 12.21,
"mean": 0.000628415300546442,
"median": 0.0,
"min": -12.31,
"standardDeviation": 2.436596410931794,
"startDate": "2023-06-24",
"sum": 0.22999999999999776,
"comparedToCohorts": []
}
],
"timeIntervalType": "ANNUALLY",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-06-24",
"endDate": "2024-06-23",
"cohortValues": []
}
]
}
],
"projectedValues": []
}
]
```
* Json
```json
"stateAttributes": [
{
"attributeName": "NET_CASH_FLOW",
"reportedByTimePeriods": [
{
"periods": [
{
"beginningValue": 24.02,
"count": 31,
"endDate": "2023-12-31",
"endingValue": -24.62,
"max": 24.42,
"mean": -0.012903225806451568,
"median": 0.0,
"min": -24.62,
"standardDeviation": 8.88077406294008,
"startDate": "2023-12-01",
"sum": -0.3999999999999986,
"comparedToCohorts": []
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-12-01",
"endDate": "2023-12-31",
"cohortValues": []
}
]
},
{
"periods": [
{
"beginningValue": 12.48,
"count": 366,
"endDate": "2024-06-23",
"endingValue": 0.0,
"max": 24.42,
"mean": 0.001256830601092884,
"median": 0.0,
"min": -24.62,
"standardDeviation": 4.873192821863588,
"startDate": "2023-06-24",
"sum": 0.4599999999999955,
"comparedToCohorts": []
}
],
"timeIntervalType": "ANNUALLY",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-06-24",
"endDate": "2024-06-23",
"cohortValues": []
}
]
}
],
"projectedValues": []
}
]
```
#### JSON fields description {#json-fields-description-1}
While most of the keys overlap with transactional attributes, the
following are state attributes-specific keys:
| Key (Datatype) | Description |
|------------------------------------|------------------------------------------------------------------------|
| **reportedByTimePeriods** (object) | Value of the "state" over some time periods |
| **beginningValue** (number) | Value of the "state" as reported on the `startDate` of the period |
| **endingValue** (number) | Value of the "state" as reported on the `endDate` of the period |
| **count** (number) | Occurrences of the "state" between specified `startDate` and `endDate` |
### Streams {#streams}
Streams are groups of transactions that represent a repeated flow of
funds for some consistent purpose between two parties (or accounts, if the
same entity owns both the source and destination of funds). Examples of
streams include: bi-weekly paychecks from an employer to an employee, a
customer's monthly phone bill paid to a telecom provider, a customer's
monthly transfer from a checking account to an investment account, etc.
Since a stream is just a group of transactions, a transactional
attribute can assign a list of streams to itself if the transactions in
that stream all fit the same classification being described by the
attribute.
* Json
```json
"streams": [
{
"cadence": 20,
"id": "ae6bec67-e1a0-4ff4-8220-8439398a373e",
"payee": "walmart",
"payor": "JOHN DOE",
"recency": 20,
"earliestObservedDate": null,
"latestObservedDate": null,
"count": null,
"sum": null,
"status": "active",
"min": null,
"max": null,
"mean": null,
"median": null,
"standardDeviation": null,
"minimumCadence": null,
"maximumCadence": null,
"medianCadence": null,
"modeCadence": null,
"standardDeviationCadence": null,
"transactionIds": [
"128512270764",
"128512270796",
"128512270747",
"128512270771",
"128512270746",
"128512270756",
"128512270773",
"128512270780",
"128512270798",
"128512270758",
"128512268825",
"128512270797",
"128512270776",
"128512268830",
"128512268821",
"128512268816",
"128512268815",
"128512268829"
]
},
{
"cadence": 20,
"id": "e6ea8ff3-6995-440f-8c6e-9d26bb61b2a4",
"payee": "JOHN DOE",
"payor": "walmart",
"recency": 30,
"earliestObservedDate": null,
"latestObservedDate": null,
"count": null,
"sum": null,
"status": "inactive",
"min": null,
"max": null,
"mean": null,
"median": null,
"standardDeviation": null,
"minimumCadence": null,
"maximumCadence": null,
"medianCadence": null,
"modeCadence": null,
"standardDeviationCadence": null,
"transactionIds": [
"128512270757",
"128512270751",
"128512268827",
"128512270770",
"128512270769",
"128512268812",
"128512268817",
"128512268819",
"128512270752",
"128512270753",
"128512270790",
"128512270792",
"128512270768",
"128512268824",
"128512268828",
"128512270791",
"128512270772",
"128512270783",
"128512270784"
]
}
]
```
* Json
```json
"streams": [
{
"cadence": 20,
"id": "9ef16f42-baa9-47ba-a936-564ce19fb9ee",
"payee": "walmart",
"payor": "JOHN DOE",
"recency": 20,
"earliestObservedDate": null,
"latestObservedDate": null,
"count": null,
"sum": null,
"status": "active",
"min": null,
"max": null,
"mean": null,
"median": null,
"standardDeviation": null,
"minimumCadence": null,
"maximumCadence": null,
"medianCadence": null,
"modeCadence": null,
"standardDeviationCadence": null,
"transactionIds": [
"128512270962",
"128512270955",
"128512270954",
"128512270956",
"128512268805",
"128512270976",
"128512270940",
"128512270960",
"128512268803",
"128512268800",
"128512268799",
"128512270943",
"128512270942",
"128512270938",
"128512268808",
"128512268807",
"128512268793",
"128512270953"
]
},
{
"cadence": 20,
"id": "2efb4258-4457-4391-8f40-4bfd973af49a",
"payee": "JOHN DOE",
"payor": "walmart",
"recency": 30,
"earliestObservedDate": null,
"latestObservedDate": null,
"count": null,
"sum": null,
"status": "inactive",
"min": null,
"max": null,
"mean": null,
"median": null,
"standardDeviation": null,
"minimumCadence": null,
"maximumCadence": null,
"medianCadence": null,
"modeCadence": null,
"standardDeviationCadence": null,
"transactionIds": [
"128512268809",
"128512270973",
"128512270963",
"128512270935",
"128512268798",
"128512270951",
"128512270961",
"128512270941",
"128512270972",
"128512268801",
"128512270959",
"128512270932",
"128512270939",
"128512268794",
"128512270967",
"128512270952",
"128512270946",
"128512270948",
"128512268802"
]
}
]
```
* Json
```json
"streams": [
{
"cadence": 20,
"id": "ae6bec67-e1a0-4ff4-8220-8439398a373e",
"payee": "walmart",
"payor": "JOHN DOE",
"recency": 20,
"earliestObservedDate": null,
"latestObservedDate": null,
"count": null,
"sum": null,
"status": "active",
"min": null,
"max": null,
"mean": null,
"median": null,
"standardDeviation": null,
"minimumCadence": null,
"maximumCadence": null,
"medianCadence": null,
"modeCadence": null,
"standardDeviationCadence": null,
"transactionIds": [
"128512270764",
"128512270796",
"128512270747",
"128512270771",
"128512270746",
"128512270756",
"128512270773",
"128512270780",
"128512270798",
"128512270758",
"128512268825",
"128512270797",
"128512270776",
"128512268830",
"128512268821",
"128512268816",
"128512268815",
"128512268829"
]
},
{
"cadence": 20,
"id": "e6ea8ff3-6995-440f-8c6e-9d26bb61b2a4",
"payee": "JOHN DOE",
"payor": "walmart",
"recency": 30,
"earliestObservedDate": null,
"latestObservedDate": null,
"count": null,
"sum": null,
"status": "inactive",
"min": null,
"max": null,
"mean": null,
"median": null,
"standardDeviation": null,
"minimumCadence": null,
"maximumCadence": null,
"medianCadence": null,
"modeCadence": null,
"standardDeviationCadence": null,
"transactionIds": [
"128512270757",
"128512270751",
"128512268827",
"128512270770",
"128512270769",
"128512268812",
"128512268817",
"128512268819",
"128512270752",
"128512270753",
"128512270790",
"128512270792",
"128512270768",
"128512268824",
"128512268828",
"128512270791",
"128512270772",
"128512270783",
"128512270784"
]
},
{
"cadence": 20,
"id": "9ef16f42-baa9-47ba-a936-564ce19fb9ee",
"payee": "walmart",
"payor": "JOHN DOE",
"recency": 20,
"earliestObservedDate": null,
"latestObservedDate": null,
"count": null,
"sum": null,
"status": "active",
"min": null,
"max": null,
"mean": null,
"median": null,
"standardDeviation": null,
"minimumCadence": null,
"maximumCadence": null,
"medianCadence": null,
"modeCadence": null,
"standardDeviationCadence": null,
"transactionIds": [
"128512270962",
"128512270955",
"128512270954",
"128512270956",
"128512268805",
"128512270976",
"128512270940",
"128512270960",
"128512268803",
"128512268800",
"128512268799",
"128512270943",
"128512270942",
"128512270938",
"128512268808",
"128512268807",
"128512268793",
"128512270953"
]
},
{
"cadence": 20,
"id": "2efb4258-4457-4391-8f40-4bfd973af49a",
"payee": "JOHN DOE",
"payor": "walmart",
"recency": 30,
"earliestObservedDate": null,
"latestObservedDate": null,
"count": null,
"sum": null,
"status": "inactive",
"min": null,
"max": null,
"mean": null,
"median": null,
"standardDeviation": null,
"minimumCadence": null,
"maximumCadence": null,
"medianCadence": null,
"modeCadence": null,
"standardDeviationCadence": null,
"transactionIds": [
"128512268809",
"128512270973",
"128512270963",
"128512270935",
"128512268798",
"128512270951",
"128512270961",
"128512270941",
"128512270972",
"128512268801",
"128512270959",
"128512270932",
"128512270939",
"128512268794",
"128512270967",
"128512270952",
"128512270946",
"128512270948",
"128512268802"
]
}
]
```
#### JSON fields description {#json-fields-description-2}
While most of the keys overlap with transactional attributes, the
following are stream attributes-specific keys:
| Key (Datatype) | Description |
|---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
| **cadence** (number) | The average number of days elapsed between consecutive transactions in the stream |
| **id** (string) | A randomly generated UUID to uniquely identify the stream |
| **payee** (string) | The party that is receiving the funds |
| **payor** (string) | The party that is sending the funds |
| **recency** (number) | The number of days elapsed since the most recent transaction in the stream |
| **earliestObservedDate** (string) | The date-time of the first observed transaction in the stream |
| **latestObservedDate** (string) | The date-time of the last observed transaction in the stream |
| **status** (string) | Active or inactive, depending on if the duration since the last transaction in the stream exceeds the historically observed cadence |
| **minimumCadence** (number) | The smallest observed duration of time elapsed between any 2 consecutive transactions in the stream |
| **maximumCadence** (number) | The largest observed duration of time elapsed between any 2 consecutive transactions in the stream |
| **medianCadence** (number) | The median number of days elapsed between consecutive transactions in the stream |
| **modeCadence** (number) | The most frequently observed number of days elapsed between consecutive transactions in the stream |
| **standardDeviationCadence** (number) | The standard deviation of the number of days elapsed between consecutive transactions in the stream |
| **transactionIds** (object) | A list of all the transaction IDs that were assigned to the stream |
## Testing {#testing}
Refer to [Generating Reports -- Testing](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#testing).
Ensure you use a test profile that contains supported account types such as [Profile_03](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#oauth-connection-profiles).