Data Schema Reference

FLEX Insights

Version 1.1

Overview

This document provides the structure and attributes of the Recurve intake data schema to enable the FLEX Insights feature. The schema outlines a consistent structure for representing interval usage and service point metadata.

This schema ensures that all inputs required for the insights feature is clearly defined. The schema versioned in this document applies specifically to the insights use case and may evolve as new capabilities, technologies, and regulatory requirements are supported.

Entities

This section describes the core data entities that make up the Insights intake schema and how they relate to one another. Each entity represents a distinct concept required to calculate time of use allocations, end use detection, and load disaggregation, based on individual customer usage characteristics. These entities define the minimum set of inputs needed to operationalize the insights features. Detailed schema definitions and example files are provided for each entity to support consistent implementation and validation.

Timestamp Format

All timestamps must use the ISO 8601 format and include the date, time, and timezone.
Supported Formats: YYYY-MM-DDTHH:MM:SS±HH:MM or YYYY-MM-DDTHH:MM:SSZ (UTC)
Examples: 2026-06-26T13:15:30-07:00, 2026-06-26T20:15:30Z

interval_data

Hourly or 15-minute AMI electric data and/or daily interval gas data, for all service points at the population level. This data provides the latest year’s worth of observed load for all meters in the targeted population. Then targeting calculations are run to disaggregate individual customer load types and usage characteristics, which enable the application of dynamic targeting parameters based on specific programmatic or load planning goals.

File Requirements

interval_data file names must begin with interval_data and end with the appropriate file type suffix (.csv)
If any delimiters are present in any field values, all values must be wrapped in double quotes
Files must have a header row that contains all required fields
"Null" values should only be passed as empty values

Examples of acceptable file names

interval_data_20240204.csv
interval_data_westernRegion.csv

Field	Type	Required	Description	Constraints
service_point_id	string	Yes	A specific location at a premise where utilities supply service, or where usage occurs. Multiple service_point_ids can belong to a single premise_id.	“9471297459” “df-443-jk”
start_time	string	Yes	Start datetime in ISO 8601 format.	ISO 8601 date format
end_time	string	Yes	End datetime in ISO 8601 format.	ISO 8601 date format
value	number	Yes	The interval data value.	format: float
direction	string	No	Direction of energy flow: 'delivered' or 'received'. Assumed to be received if not specified.	enum: "delivered", "received"

service_points

Customer metadata for all service points at the population level. This data is used in conjunction with interval usage data, to calculate eligibility based on various customizable data sufficiency and disqualification thresholds.

File Requirements

Service point file names must begin with service_point_ and end with the appropriate file type suffix (.csv)
If any delimiters are present in any field values, all values must be wrapped in double quotes
Files must have a header row that contains all required fields, and any applicable non-required fields
"Null" values should only be passed as empty values

Examples of acceptable file names

service_point_data__20240204.csv
service_point_data_westernRegion.csv

Field	Type	Required	Description	Constraints
service_point_id	string	Yes	A specific location at a premise where utilities supply service, or where usage occurs. Multiple service_point_ids can belong to a single premise_id.
service_point_type	string	Yes	The type of the service point, either Gas or Electric.	enum: “electricity”, “gas”
substation	string	No	Substation identifier.
feeder_line	string	No	Feeder line identifier.
timezone	string	No	IANA timezone string (e.g., America/Los_Angeles).
premise_id	string	No	A unique identifier for the premise, if available.
street_1	string	Yes
street_2	string	No
city_town	string	Yes
state_province_region	string	Yes
zip_code_postal_code	string	Yes
county	string	No
country	string	No
naics_code	string	No*	The 6-digit North American Industry Classification System (NAICS) *Required for Commercial programs for comparison group mapping.
sector	string	No	The sector classification of the premise.	enum: "residential", "commercial", "Industrial", "agriculture", "other"
interval	object	No	The interval at which this meter device records data, if available.	enum: "15min", “30min”, "hourly", "daily"
can_export	boolean	No	This service point can export to the grid. This is relevant if solar is installed.
export_start_date	string	No	When did this service point become capable of exporting energy?	ISO 8601 date format
rate_code	string	No	The tariff rate code under which this service point operates.
equity_flag	string	No	An indicator for customer participation in income-qualified, medical, geographic, or debt-relief assistance programs. Helps identify vulnerable, protected, or subsidized ratepayer segments.	enum: “CARE”, “FERA”, “LIFE_SUPPORT”, “MEDICAL_BASELINE”, “DISADVANTAGED_COMMUNITY”, “TRIBAL”, “MOBILE_HOME”
account_id	string	No	A unique identifier for the account.
agreement_id	string	No	A unique identifier for the agreement between the service point and the customer. Along with the corresponding date, it identifies the latest customer at the service point. Often referred to as service agreement ID, customer agreement ID, or account agreement ID.
start_date	string	No	Start date of the service point's contract agreement.	ISO 8601 date format
end_date	string	null	No	End date of the service point's contract agreement.

Change Log

Version	Date	Change
1.1	2026-07-09	Initial version

FLEX Insights

Version 1.1​