# Balance Analytics source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/balance-analytics/index.md ## Overview {#overview} Balance Analytics (BA) provides insights into a customer's account balances over time, helping assess liquidity, trends, and potential risk for lending and portfolio decisions. BA analyzes up to 24 months of transaction history (as available) and returns attributes such as minimum, maximum, and average balances over the desired time intervals. Learn more about Mastercard's [Assets \& Balances](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#assets-and-balances) solutions. ### 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 `fromDate` and defaults to 24 months * **Balance Analytics:** Includes min, max, and average cash balance attributes by requested time interval * **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 #### Additional Product Information {#additional-product-information} * **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 Balance Analytics product can be used for the following use cases: * Auto * Credit Card Issuance * Credit Line Management * Customer / Portfolio Monitoring * Debt Collection * [Mortgage Lending](https://developer.mastercard.com/open-finance-us/documentation/usecases/mortgage-lending/index.md) * 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 Mastercard 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 record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers) * [Create a consumer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) 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 Balance Analytics Report {#generate-a-balance-analytics-report} To generate or refresh a Balance Analytics report, use the following endpoint: API Reference: `POST /decisioning/v2/customers/{customerId}/reports/balance-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. * Use the `timeIntervalType` to select the periodicity at which attributes will be calculated. Defaults to Monthly Calendar. * Customize the type of Balance 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 | |-------------|----------------------|-----------------|---------------------------------|-------------------|-------------------|-------------------| | barpcra | personal | true | N/A | true | true | false | | barpnoncra | personal | false | N/A | false | true | false | | barbcra | business | true | true | true | true | true | | barbftc | business | true | false | false | true | true | | barbnoncra | business | false | false | false | true | true | ### Get Balance Analytics Reports {#get-balance-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": "sd1j45yn37wr-barpcra", "customerType": "active", "customerId": 1275320, "requestId": "7a7qyps2iy", "requesterName": "Decisioning API", "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 Balance Analytics", "consumerId": "3f7ff2cf0ffb3d0cd59875e070c9b1d4", "consumerSsn": "1234", "disputeStatement": "Invalid data present.", "constraints": { "analyticsReportData": { "forCraPurpose": true, "timeIntervalTypes": [ "MONTHLY_CALENDAR" ] } }, "type": "barpcra", "status": "success", "createdDate": 1579819592, "startDate": 1512594823, "endDate": 1575666823, "days": 730, "institutions": [ { "id": "102105", "name": "FinBank Profiles", "urlHomeApp": "http://www.bank.example.com", "accounts": [ { "id": "1111", "ownerName": "PATRICK & LORRAINE PURCHASER", "ownerAddress": "7195 BELMONT ST. PARLIN, NJ 08859", "ownerAsOfDate": 1577986990, "name": "Checking", "number": "XX1111", "type": "checking", "aggregationStatusCode": "0", "currentBalance": 100000, "availableBalance": 1000, "balanceDate": 1614880526, "transactions": [ { "id": "00000001", "amount": -81.7, "postedDate": 1614859200, "description": "TMOBILE*AUTO PAY", "normalizedPayee": "T-Mobile", "institutionTransactionId": "0000000000", "category": "Mobile Phone" }, { "id": "00000002", "amount": -81.7, "postedDate": 1614859200, "description": "TMOBILE*AUTO PAY", "normalizedPayee": "T-Mobile", "institutionTransactionId": "0000000000", "category": "Mobile Phone" }, { "id": "00000003", "amount": -81.7, "postedDate": 1614859200, "description": "TMOBILE*AUTO PAY", "normalizedPayee": "T-Mobile", "institutionTransactionId": "0000000000", "category": "Mobile Phone" }, { "id": "00000004", "amount": -81.7, "postedDate": 1614859200, "description": "TMOBILE*AUTO PAY", "normalizedPayee": "T-Mobile", "institutionTransactionId": "0000000000", "category": "Mobile Phone" } ], "analytics": [ { "transactionalAttributes": [], "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "timeIntervalType": "MONTHLY_CALENDAR", "periods": [ { "startDate": "2023-02-05", "endDate": "2023-02-28", "sum": 75517.99999999997, "count": 24, "mean": 3146.583333333333, "median": 3145.2, "min": 3145.2, "max": 3178.4, "standardDeviation": 6.776921621700182, "beginningValue": 3145.2, "endingValue": 3178.4 }, { "startDate": "2023-03-01", "endDate": "2023-03-31", "sum": 95350.54000000005, "count": 31, "mean": 3075.823870967742, "median": 3178.4, "min": 2946.3, "max": 3329.22, "standardDeviation": 132.58604314877732, "beginningValue": 3178.4, "endingValue": 3329.22 } ] } ] } ], "streams": [ { "id": "2b96f6d4-4882-4db2-96c6-f89530a68f1c", "payor": "TD AMERITRADE", "payee": "John Smith", "cadence": 15, "recency": 124, "transactionIds": [ "00000003", "00000004", "00000001" ] }, { "id": "dafc9b5d-762d-4f91-a429-f80573944bcd", "payor": "John Smith", "payee": "TD AMERITRADE", "cadence": 0, "recency": 139, "transactionIds": [ "00000002" ] } ] } ] }, { "id": "2222", "ownerName": "PATRICK & LORRAINE PURCHASER", "ownerAddress": "7195 BELMONT ST. PARLIN, NJ 08859", "ownerAsOfDate": 1577986990, "name": "Checking", "number": "XX1111", "type": "checking", "aggregationStatusCode": "0", "currentBalance": 100000, "availableBalance": 1000, "balanceDate": 1614880526, "transactions": [ { "id": "00000005", "amount": -81.7, "postedDate": 1614859200, "description": "TMOBILE*AUTO PAY", "normalizedPayee": "T-Mobile", "institutionTransactionId": "0000000000", "category": "Mobile Phone" }, { "id": "00000006", "amount": -81.7, "postedDate": 1614859200, "description": "TMOBILE*AUTO PAY", "normalizedPayee": "T-Mobile", "institutionTransactionId": "0000000000", "category": "Mobile Phone" }, { "id": "00000007", "amount": -81.7, "postedDate": 1614859200, "description": "TMOBILE*AUTO PAY", "normalizedPayee": "T-Mobile", "institutionTransactionId": "0000000000", "category": "Mobile Phone" }, { "id": "00000008", "amount": -81.7, "postedDate": 1614859200, "description": "TMOBILE*AUTO PAY", "normalizedPayee": "T-Mobile", "institutionTransactionId": "0000000000", "category": "Mobile Phone" } ], "analytics": [ { "transactionalAttributes": [], "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "timeIntervalType": "MONTHLY_CALENDAR", "periods": [ { "startDate": "2023-02-05", "endDate": "2023-02-28", "sum": 75517.99999999997, "count": 24, "mean": 3146.583333333333, "median": 3145.2, "min": 3145.2, "max": 3178.4, "standardDeviation": 6.776921621700182, "beginningValue": 3145.2, "endingValue": 3178.4 }, { "startDate": "2023-03-01", "endDate": "2023-03-31", "sum": 95350.54000000005, "count": 31, "mean": 3075.823870967742, "median": 3178.4, "min": 2946.3, "max": 3329.22, "standardDeviation": 132.58604314877732, "beginningValue": 3178.4, "endingValue": 3329.22 } ] } ] } ], "streams": [ { "id": "b838ffb3-2549-43b3-a1b1-50bc13438e0f", "payor": "John Smith", "payee": "Whole Foods", "cadence": 0, "recency": 124, "transactionIds": [ "00000005", "00000008" ] }, { "id": "54214633-39d7-43f4-9314-bae2ce3b6af9", "payor": "John Smith", "payee": "Walmart", "cadence": 0, "recency": 139, "transactionIds": [ "00000006", "00000007" ] } ] } ] } ] } ], "customerAnalytics": { "transactionalAttributes": [], "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "timeIntervalType": "MONTHLY_CALENDAR", "periods": [ { "startDate": "2023-02-05", "endDate": "2023-02-28", "sum": 75517.99999999997, "count": 24, "mean": 3146.583333333333, "median": 3145.2, "min": 3145.2, "max": 3178.4, "standardDeviation": 6.776921621700182, "beginningValue": 3145.2, "endingValue": 3178.4 }, { "startDate": "2023-03-01", "endDate": "2023-03-31", "sum": 95350.54000000005, "count": 31, "mean": 3075.823870967742, "median": 3178.4, "min": 2946.3, "max": 3329.22, "standardDeviation": 132.58604314877732, "beginningValue": 3178.4, "endingValue": 3329.22 } ] } ] } ], "streams": [ { "id": "2b96f6d4-4882-4db2-96c6-f89530a68f1c", "payor": "TD AMERITRADE", "payee": "John Smith", "cadence": 15, "recency": 124, "transactionIds": [ "00000003", "00000004", "00000001" ] }, { "id": "dafc9b5d-762d-4f91-a429-f80573944bcd", "payor": "John Smith", "payee": "TD AMERITRADE", "cadence": 0, "recency": 139, "transactionIds": [ "00000002" ] }, { "id": "b838ffb3-2549-43b3-a1b1-50bc13438e0f", "payor": "John Smith", "payee": "Whole Foods", "cadence": 0, "recency": 124, "transactionIds": [ "00000005", "00000008" ] }, { "id": "54214633-39d7-43f4-9314-bae2ce3b6af9", "payor": "John Smith", "payee": "Walmart", "cadence": 0, "recency": 139, "transactionIds": [ "6010290887", "6010290914" ] } ] } } ``` 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 Balance Analytics report: [Balance_Analytics_HTR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/Balance_Analytics_HTR.pdf) (3MB) ## Reading a Balance Analytics JSON Report {#reading-a-balance-analytics-json-report} This section provides a detailed description of the structure and format of the JSON version of Balance 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. ### Balance Analytics Attributes {#balance-analytics-attributes} The above sample demonstrates some, if not all, Balance Analytics attributes from the following table: | Attribute | Definition | Type | |---------------|----------------------------------------------------------------|-------| | ASSET_BALANCE | History of asset balances for the customer and their accounts. | State | ### Time Interval types {#time-interval-types} A report supports up to 2 time interval types currently. If a partner requests more than 2 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. For the purpose of this document, consider a customer with the following two accounts that contain transactions: * Json ```json "accounts": [ { "id": 8059411974 }, { "id": 8059411978 } ] ``` 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 time interval type specified in the constraints by the requesting partner. *Currently, Balance Analytics does not have any transactional attributes.* ### 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. * Json ```json "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 609.5, "count": 31, "endDate": "2024-12-31", "endingValue": 621.7, "max": 621.7, "mean": 614.158064516129, "median": 609.5, "min": 609.4, "standardDeviation": 6.025654829894631, "startDate": "2024-12-01", "sum": 19038.9, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2024-12-01", "endDate": "2024-12-31", "cohortValues": [] } ] }, { "periods": [ { "beginningValue": 618.61, "count": 365, "endDate": "2025-06-18", "endingValue": 618.49, "max": 623.78, "mean": 618.0496712328767, "median": 619.59, "min": 609.4, "standardDeviation": 4.681207449827294, "startDate": "2024-06-19", "sum": 225588.13, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2024-06-19", "endDate": "2025-06-18", "cohortValues": [] } ] } ], "projectedValues": [] } ] ``` * Json ```json "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 609.5, "count": 31, "endDate": "2024-12-31", "endingValue": 621.7, "max": 621.7, "mean": 614.158064516129, "median": 609.5, "min": 609.4, "standardDeviation": 6.025654829894631, "startDate": "2024-12-01", "sum": 19038.9, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2024-12-01", "endDate": "2024-12-31", "cohortValues": [] } ] }, { "periods": [ { "beginningValue": 1855.83, "count": 365, "endDate": "2025-06-18", "endingValue": 618.49, "max": 623.78, "mean": 618.0496712328767, "median": 619.59, "min": 609.4, "standardDeviation": 4.681207449827294, "startDate": "2024-06-19", "sum": 225588.13, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2024-06-19", "endDate": "2025-06-18", "cohortValues": [] } ] } ], "projectedValues": [] } ] ``` * Json ```json "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 1828.5, "count": 31, "endDate": "2024-12-31", "endingValue": 1865.1000000000001, "max": 1865.1000000000001, "mean": 1842.4741935483871, "median": 1828.5, "min": 1828.1999999999998, "standardDeviation": 18.07696448968397, "startDate": "2024-12-01", "sum": 57116.7, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2024-12-01", "endDate": "2024-12-31", "cohortValues": [] } ] }, { "periods": [ { "beginningValue": 1855.83, "count": 365, "endDate": "2025-06-18", "endingValue": 2473.96, "max": 2473.96, "mean": 1855.843506849315, "median": 1858.77, "min": 1828.1999999999998, "standardDeviation": 35.351654853132914, "startDate": "2024-06-19", "sum": 677382.88, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2024-06-19", "endDate": "2025-06-18", "cohortValues": [] } ] } ], "projectedValues": [] } ] ``` ### JSON fields description {#json-fields-description} | Key (Datatype) | Description | Applicable for Balance Analytics | |---------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------| | attributeName (string) | Name of the attribute that we are reporting the numbers for. Refer to the attributes list above. | Yes | | reportedByTimePeriods (object) | An object that contains periods object data, comparedToCohorts object data, and time interval type | | | periods (object) | Statistics of aggregated transactions over some time period. | | | beginningValue (number) | Value of the attribute as reported on the startDate of the period. | | | endingValue (number) | Value of the attribute as reported on the endDate of the period. | | | count (number) | For the selected time interval type, the number of state events that occurred during the period. For example, for monthly time interval, count will be shown for each day of the month. | | | endDate (string) | For the selected time interval type, the final day (inclusive) of the period being reported. | | | max (number) | For the selected time interval type, the maximum value in the period. | | | mean (number) | For the selected time interval type, the mean value in the period. | | | median (number) | For the selected time interval type, the median value in the period. | | | min (number) | For the selected time interval type, the minimum value in the period. | | | standardDeviation (number) | For the selected time interval type, the standard deviation in the period. | | | startDate (string) | For the selected time interval type, the first day (inclusive) of the period being reported. | | | sum (number) | For the selected time interval type, the arithmetic sum for the period. | | | comparedToCohorts (object) | An array comparing the customer's spending during a time period to the average customer's spending in various cohorts (e.g., 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. | | | totalDifferenceToCohort (number) | The difference between the customer's spending for the period minus the average spending in this cohort. | | | percentageDifferenceToCohort (number) | The percentage difference between the customer's sum value for the period and the average of the cohort. | | | timeIntervalType (string) | See Time Interval Types above for how each period is defined. | | | 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. | | | endDate (string) | The final day of the cohort benchmark period. | | | 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. | | | value (number) | For each cohort benchmark period, the average spending of the cohort during this time period. | | | streamIds | List of stream IDs associated with the attribute. | No | | 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. | | | timeUnit (string) | The unit of time being described, e.g., MONTHS. | | | timeValue (number) | The number of timeUnit units for which we are projecting, e.g., 12 (for 12 months). | | | projectionValue (number) | The predicted sum value of the attribute over the coming timeValue number of timeUnits. | | | streamConfidences (object) | List of stream confidences, indicating the confidence in which we believe each stream is correctly associated with this attribute. | | | streamId (string) | The stream ID we are reporting the confidence for. | | | confidence (number) | A float value between 0 and 100 indicating the confidence over whether a stream is correctly associated to an income attribute. | | ### Streams {#streams} Streams are groups of transactions that represent a repeated flow of funds for some consistent purpose between 2 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": "688992c4-263b-4220-9c57-ed8e42489340", "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": [ "28985672772", "28985672796", "28985653969", "28985672790", "28985672769", "28985672774", "28985653982", "28985672779", "28985672806", "28985672801", "28985672802", "28985672765", "28985672815", "28985672799", "28985653976", "28985653979", "28985672782", "28985672805", "28985653983", "28985672783", "28985672766", "28985672817", "28985672785", "28985672818", "28985653986", "28985672794", "28985672784", "28985653978", "28985653987", "28985672780", "28985672816", "28985672795", "28985653971", "28985672793", "28985672777", "28985672797" ] } ] ``` * Json ```json "streams": [ { "cadence": 20, "id": "4c7f0a3e-7d7f-4294-b8c0-07ff5563217f", "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": [ "28985654346", "28985675175", "28985675171", "28985675206", "28985654342", "28985675203", "28985675190", "28985654354", "28985675191", "28985675189", "28985675222", "28985675224", "28985675172", "28985675211", "28985654359", "28985675208", "28985675221", "28985654351", "28985675198", "28985675188", "28985654355", "28985654358", "28985675223", "28985654350", "28985675184", "28985675200", "28985675179", "28985675183", "28985675187", "28985654341", "28985675207", "28985675202", "28985675212", "28985675201", "28985675181", "28985675196" ] } ] ``` ### JSON fields description {#json-fields-description-1} | 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).