# Consumer Foresight (Preview)
source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/consumer-foresight-preview/index.md
Alert: The new **Generate Non CRA Foresight Analytics Report Using 1st/3rd Party Transaction Data** endpoint described on this page is coming soon but is **not yet available**.
This is a preview of the documentation. See the current
[Consumer Foresight](https://developer.mastercard.com/open-finance-us/documentation/products/manage/consumer-foresight/index.md) page to learn how the service
works now.
The new endpoint will provide the option to use first-party data you submitted through
[Data Enrichment](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/index.md).
To get a report using first-party data,
you will be able to use the new endpoint as described in [How It Works](https://developer.mastercard.com/open-finance-us/documentation/products/manage/consumer-foresight-preview/index.md#how-it-works).
The [legacy endpoint](https://developer.mastercard.com/open-finance-us/documentation/products/manage/consumer-foresight-preview/index.md#legacy-endpoint) will remain available.
Consumer Foresight is an API based solution designed to help banks and Fintechs personalize consumer experiences for use cases like personal financial management (PFM), marketing/product segmentation, alerts/nudges to drive better financial decisions, and other personalization use cases. The service provides tailored consumer insights for end users against 16 different spend categories.
These insights can be generated using the end user's third-party permissioned Open Finance data, and/or your own first-party data submitted via [Data Enrichment](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/index.md), as well as anonymized transactional data from the Mastercard network for benchmarking.
For each category, Consumer Foresight delivers:
* Historical Spending: Historical spending patterns aggregated by each spend category for a historical view of a consumer over the last 12 months.
* Benchmarking: Spending benchmarked against 'like' peers, definable by location, age and income.
* Forecasting: Data Science modeling predicts anticipated customer spending in each spending category for 3, 6, 9, and 12 months into the future.
Note: Consumer Foresight is currently in Beta. Contact your Sales representative or Account manager to learn more.
These insights are delivered on a per category basis and can be used to power more personalized experiences and messaging to end users.
Note: This is a subscription service. You will be billed for each customer you generate a report for in a given month. Additional report refreshes for the same customer in the same month are free.
## Use Cases {#use-cases}
* Personal financial management
* Product and marketing personalization
* Consumer alerts and behavior nudges
* Spending health checks
## Benchmarking Options {#benchmarking-options}
Consumer Foresight enables you to benchmark a consumer's spending in each category
against one or more comparison groups.
When you generate a report, you can use parameters to choose whether to
benchmark against consumers with similar:
* age
* income
* ZIP/postal code
You must use at least one parameter.
If you use multiple parameters, the report benchmarks the consumer against
each parameter, both individually and also in combination.
For example, if you specify age and income, the response will include comparisons
to consumers with similar age, consumers with similar income, and consumers
with both similar age and income.
## Third-Party and First-Party Data {#third-party-and-first-party-data}
The updated Consumer Foresight endpoint can use:
* **third-party data**: account and transaction data authorized by the customer through Mastercard Data Connect from external institutions.
* **first-party data** : customer transaction data you have provided through the Open Finance [Data Enrichment](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/index.md) service.
You can combine both sources of data into a single report.
## How It Works {#how-it-works}
1. Generate the required credentials to call the API. See [Create a Sandbox Project](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#create-a-sandbox-project).
2. Generate an Access Token. See [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token).
3. Create a customer and link them to at least one account via Data Connect and/or submit data for them via Data Enrichment. See [Welcome Your First Customer](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#welcome-your-first-customer). Review the different [Bank Account Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#bank-account-profiles) and account types available for testing Data Connect in Sandbox - the report only works if the customer has a checking, credit card or savings account.
4. Call [Generate Non CRA Foresight Analytics Report Using 1st/3rd Party Transaction Data](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GenerateForesightAnalyticsFirstThirdPartyNonCraReport) with selected input parameters. The response `id` element contains the report ID.
* To use third-party data permissioned via Data Connect, provide a `customerId` in the request body.
* To use first-party data you submitted via [Data Enrichment](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/index.md), provide the `externalCustomerId` you supplied when uploading the data.
* You can use third-party data, first-party data, or both in the same request.
API Reference: `POST /decisioning/reports/foresight-analytics/userTypes/{userType}`
5. Call [Get Report by Report ID](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetReportById) using the report ID. Returns a JSON file with spending insights and forecasts.
API Reference: `POST /decisioning/v3/reports/{reportId}`
Warning: You must use **Get Report by Report ID** to retrieve reports generated with the latest endpoint. Other Get Report endpoints are not supported. Diagram consumer-foresight
## Reading a Consumer Foresight JSON Report {#reading-a-consumer-foresight-json-report}
This section provides a detailed description of the structure and format of the Consumer Foresight JSON report. It explains the key elements, fields, and their usage. Developers should use this as a reference when integrating, parsing, or processing the JSON report. The JSON report is generated to provide data in a structured and machine-readable format.
#### Example JSON Reports {#example-json-reports}
The response contains different data depending on the selected input parameters. The following downloadable examples show successful responses.
This example shows the output of profile-524 used in the Sandbox, benchmarked by postal code:
[farpbfnoncra-profile-524.json](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/farpbfnoncra-profile-524.json) (1MB)
This example shows the output when benchmarking by postal code, age and income:
[farpbfnoncra-multisegment.json](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/farpbfnoncra-multisegment.json) (167KB)
#### Consumer Foresight Attributes {#consumer-foresight-attributes}
| Attribute | Definition | Type |
|---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
| ACCOMMODATION_SPENDING | Expenses related to accommodations such as hotels. | Transactional |
| BOOKS_SPENDING | Expenses incurred for book purchases or reading. | Transactional |
| CLOTHING_SPENDING | Expenses towards the purchase of clothes. | Transactional |
| COMMUNICATION_SERVICES_SPENDING | Expenses incurred on phone, internet, broadband, television. | Transactional |
| CONSUMER_ELECTRONICS_SPENDING | Electronics and software related expenses. | Transactional |
| EATING_PLACES_SPENDING | Expenses incurred due to eating activities such as restaurants and coffee shops. | Transactional |
| ENTERTAINMENT_SPENDING | Entertainment related expenses such as amusement, music and alcohol. | Transactional |
| FINANCIAL_SERVICES_SPENDING | Expenses incurred due to availing financial services such as financial advisors, trade commissions and late payments. | Transactional |
| FUEL_SPENDING | Expenses related to gas and fuel. | Transactional |
| GROCERIES_SPENDING | Expenses towards groceries. | Transactional |
| HEALTH_BEAUTY_MEDICAL_SPENDING | Expenses incurred due to personal health management activities such as gyms, dentists, hair, doctors and fitness. | Transactional |
| HOME_IMPROVEMENT_SPENDING | Expenses incurred for home improvement such as furniture and supplies. | Transactional |
| PHARMACY_SPENDING | Pharmacy related expenses such as the purchase of drugs and medical tests. | Transactional |
| TOTAL_SPENDING | Total consumer spending for all transaction categories except for transfers, income, wealth management, and credit card payments | Transactional |
| TRAVEL_SPENDING | Expenses incurred as a result of travelling such as air travel, rental cars, taxis, and other forms of transportation. | Transactional |
| UTILITIES_SPENDING | Utility related expenses like bill payments. | Transactional |
| DISCRETIONARY_SPENDING | This is an umbrella group that sums: ACCOMMODATION_SPENDING BOOKS_SPENDING CONSUMER_ELECTRONICS_SPENDING EATING_PLACES_SPENDING ENTERTAINMENT_SPENDING HEALTH_BEAUTY_MEDICAL_SPENDING HOME_IMPROVEMENT_SPENDING TRAVEL_SPENDING | Transactional |
| NONDISCRETIONARY_SPENDING | This is an umbrella group that sums: CLOTHING_SPENDING COMMUNICATION_SERVICES_SPENDING FINANCIAL_SERVICES_SPENDING FUEL_SPENDING GROCERIES_SPENDING INSURANCE_SPENDING PHARMACY_SPENDING UTILITIES_SPENDING | Transactional |
#### Time Interval Types {#time-interval-types}
A report supports up to two time interval types. If a partner requests for more than two interval types, the end point gives the error: `More than 2 intervalTypes passed request.` If the time interval type is not specified, the default is MONTHLY_CALENDAR. The table shows all possible time interval types for which a partner can request a report.
| 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 seven calendar dates, with each period beginning on a Monday and ending on a Sunday, with the exception of 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 seven 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, with each period beginning on a Monday and ending on the second subsequent Sunday, with the exception of 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 two periods per calendar month, where both the first and the last period may be partial, and periods will alternate between representing the 1st:15th of the month and the 16th: end of the month. | YES | YES | 1 | 16 |
| MONTHLY_CALENDAR | The report time period will be broken up into one 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 one 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 one period per three 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 three periods of 90 calendar dates followed by one 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 one period. | NO | NO | 1 | Duration of report data |
The JSON snippet shows an example of how a time interval type is represented.
* Json
```json
"constraints": {
"analyticsReportData": {
"timeIntervalTypes": [
"MONTHLY_CALENDAR",
"ANNUALLY"
]
}
}
```
#### JSON report structure - Analytics section {#json-report-structure---analytics-section}
Analytics will be provided at the account level, grouped by financial institution and at an aggregated customer level. The following examples show a customer with two accounts that contain transactions.
* Json
```json
"accounts": [
{
"id": 1005572173
},
{
"id": 1005572174
}
]
```
The analytics section is divided into three sections.
* Transactional attributes
* State attributes-not applicable to Consumer Foresight
* Streams-not applicable to Consumer Foresight
**Account-level analytics structure**
This section is for each of the customer accounts.
* Json
```json
"analytics": {
"transactionalAttributes": [...
],
"stateAttributes": [...
],
"streams": [...
]
}
```
**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. For example, an attribute called FUEL_SPENDING may be a classification of all transactions that we assume to be a customer paying towards fuel or gas.
The following sample JSON snippets are for transactional attributes on accounts and customer levels.
* The sample snippets show transaction data of one month for MONTHLY_CALENDAR time interval type as an example. The actual report has all transaction stats for all the months.
* The period array for ANNUALLY shows aggregated data for all the months between the specified start and end dates.
* Not all attributes are showcased. Refer to the attribute table to view all Foresight attributes.
* The data in the snippets are for profile-524 with some modifications.
NONDISCRETIONARY_SPENDING will have aggregated data of COMMUNICATION_SERVICES_SPENDING and UTILITIES_SPENDING.
* Json
```json
"transactionalAttributes": [
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 2,
"endDate": "2025-03-31",
"max": -89.91,
"mean": -94.115,
"median": -94.115,
"min": -98.32,
"standardDeviation": 5.9467680297788625,
"startDate": "2025-03-01",
"sum": -188.23,
"comparedToCohorts": [
{
"cohortType": "POSTAL_CODE",
"totalDifferenceToCohort": 278.08,
"percentageDifferenceToCohort": 59.63
}
]
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2025-03-01",
"endDate": "2025-03-31",
"cohortValues": [
{
"cohortType": "POSTAL_CODE",
"value": "-466.31"
}
]
}
]
},
{
"periods": [
{
"count": 5,
"endDate": "2025-03-04",
"max": -87.51,
"mean": -93.438,
"median": -94.115,
"min": -100.72,
"standardDeviation": 5.9467680297788625,
"startDate": "2024-03-05",
"sum": -467.19,
"comparedToCohorts": [
{
"cohortType": "POSTAL_CODE",
"totalDifferenceToCohort": 655.10,
"percentageDifferenceToCohort": 58.37
}
]
}
],
"timeIntervalType": "ANNUALLY",
"cohortBenchmarkPeriods": [
{
"startDate": "2024-03-05",
"endDate": "2025-03-04",
"cohortValues": [
{
"cohortType": "POSTAL_CODE",
"value": "-1122.29"
}
]
}
]
}
],
"attributeName": "COMMUNICATION_SERVICES_SPENDING",
"streamIds": [],
"transactionIds": [
"100393337806",
"100393337807",
"100393337808",
"100393337809",
"100393337810"
],
"projectedValues": [
{
"timeUnit": "MONTHS",
"timeValue": 3,
"projectionValue": -595.23
},
{
"timeUnit": "MONTHS",
"timeValue": 6,
"projectionValue": -1190.45
},
{
"timeUnit": "MONTHS",
"timeValue": 9,
"projectionValue": -1785.68
},
{
"timeUnit": "MONTHS",
"timeValue": 12,
"projectionValue": -2380.9
}
],
"streamConfidences": null
},
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 3,
"endDate": "2025-03-31",
"max": -70.55,
"mean": -107.12333333333333,
"median": -102.0,
"min": -148.82,
"standardDeviation": 39.385716107915734,
"startDate": "2025-03-01",
"sum": -321.37,
"comparedToCohorts": [
{
"cohortType": "POSTAL_CODE",
"totalDifferenceToCohort": 45.67,
"percentageDifferenceToCohort": 12.44
}
]
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2025-03-01",
"endDate": "2025-03-31",
"cohortValues": [
{
"cohortType": "POSTAL_CODE",
"value": "-367.04"
}
]
}
]
},
{
"periods": [
{
"count": 6,
"endDate": "2025-03-04",
"max": -67.51,
"mean": -108.713,
"median": -105.115,
"min": -148.82,
"standardDeviation": 39.385716107915734,
"startDate": "2024-03-05",
"sum": -652.28,
"comparedToCohorts": [
{
"cohortType": "POSTAL_CODE",
"totalDifferenceToCohort": 55.55,
"percentageDifferenceToCohort": 7.85
}
]
}
],
"timeIntervalType": "ANNUALLY",
"cohortBenchmarkPeriods": [
{
"startDate": "2024-03-05",
"endDate": "2025-03-04",
"cohortValues": [
{
"cohortType": "POSTAL_CODE",
"value": "-707.83"
}
]
}
]
}
],
"attributeName": "UTILITIES_SPENDING",
"streamIds": [],
"transactionIds": [
"100393337811",
"100393337812",
"100393337813",
"100393337814",
"100393337815",
"100393337816"
],
"projectedValues": [
{
"timeUnit": "MONTHS",
"timeValue": 3,
"projectionValue": -895.54
},
{
"timeUnit": "MONTHS",
"timeValue": 6,
"projectionValue": -1791.08
},
{
"timeUnit": "MONTHS",
"timeValue": 9,
"projectionValue": -2686.62
},
{
"timeUnit": "MONTHS",
"timeValue": 12,
"projectionValue": -3582.15
}
],
"streamConfidences": null
},
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 5,
"endDate": "2025-03-31",
"max": -70.55,
"mean": -101.92,
"median": -98.32,
"min": -148.82,
"standardDeviation": 28.900230967935187,
"startDate": "2025-03-01",
"sum": -509.59999999999997,
"comparedToCohorts": [
{
"cohortType": "POSTAL_CODE",
"totalDifferenceToCohort": -509.6
}
]
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2025-03-01",
"endDate": "2025-03-31",
"cohortValues": [
{
"cohortType": "POSTAL_CODE",
"value": "0.0"
}
]
}
]
},
{
"periods": [
{
"count": 11,
"endDate": "2025-03-04",
"max": -67.51,
"mean": -101.77,
"median": -105.115,
"min": -148.82,
"standardDeviation": 39.385716107915734,
"startDate": "2024-03-05",
"sum": -1119.47,
"comparedToCohorts": [
{
"cohortType": "POSTAL_CODE",
"totalDifferenceToCohort": 710.65,
"percentageDifferenceToCohort": 38.83
}
]
}
],
"timeIntervalType": "ANNUALLY",
"cohortBenchmarkPeriods": [
{
"startDate": "2024-03-05",
"endDate": "2025-03-04",
"cohortValues": [
{
"cohortType": "POSTAL_CODE",
"value": "-1830.12"
}
]
}
]
}
],
"attributeName": "NONDISCRETIONARY_SPENDING",
"streamIds": [],
"transactionIds": [
"100393337806",
"100393337807",
"100393337808",
"100393337809",
"100393337810"
"100393337811",
"100393337812",
"100393337813",
"100393337814",
"100393337815",
"100393337816"
],
"projectedValues": [],
"streamConfidences": null
}
]
```
Note: NONDISCRETIONARY_SPENDING will have aggregated data of COMMUNICATION_SERVICES_SPENDING. DISCRETIONARY_SPENDING will have aggregated data of ENTERTAINMENT_SPENDING.
* Json
```json
"transactionalAttributes": [
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 4,
"endDate": "2025-03-31",
"max": -101.13,
"mean": -45.93,
"median": -36.98,
"min": -8.63,
"standardDeviation": 45.48252411641201,
"startDate": "2025-03-01",
"sum": -183.72,
"comparedToCohorts": [
{
"cohortType": "POSTAL_CODE",
"totalDifferenceToCohort": 282.59,
"percentageDifferenceToCohort": 60.6
}
]
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2025-03-01",
"endDate": "2025-03-31",
"cohortValues": [
{
"cohortType": "POSTAL_CODE",
"value": "-466.31"
}
]
}
]
}
],
"attributeName": "COMMUNICATION_SERVICES_SPENDING",
"streamIds": [],
"transactionIds": [
"100393337866",
"100393337868",
"100393337869",
"100393337871"
],
"projectedValues": [
{
"timeUnit": "MONTHS",
"timeValue": 3,
"projectionValue": -538.45
},
{
"timeUnit": "MONTHS",
"timeValue": 6,
"projectionValue": -1076.89
},
{
"timeUnit": "MONTHS",
"timeValue": 9,
"projectionValue": -1615.34
},
{
"timeUnit": "MONTHS",
"timeValue": 12,
"projectionValue": -2153.78
}
],
"streamConfidences": null
},
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 1,
"endDate": "2025-01-31",
"max": -102.0,
"mean": -102.0,
"median": -102.0,
"min": -102.0,
"startDate": "2025-01-01",
"sum": -102.0,
"comparedToCohorts": [
{
"cohortType": "POSTAL_CODE",
"totalDifferenceToCohort": 265.04,
"percentageDifferenceToCohort": 72.21
}
]
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2025-03-01",
"endDate": "2025-03-31",
"cohortValues": [
{
"cohortType": "POSTAL_CODE",
"value": "-367.04"
}
]
}
]
}
],
"attributeName": "ENTERTAINMENT_SPENDING",
"streamIds": [],
"transactionIds": [
"100393337856"
],
"projectedValues": [
{
"timeUnit": "MONTHS",
"timeValue": 3,
"projectionValue": -68.06
},
{
"timeUnit": "MONTHS",
"timeValue": 6,
"projectionValue": -136.12
},
{
"timeUnit": "MONTHS",
"timeValue": 9,
"projectionValue": -204.19
},
{
"timeUnit": "MONTHS",
"timeValue": 12,
"projectionValue": -272.25
}
],
"streamConfidences": null
},
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 1,
"endDate": "2025-01-31",
"max": -102.0,
"mean": -102.0,
"median": -102.0,
"min": -102.0,
"startDate": "2025-01-01",
"sum": -102.0,
"comparedToCohorts": [
{
"cohortType": "POSTAL_CODE",
"totalDifferenceToCohort": 265.04,
"percentageDifferenceToCohort": 72.21
}
]
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2025-03-01",
"endDate": "2025-03-31",
"cohortValues": [
{
"cohortType": "POSTAL_CODE",
"value": "0.0"
}
]
}
]
}
],
"attributeName": "DISCRETIONARY_SPENDING",
"streamIds": [],
"transactionIds": [
"100393337856"
],
"projectedValues": [],
"streamConfidences": null
},
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 4,
"endDate": "2025-03-31",
"max": -8.63,
"mean": -45.93,
"median": -36.98,
"min": -101.13,
"standardDeviation": 45.48252411641201,
"startDate": "2025-03-01",
"sum": -183.72,
"comparedToCohorts": [
{
"cohortType": "POSTAL_CODE",
"totalDifferenceToCohort": 282.59,
"percentageDifferenceToCohort": 60.6
}
]
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2025-03-01",
"endDate": "2025-03-31",
"cohortValues": [
{
"cohortType": "POSTAL_CODE",
"value": "0.0"
}
]
}
]
}
],
"attributeName": "NONDISCRETIONARY_SPENDING",
"streamIds": [],
"transactionIds": [
"100393337866",
"100393337868",
"100393337869",
"100393337871"
],
"projectedValues": [],
"streamConfidences": null
}
]
```
Note: NONDISCRETIONARY_SPENDING will have aggregated data of COMMUNICATION_SERVICES_SPENDING. DISCRETIONARY_SPENDING will have aggregated data of ENTERTAINMENT_SPENDING.
* Json
```json
"transactionalAttributes": [
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 6,
"endDate": "2025-03-31",
"max": -101.13,
"mean": 61.99166667,
"median": -60.98,
"min": -8.63,
"standardDeviation": 35.48252411641201,
"startDate": "2025-03-01",
"sum": -371.95,
"comparedToCohorts": [
{
"cohortType": "POSTAL_CODE",
"totalDifferenceToCohort": 94.36,
"percentageDifferenceToCohort": 20.24
}
]
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2025-03-01",
"endDate": "2025-03-31",
"cohortValues": [
{
"cohortType": "POSTAL_CODE",
"value": "-466.31"
}
]
}
]
}
],
"attributeName": "COMMUNICATION_SERVICES_SPENDING",
"streamIds": [],
"transactionIds": [
"100393337806",
"100393337807",
"100393337866",
"100393337868",
"100393337869",
"100393337871"
],
"projectedValues": [
{
"timeUnit": "MONTHS",
"timeValue": 3,
"projectionValue": -1133.67
},
{
"timeUnit": "MONTHS",
"timeValue": 6,
"projectionValue": -2267.34
},
{
"timeUnit": "MONTHS",
"timeValue": 9,
"projectionValue": -3401.02
},
{
"timeUnit": "MONTHS",
"timeValue": 12,
"projectionValue": -4534.69
}
],
"streamConfidences": null
},
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 3,
"endDate": "2025-03-31",
"max": -148.82,
"mean": -107.12333333333333,
"median": -102.0,
"min": -70.55,
"standardDeviation": 39.385716107915734,
"startDate": "2025-03-01",
"sum": -321.37,
"comparedToCohorts": [
{
"cohortType": "POSTAL_CODE",
"totalDifferenceToCohort": 45.67,
"percentageDifferenceToCohort": 12.44
}
]
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2025-03-01",
"endDate": "2025-03-31",
"cohortValues": [
{
"cohortType": "POSTAL_CODE",
"value": "-367.04"
}
]
}
]
}
],
"attributeName": "UTILITIES_SPENDING",
"streamIds": [],
"transactionIds": [
"100393337811",
"100393337812",
"100393337813"
],
"projectedValues": [
{
"timeUnit": "MONTHS",
"timeValue": 3,
"projectionValue": -895.54
},
{
"timeUnit": "MONTHS",
"timeValue": 6,
"projectionValue": -1791.08
},
{
"timeUnit": "MONTHS",
"timeValue": 9,
"projectionValue": -2686.62
},
{
"timeUnit": "MONTHS",
"timeValue": 12,
"projectionValue": -3582.15
}
],
"streamConfidences": null
},
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 1,
"endDate": "2025-01-31",
"max": -102.0,
"mean": -102.0,
"median": -102.0,
"min": -102.0,
"startDate": "2025-01-01",
"sum": -102.0,
"comparedToCohorts": [
{
"cohortType": "POSTAL_CODE",
"totalDifferenceToCohort": 265.04,
"percentageDifferenceToCohort": 72.21
}
]
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2025-03-01",
"endDate": "2025-03-31",
"cohortValues": [
{
"cohortType": "POSTAL_CODE",
"value": "-367.04"
}
]
}
]
}
],
"attributeName": "ENTERTAINMENT_SPENDING",
"streamIds": [],
"transactionIds": [
"100393337856"
],
"projectedValues": [
{
"timeUnit": "MONTHS",
"timeValue": 3,
"projectionValue": -68.06
},
{
"timeUnit": "MONTHS",
"timeValue": 6,
"projectionValue": -136.12
},
{
"timeUnit": "MONTHS",
"timeValue": 9,
"projectionValue": -204.19
},
{
"timeUnit": "MONTHS",
"timeValue": 12,
"projectionValue": -272.25
}
],
"streamConfidences": null
},
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 1,
"endDate": "2025-01-31",
"max": -102.0,
"mean": -102.0,
"median": -102.0,
"min": -102.0,
"startDate": "2025-01-01",
"sum": -102.0,
"comparedToCohorts": [
{
"cohortType": "POSTAL_CODE",
"totalDifferenceToCohort": 265.04,
"percentageDifferenceToCohort": 72.21
}
]
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2025-03-01",
"endDate": "2025-03-31",
"cohortValues": [
{
"cohortType": "POSTAL_CODE",
"value": "0.0"
}
]
}
]
}
],
"attributeName": "DISCRETIONARY_SPENDING",
"streamIds": [],
"transactionIds": [
"100393337856"
],
"projectedValues": [],
"streamConfidences": null
},
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 9,
"endDate": "2025-03-31",
"max": -148.82,
"mean": -77.93,
"median": -84.98,
"min": -8.63,
"standardDeviation": 37.48252411641201,
"startDate": "2025-03-01",
"sum": -693.32,
"comparedToCohorts": [
{
"cohortType": "POSTAL_CODE",
"totalDifferenceToCohort": 282.59,
"percentageDifferenceToCohort": 60.6
}
]
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2025-03-01",
"endDate": "2025-03-31",
"cohortValues": [
{
"cohortType": "POSTAL_CODE",
"value": "0.0"
}
]
}
]
}
],
"attributeName": "NONDISCRETIONARY_SPENDING",
"streamIds": [],
"transactionIds": [
"100393337806",
"100393337807",
"100393337866",
"100393337868",
"100393337869",
"100393337871",
"100393337811",
"100393337812",
"100393337813"
],
"projectedValues": [],
"streamConfidences": null
}
]
```
**JSON fields description**
| Key (Datatype) | Description | Applicable for Consumer Foresight |
|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|
| 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 a 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 a monthly time interval, the 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 a monthly time interval, the 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 a monthly time interval, the 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 a monthly time interval, the 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 a time interval, the 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. | Yes |
| cohortType (string) | Describes the type of cohort being compared to for this period, for example POSTAL_CODE. | Yes |
| totalDifferenceToCohort (number) | Reflects the difference between the customer's spending for the period minus that of the average spending in this cohort. A positive difference value indicates that a customer has spent less than the cohort while a negative difference value indicates that a customer has spent more than the cohort. | Yes |
| percentageDifferenceToCohort (number) | Reflects the percentage difference between the customer's sum value for the period and the average of the cohort. A positive percentage value indicates that a customer has spent less than the cohort while a negative percentage value indicates that a customer has spent more than the cohort. | Yes |
| timeIntervalType (string) | See Time Interval Types 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 the type and value of a cohort benchmark period. | Yes |
| cohortType (string) | For each cohort benchmark period, the type of cohort we have a representative metric for, for example POSTAL_CODE. | Yes |
| value (number) | For each cohort benchmark period, the average spending of the cohort during this time period. | Yes |
| attributeName (string) | Name of a Consumer Foresight attribute for which we are reporting the numbers. Refer to Consumer Foresight Attributes. | Yes |
| streamIds | List of stream IDs associated with the attribute. This field will be empty as it is not applicable for Consumer Foresight. | 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. | Yes |
| timeUnit (string) | The unit of time being described, for example MONTHS. | Yes |
| timeValue (number) | The number of timeUnit units for which we are projecting, for example 12. (for 12 months) | Yes |
| projectionValue (number) | The predicted sum value of the attribute over the coming timeValue number of timeUnits. | Yes |
| streamConfidences (object) | List of stream confidences, indicating the confidence in which we believe each stream is correctly associated with this attribute. This field will be empty as it is not applicable for Consumer Foresight. | No |
| streamId (string) | The stream ID we are reporting the confidence for. This field will be empty as it is not applicable for Consumer Foresight. | No |
| confidence (number) | A float value between 0 and 100 indicating the confidence over whether a stream is correctly associated to an attribute. This field will be empty as it is not applicable for Consumer Foresight. | No |
#### State Attributes {#state-attributes}
Consumer Foresight does not currently have any state attributes.
#### Streams {#streams}
Consumer Foresight does not currently have any stream attributes.
## Testing {#testing}
Refer to [Test the APIs](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md). Ensure you use a test profile that contains supported account types such as **profile_1726**.
## Legacy Endpoint {#legacy-endpoint}
The legacy endpoint is available at:
API Reference: `POST /decisioning/customers/{customerId}/reports/foresight-analytics/userTypes/{userType}`
You can use any [Get Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) endpoint to retrieve reports from the legacy endpoint.