Rewind - Account History

You are here to make it easy for your users to link their utility accounts.

User-Friendly Account linking Experience

You will use Deck Link, a widget that will be embedded in your user flow in order for your users to give Deck permission to link their utility account. Deck Link handles all of the end-user authentication flows, including when we face incorrect credentials or MFA scenarios.

Reliable and Continuous Data Stream

When users link their accounts through Deck Link, you can retrieve up to several years of historical data, providing the ability to generate comprehensive quarterly or annual reports instantly.

Once the account is linked, Deck allows for continuous, periodic data fetching, ensuring you have up-to-date information for real-time analysis and reporting.

In-Depth Insights with Detailed Datasets

To power your use-case, you can access granular consumption details and breakdown of charges. As a rule of thumb, if the data point you need is seen on an invoice from that provider, Deck is able to pull it for you.

Sample Response for the Sustainability endpoint:

{
  "source_name": "National Grid",
  "source_country": "US",
  "username": "[email protected]",
  "accounts": [
    {
      "account_number": "987654321",
      "statements": [
        {
          "customer_name": "ACME Corporation",
          "customer_number": "CUS-2025-00001",
          "account_number": "987654321",
          "statement_number": null,
          "billing_address": "ACME Corporation\n123 Main St, Suite 500\nNew York, NY 10001"
          
          // Billing period details
          "billing_period_start_date": "2025-01-25",
          "billing_period_end_date": "2025-02-25",
          "billing_period_duration_days": 31,
          "billing_date": "2025-02-25",
          "next_billing_date": "2025-03-25",
          "payment_due_date": "2025-03-15",
          "auto_pay_date": "2025-03-01",

          // Financial details
          "previous_total_due_amount": 12500.00,
          "balance_forward": 0,
          "total_due_amount": 11450.45,
          "currency_code": "USD",

          // Payments and corrections
          "payments": [
            {
              "date": "2025-02-20",
              "details": "Payment received via credit card",
              "amount": 12500.00
            }
          ],
          "corrections": [],

          // Service Locations details
          "service_locations": [
            {
              // General service information
              "service_number": "SRV-001",
              "service_address": "456 Elm St, Suite 200\nNew York, NY\n10001",
              "service_type": "Electric",
              "service_plan": "EL12 Industrial High-Usage",
              
              // Charges summary
              "new_charges": 13076.0,

              // Detailed breakdown of charges
              "charges": [
                {
                  "charge_name": "Customer charge",
                  "amount": 75.0
                },
                {
                  "charge_name": "Energy delivery 250000.00 kWh @2.500¢/kWh",
                  "amount": 6250.0
                },
                {
                  "charge_name": "Demand delivery 650.00 kW @ $45.00/kW",
                  "amount": 29250.0
                },
                {
                  "charge_name": "System Benefit Charge",
                  "amount": 1250.0
                },
                {
                  "charge_name": "Billing and payment processing charge",
                  "amount": 1.0
                }
              ],
              
              // Meter readings and usage
              "meters": [
                {
                  "meter_number": "MTR-123456",
                  "read_start_date": "2025-01-25",
                  "read_start_value": 10250.0,
                  "read_end_date": "2025-02-25",
                  "read_end_value": 11500.0,
                  "read_period_duration_days": 31,
                  "read_delta": 1250.0,
                  "multiplier": 100,
                  "total_usage": 125000,
                  "total_usage_unit": "kWh",
                  "charges": []
                }
              ]
            },
            {
              // General service information
              "service_number": "SRV-002",
              "service_address": "456 Elm St, Suite 200\nNew York, NY\n10001",
              "service_type": "NaturalGas",
              "service_plan": "NG4 Commercial Standard",

              // Charges summary
              "new_charges": 904.08,

              // Detailed breakdown of charges
              "charges": [
                {
                  "charge_name": "Supply 500 therms",
                  "amount": 750.0
                },
                {
                  "charge_name": "Basic service charge",
                  "amount": 50.0
                },
                {
                  "charge_name": "System Benefit Charge",
                  "amount": 10.0
                },
                {
                  "charge_name": "Sales tax @8.875%",
                  "amount": 80.45
                }
              ],
              
              // Meter readings and usage
              "meters": [
                {
                  "meter_number": "MTR-654321",
                  "read_start_date": "2025-01-25",
                  "read_start_value": 500,
                  "read_end_date": "2025-02-25",
                  "read_end_value": 550,
                  "read_period_duration_days": 31,
                  "read_delta": 50,
                  "multiplier": 1.05,
                  "total_usage": 52.5,
                  "total_usage_unit": "therms",
                  "charges": []
                }
              ]
            }
          ],
          
          // Additional charges at the statement level
          "charges": []
        }
      ]
    }
  ]
}

