Facteus Cube API Guide¶
This guide walks through the available API calls to access the Cube endpoint. Readers should come away with an understanding of the available calls, parameters, and result sets using the Cube API. Access information and sample calls will be added.
Get Reports¶
Description: Returns the accessible reports for a user’s access.
Required Parameters: None
Optional Parameters: None
Result:
Field |
Description |
|---|---|
report_name |
Name of the report |
report_id |
ID of the report |
Get Reports Entities¶
Description: Returns the available entities (merchants, categories, groupings) for the specified report as part of a report configuration.
Required Parameters:
Parameter |
Description |
Type |
|---|---|---|
report_id |
Defines the report to return. |
String |
Optional Parameters: None
Result:
Field |
Description |
Type |
|---|---|---|
report_id |
ID of the report. |
String |
entity_name |
Name of the entity (e.g., merchant, category). |
String |
entity_id |
Unique identifier for the entity. |
String |
is_report_primary_entity |
Indicates whether this is the primary entity for the report. |
Bool |
uses_custom_entity_field |
Indicates whether custom fields are used for the entity. |
Bool |
Get Report Field Options¶
Description: Returns the available values for each field for the specified report.
Required Parameters:
Parameter |
Description |
Type |
|---|---|---|
report_id |
Defines the report to return. |
String |
Optional Parameters: None
Result:
Field |
Description |
Type |
|---|---|---|
field |
Name of the field. |
String |
value |
Available value for the field. |
String |
Get Spend Metrics¶
Description: Returns spend and related KPIs for the selected report.
Required Parameters:
Parameter |
Description |
Type |
|---|---|---|
report_id |
Defines the report to return. |
String |
Optional Parameters:
Parameter |
Description |
Type |
|---|---|---|
brands |
Filters the result set to the specified merchants. |
StringList |
report_time_unit |
Filters the result set to the specified calendar aggregation. Valid values: Year, Quarter, Month, Week. |
String |
report_time |
Filters the result set to the specified date. Format: YYYY-MM-DD. |
String |
report_time_before |
Filters the result set to Report Times before the specified date. Format: YYYY-MM-DD. |
String |
report_time_after |
Filters the result set to Report Times after the specified date. Format: YYYY-MM-DD. |
String |
shopper_region |
Filters the result set to shoppers with home locations in the specified region. Valid values: Northeast, Midwest, South, West, Other. |
String |
shopper_msa |
Filters the result set to shoppers with home locations in the specified MSA. See MSA list below, or use Get Report Options. |
String |
shopper_state |
Filters the result set to shoppers with home locations in the specified state. Two-character state code, see State list below, or use Get Report Options. |
String |
shopper_city |
Filters the result set to shoppers with home locations in the specified city. See City list below, or use Get Report Options. |
String |
shopper_postal_code |
Filters the result set to shoppers with home locations in the specified region. Format: #####, valid 5-digit zip code. |
String |
shopper_country |
Filters the result set to shoppers with home locations in the specified country. Valid values: USA. |
String |
shopper_generation |
Filters the result set to shoppers born in the specified generation. Valid values: Gen Z, Millennial, Gen X, Baby Boomer, Silent, N/A. |
String |
daypart |
Filters the result set to transactions from the specified daypart. Valid values: 12 AM - 5 AM, 5 AM - 9 AM, 9 AM - 11 AM, 11 AM - 2 PM, 2 PM - 4 PM, 4 PM - 9 PM, 9 PM - 12 AM, N/A. |
String |
channel |
Filters the result set to transactions from the specified payment channel. Valid values: Card Present, Card Not Present, N/A. |
String |
merchant_distance_from_home |
Filters the result set to transactions that occurred within the specified distance from the merchant to the shopper home zip code. Valid values: 0, 1, 5, 10, 25, 100, 250, 251. |
String |
shopper_income_bracket |
Filters the result set to shoppers within the specified income bracket. Valid values: UNDER $50K, $50-$75K, $75-$100K, $100-$125K, $125-$150K, Over $150K, N/A. |
String |
shopper_card_type |
Filters the result set to shoppers using the specified card type. Valid values: Credit, Debit, Payroll, Government, General Purpose, Benefit - Health. |
String |
grouping_columns |
Adds additional columns to the result set that group the results by the specified column. Valid values: non-time report filters above, e.g., merchant_distance_from_home. |
StringList |
Result:
Field |
Description |
Type |
|---|---|---|
spend |
Total spend amount. |
Float |
transactions |
Total number of transactions. |
Int |
shoppers |
Total number of shoppers. |
Int |
spend_per_transaction |
Average spend per transaction. |
Float |
spend_per_shopper |
Average spend per shopper. |
Float |
transactions_per_shopper |
Average transactions per shopper. |
Float |
primary_entity |
Primary entity in the report. |
String |
report_time |
Time period of the report. |
String |
grouping_columns |
Additional grouping columns, if selected. |
String |
Get Cross Shopping¶
Description: Returns the cross-shopping matrix for the specified report and time period, optionally filtering by the brands specified and geography specified.
Required Parameters:
Parameter |
Description |
Type |
|---|---|---|
report_id |
Defines the report to return. |
String |
Optional Parameters:
Parameter |
Description |
Type |
|---|---|---|
metric |
Selects which KPI to return. Valid values: CustomerShare, SpendPerCustomer, Customers, SpendPerTransaction. |
String |
return_pivoted |
Returns data either in normal, tabular form or pivoted. Valid values: Y, N. |
String |
report_time_unit |
Filters the result set to the specified calendar aggregation. Valid values: Year, Quarter, Month. |
String |
report_time |
Filters the result set to the specified date. Format: YYYY-MM-DD. |
String |
report_time_before |
Filters the result set to Report Times before the specified date. Format: YYYY-MM-DD. |
String |
report_time_after |
Filters the result set to Report Times after the specified date. Format: YYYY-MM-DD. |
String |
shopper_region |
Filters the result set to shoppers with home locations in the specified region. Valid values: Northeast, Midwest, South, West, Other. |
String |
Result:
Field |
Description |
Type |
|---|---|---|
value |
Value of the metric. |
Float |
report_time_unit |
Time unit of the report. |
String |
report_time |
Time period of the report. |
String |
row_label |
Label for the row. |
String |
column_label |
Label for the column. |
String |
grouping_columns |
Additional grouping columns, if selected. |
String |
Get Customer Journey¶
Description: Returns the customer journey data for the specified report, detailing the sequence of interactions customers have with merchants or categories over time.
Required Parameters:
Parameter |
Description |
Type |
|---|---|---|
report_id |
Defines the report to return. |
String |
Optional Parameters:
Parameter |
Description |
Type |
|---|---|---|
report_time_unit |
Filters the result set to the specified calendar aggregation. Valid values: Year, Quarter, Month, Week. |
String |
report_time |
Filters the result set to the specified date. Format: YYYY-MM-DD. |
String |
report_time_before |
Filters the result set to Report Times before the specified date. Format: YYYY-MM-DD. |
String |
report_time_after |
Filters the result set to Report Times after the specified date. Format: YYYY-MM-DD. |
String |
shopper_region |
Filters the result set to shoppers with home locations in the specified region. Valid values: Northeast, Midwest, South, West, Other. |
String |
shopper_msa |
Filters the result set to shoppers with home locations in the specified MSA. See MSA list below, or use Get Report Options. |
String |
shopper_state |
Filters the result set to shoppers with home locations in the specified state. Two-character state code, see State list below, or use Get Report Options. |
String |
shopper_city |
Filters the result set to shoppers with home locations in the specified city. See City list below, or use Get Report Options. |
String |
shopper_postal_code |
Filters the result set to shoppers with home locations in the specified region. Format: #####, valid 5-digit zip code. |
String |
shopper_country |
Filters the result set to shoppers with home locations in the specified country. Valid values: USA. |
String |
shopper_generation |
Filters the result set to shoppers born in the specified generation. Valid values: Gen Z, Millennial, Gen X, Baby Boomer, Silent, N/A. |
String |
grouping_columns |
Adds additional columns to the result set that group the results by the specified column. Valid values: non-time report filters above, e.g., shopper_region. |
StringList |
Result:
Field |
Description |
Type |
|---|---|---|
journey_step |
The step in the customer journey (e.g., first interaction, second interaction). |
String |
entity_name |
Name of the entity (e.g., merchant, category). |
String |
entity_id |
Unique identifier for the entity. |
String |
spend |
Total spend amount at this step. |
Float |
transactions |
Total number of transactions at this step. |
Int |
shoppers |
Total number of shoppers at this step. |
Int |
report_time |
Time period of the report. |
String |
grouping_columns |
Additional grouping columns, if selected. |
String |
Get Affinities¶
Description: Returns affinity metrics for the specified report, detailing the strength of relationships between entities (e.g., merchants, categories) based on customer behavior.
Required Parameters:
Parameter |
Description |
Type |
|---|---|---|
report_id |
Defines the report to return. |
String |
Optional Parameters:
Parameter |
Description |
Type |
|---|---|---|
brands |
Filters the result set to the specified merchants. |
StringList |
report_time_unit |
Filters the result set to the specified calendar aggregation. Valid values: Year, Quarter, Month, Week. |
String |
report_time |
Filters the result set to the specified date. Format: YYYY-MM-DD. |
String |
report_time_before |
Filters the result set to Report Times before the specified date. Format: YYYY-MM-DD. |
String |
report_time_after |
Filters the result set to Report Times after the specified date. Format: YYYY-MM-DD. |
String |
shopper_region |
Filters the result set to shoppers with home locations in the specified region. Valid values: Northeast, Midwest, South, West, Other. |
String |
shopper_msa |
Filters the result set to shoppers with home locations in the specified MSA. See MSA list below, or use Get Report Options. |
String |
shopper_state |
Filters the result set to shoppers with home locations in the specified state. Two-character state code, see State list below, or use Get Report Options. |
String |
shopper_city |
Filters the result set to shoppers with home locations in the specified city. See City list below, or use Get Report Options. |
String |
shopper_postal_code |
Filters the result set to shoppers with home locations in the specified region. Format: #####, valid 5-digit zip code. |
String |
shopper_country |
Filters the result set to shoppers with home locations in the specified country. Valid values: USA. |
String |
shopper_generation |
Filters the result set to shoppers born in the specified generation. Valid values: Gen Z, Millennial, Gen X, Baby Boomer, Silent, N/A. |
String |
grouping_columns |
Adds additional columns to the result set that group the results by the specified column. Valid values: non-time report filters above, e.g., shopper_region. |
StringList |
Result:
Field |
Description |
Type |
|---|---|---|
affinity_score |
The strength of the relationship between entities, represented as a score. |
Float |
entity_name |
Name of the entity (e.g., merchant, category). |
String |
entity_id |
Unique identifier for the entity. |
String |
related_entity_name |
Name of the related entity. |
String |
related_entity_id |
Unique identifier for the related entity. |
String |
spend |
Total spend amount for the entity. |
Float |
transactions |
Total number of transactions for the entity. |
Int |
shoppers |
Total number of shoppers for the entity. |
Int |
report_time |
Time period of the report. |
String |
grouping_columns |
Additional grouping columns, if selected. |
String |