Sustainability for Platforms

Simplifying Utility Account Linking for Your Platform

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 NameTypeDescription
source_nameStringName of the utility provider (e.g., National Grid)
source_countryStringThe 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)
usernameStringA 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.
accountsArrayA list of accounts associated with the user. Contains account and statement data.

Account Fields:

Field NameTypeDescription
account_numberStringThe account number assigned by the utility provider (e.g., 987654321).
statementsArrayA list of billing statements related to the account.

Statement Fields:

Field NameTypeDescriptionLikely Null
customer_nameStringName of the customer or business (e.g., ACME Corporation).No
customer_numberStringThe unique customer identifier (e.g., CUS-2025-00001).Yes
account_numberStringThe 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_numberStringThe unique identifier for the statement (could be null if not applicable).Yes
billing_addressStringBilling address of the customer, formatted in three lines using \n.No

Billing Period Fields:

Field NameTypeDescription
billing_period_start_dateStringStart date of the billing period (e.g., 2025-01-25).
billing_period_end_dateStringEnd date of the billing period (e.g., 2025-02-25).
billing_period_duration_daysIntegerNumber of days in the billing period (e.g., 31).
billing_dateStringThe date the statement was issued (e.g., 2025-02-25).
next_billing_dateStringThe date of the next billing cycle (e.g., 2025-03-25).
payment_due_dateStringThe due date for payment (e.g., 2025-03-15).
auto_pay_dateStringThe 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 NameTypeDescription
previous_total_due_amountNumberThe amount due from the previous billing cycle (e.g., 12500.00).
balance_forwardNumberThe balance carried forward from previous statements (e.g., 0).
total_due_amountNumberThe total amount due for the current billing period (e.g., 11450.45).
currency_codeStringThe three-letter currency code (ISO 4217) used for the billing amount (e.g., USD).

Payments and Corrections:

Field NameTypeDescriptionLikely Null
paymentsArrayA list of payments applied to the statement.Yes
payment_dateStringDate when the payment was made (e.g., 2025-02-20).Yes
payment_detailsStringDescription of the payment (e.g., Payment received via credit card).Yes
payment_amountStringAmount paid (e.g., 12500.00).Yes
CorrectionsArrayList of any billing corrections (empty array if no corrections).Non-applicable

Service Locations:

Field NameTypeDescriptionEnum (when applicable)
service_locationsArrayList of service locations.
service_numberStringUnique service identifier (e.g., SRV-001).
service_addressStringAddress of the service location, formatted in three lines using \n.
service_typeEnumType of service provided (e.g., Electric, NaturalGas).Electricity Gas Water CellPhoneService HomeInternet CableTelevision LandlineTelephone
service_planStringThe rate plan applied to the service (e.g., EL12 Industrial High-Usage).
new_chargesNumberThe total new charges for the service location (e.g., 13076.0).

Charges (Breakdown):

Field NameTypeDescription
chargesArrayA list of charges for the service location.
charge_nameStringDescription of the specific charge (e.g., Customer charge, Energy delivery).
amountNumberAmount for the specific charge (e.g., 75.0).

Meter Readings:

Field NameTypeDescription
meter_numberStringUnique identifier for the meter (e.g., MTR-123456).
read_start_dateStringStart date for the meter reading (e.g., 2025-01-25).
read_start_valueNumberStart value of the meter reading (e.g., 10250.0).
read_end_dateStringEnd date for the meter reading (e.g., 2025-02-25).
read_end_valueNumberEnd value of the meter reading (e.g., 11500.0).
read_period_duration_daysIntegerNumber of days between meter readings (e.g., 31).
read_deltaNumberDifference between start and end readings (e.g., 1250.0).
multiplierNumberA 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_usageNumberTotal usage calculated for the billing period (e.g., 125000).
total_usage_unitStringUnit 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 NameTypeDescription
chargesArrayA list of charges for the service location.

Potential Usage Units:

ServiceUsage UnitDescription
ElectricityTypically measured in kilowatt-hours (kWh) for residential usage or megawatt-hours (MWh) for large-scale industrial use.
kWhStandard unit for measuring electricity consumption (kilowatt-hour).
MWhUsed for larger-scale electricity consumption (megawatt-hour).
W (watts)Instantaneous power consumption measurement.
GasMeasured in therms, cubic meters (m³), or cubic feet (cf), depending on regional standards and the size of consumption.
thermsCommon unit for measuring natural gas.
Cubic meters for the volume of gas consumption in metric system.
cfVolume of gas consumption in imperial system (cubic feet).
BtuMeasurement of energy content in gas (British thermal units)
gallonsVolume of heating oil consumption.
litersVolume of heating oil in metric system.
WaterMeasured in gallons (U.S.) or liters/m³ (metric system).
gallonsCommon unit for measuring water in the U.S.
litersCommon unit for measuring water in metric system.
m3Large-scale water consumption measurement (cubic meters).
WasteUsually measured by weight, in tons or pounds.
tonsWeight of waste for disposal (common in industrial or municipal services).
lbsWeight of waste, smaller scale (pounds).
TelecomInternet data is measured in gigabytes (GB) or megabytes (MB), while phone services may measure in minutes for voice calls.
GBData usage for internet services (gigabytes).
MBData usage for internet services (megabytes).
minutesDuration 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/