Note: if multiple meters, you will receive one object per meter per invoice in the invoices array.

Sustainability Endpoint Data Dictionary

Top-level Fields:

Field Name	Type	Description
source_name	String	Name of the utility provider (e.g., National Grid)
source_country	String	The two-letter country code (ISO 3166-1 alpha-2) representing the country associated with the account or service (e.g., “US” for the United States)
username	String	A unique identifier for the user that is used to authenticate and associate API requests with the correct account. This is typically an email address, username, or another form of user ID registered with the platform or service.
accounts	Array	A list of accounts associated with the user. Contains account and statement data.

Account Fields:

Field Name	Type	Description
account_number	String	The account number assigned by the utility provider (e.g., 987654321).
statements	Array	A list of billing statements related to the account.

Statement Fields:

Field Name	Type	Description	Likely Null
customer_name	String	Name of the customer or business (e.g., ACME Corporation).	No
customer_number	String	The unique customer identifier (e.g., CUS-2025-00001).	Yes
account_number	String	The account number associated with this statement (e.g., 987654321). It mirrors the “account_number” field from the account section, provided for ease of reference at the statement level.	No
statement_number	String	The unique identifier for the statement (could be null if not applicable).	Yes
billing_address	String	Billing address of the customer, formatted in three lines using \n.	No

Billing Period Fields:

Field Name	Type	Description
billing_period_start_date	String	Start date of the billing period (e.g., 2025-01-25).
billing_period_end_date	String	End date of the billing period (e.g., 2025-02-25).
billing_period_duration_days	Integer	Number of days in the billing period (e.g., 31).
billing_date	String	The date the statement was issued (e.g., 2025-02-25).
next_billing_date	String	The date of the next billing cycle (e.g., 2025-03-25).
payment_due_date	String	The due date for payment (e.g., 2025-03-15).
auto_pay_date	String	The scheduled date when the automatic payment will be withdrawn from the customer’s account (e.g., 2025-03-01). This is the date when the payment is processed without requiring manual intervention, assuming the customer has set up automatic payments with the provider.

Financial Details:

Field Name	Type	Description
previous_total_due_amount	Number	The amount due from the previous billing cycle (e.g., 12500.00).
balance_forward	Number	The balance carried forward from previous statements (e.g., 0).
total_due_amount	Number	The total amount due for the current billing period (e.g., 11450.45).
currency_code	String	The three-letter currency code (ISO 4217) used for the billing amount (e.g., USD).

Payments and Corrections:

Field Name	Type	Description	Likely Null
payments	Array	A list of payments applied to the statement.	Yes
payment_date	String	Date when the payment was made (e.g., 2025-02-20).	Yes
payment_details	String	Description of the payment (e.g., Payment received via credit card).	Yes
payment_amount	String	Amount paid (e.g., 12500.00).	Yes
Corrections	Array	List of any billing corrections (empty array if no corrections).	Non-applicable

Service Locations:

