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 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/
Updated 24 days ago