Field Name	Type	Description	Enum (when applicable)
service_locations	Array	List of service locations.
service_number	String	Unique service identifier (e.g., SRV-001).
service_address	String	Address of the service location, formatted in three lines using \n.
service_type	Enum	Type of service provided (e.g., Electric, NaturalGas).	`Electricity` `Gas` `Water` `CellPhoneService HomeInternet CableTelevision LandlineTelephone`
service_plan	String	The rate plan applied to the service (e.g., EL12 Industrial High-Usage).
new_charges	Number	The total new charges for the service location (e.g., 13076.0).

Charges (Breakdown):

Field Name	Type	Description
charges	Array	A list of charges for the service location.
charge_name	String	Description of the specific charge (e.g., Customer charge, Energy delivery).
amount	Number	Amount for the specific charge (e.g., 75.0).

Meter Readings:

Field Name	Type	Description
meter_number	String	Unique identifier for the meter (e.g., MTR-123456).
read_start_date	String	Start date for the meter reading (e.g., 2025-01-25).
read_start_value	Number	Start value of the meter reading (e.g., 10250.0).
read_end_date	String	End date for the meter reading (e.g., 2025-02-25).
read_end_value	Number	End value of the meter reading (e.g., 11500.0).
read_period_duration_days	Integer	Number of days between meter readings (e.g., 31).
read_delta	Number	Difference between start and end readings (e.g., 1250.0).
multiplier	Number	A factor applied to the raw meter reading to account for measurement scaling or calibration. It adjusts the meter’s raw consumption data to reflect actual usage in appropriate units (e.g., kilowatt-hours for electricity, therms for gas). Multipliers are often used when a meter measures only a fraction of the total usage, or when scaling is necessary due to the size of the service or equipment.
total_usage	Number	Total usage calculated for the billing period (e.g., 125000).
total_usage_unit	String	Unit of measurement for usage (e.g., kWh for electricity, therms for gas). See table "Potential Usage Units" below for a breakdown by Service.

Additional Charges at Statement Level:

Field Name	Type	Description
charges	Array	A list of charges for the service location.

Potential Usage Units:

Service	Usage Unit	Description
Electricity		Typically measured in kilowatt-hours (kWh) for residential usage or megawatt-hours (MWh) for large-scale industrial use.
	kWh	Standard unit for measuring electricity consumption (kilowatt-hour).
	MWh	Used for larger-scale electricity consumption (megawatt-hour).
	W (watts)	Instantaneous power consumption measurement.
Gas		Measured in therms, cubic meters (m³), or cubic feet (cf), depending on regional standards and the size of consumption.
	therms	Common unit for measuring natural gas.
	m³	Cubic meters for the volume of gas consumption in metric system.
	cf	Volume of gas consumption in imperial system (cubic feet).
	Btu	Measurement of energy content in gas (British thermal units)
	gallons	Volume of heating oil consumption.
	liters	Volume of heating oil in metric system.
Water		Measured in gallons (U.S.) or liters/m³ (metric system).
	gallons	Common unit for measuring water in the U.S.
	liters	Common unit for measuring water in metric system.
	m3	Large-scale water consumption measurement (cubic meters).
Waste		Usually measured by weight, in tons or pounds.
	tons	Weight of waste for disposal (common in industrial or municipal services).
	lbs	Weight of waste, smaller scale (pounds).
Telecom		Internet data is measured in gigabytes (GB) or megabytes (MB), while phone services may measure in minutes for voice calls.
	GB	Data usage for internet services (gigabytes).
	MB	Data usage for internet services (megabytes).
	minutes	Duration of voice calls for telecommunication services.

Coverage should never be an issue with Deck

Although Deck's network of utilities is extensive, it is not infrequent that we find gaps for smaller regional utility providers that is flagged by tech or product folks from our customer base. Typically, if you flag it to us, your users will be able to find that provider in the search bar of the Deck Link within a few days. If we're not talking already on Slack, you can reach out directly here: https://www.linkedin.com/in/fk-lavoie/