Home / Specifications / cds-wg3-01 - Customer Data

Customer Data

Looking for a more human-readable summary of this specification? Check out our overview.

Below is a rendering of the original specification source: https://github.com/daniel-roesler/CDS-Customer-Data/blob/main/specifications/cds-wg3-01.md

CDS-WG3-01 - Customer Data

Abstract

This specification defines how utilities and other central entities (“Servers”) may allow vendors, customers, and other external organizations (“Clients”) to securely access account holder data (“Customer Data”), including in situations where Customer consent where needed or data is aggregated. This specification extends [CDS-WG1-02] (“Client Registration”) to add new authorization Scopes and defines new Application Programming Interfaces (APIs) for Customer Data.

Status

WARNING: This specification is a DRAFT and has not achieved consensus by the working group.

Copyright

Copyright Joint Development Foundation Projects, LLC, LF Energy Standards and Specifications Series and its contributors (“LFESS”). All rights reserved. For more information, visit https://lfess.energy/.

Table of Contents

1. Introduction

This specification was developed as part of the global effort to facilitate grid modernization and the energy transition. Specifically, in order to scalably deploy and economically operate and analyze new energy technologies, external organizations and Customers need an automated means of requesting access to Customer Data from utilities and other central entities.

There are thousands of utilities serving Customers across the world, and each have their own way of providing access to and formatting Customer Data. This specification defines a way for these utilities and other central entities (“Servers”) to provide a standardized, structured process for external users and organizations (“Clients”) to access Customer Data, requesting consent from Customers if needed. By offering a standardized a Customer Data access protocol, utilities and other central entities can offer secure, automated, managed means of access to Customer Data.

2. Terminology

“Server” - The entity hosting the specified endpoints. A Server can be an energy utility or another type of entity that want to provide access to privileged functionality or data. These entities can include, but are not limited to, distribution utilities, grid operators, electric retailers, community choice aggregators, government agencies, data warehouses, and private infrastructure providers.

“Client” - The entity requesting Server’s metadata endpoints. A Client can be any organization or user seeking to access Customer data with a Server for a specific scope of access. These entities can include, but are not limited to, energy efficiency contractors, utility vendors, distributed energy resource companies, building energy management platforms, and even Customers themselves (to gain automated access their own data).

“Customer” - The entity who’s data is being requested from a Server by a Client (“Customer Data”). For grants that require customer authorization, the Customer is the user who authorizes the access. Customers are typically the account holder, also commonly called the “customer of record”, such as homeowners, renters, businesses, and industrial companies. Customers may also be a representative of the customer of record, such as an energy management company, provided that the reprentative has been duly authorized give consent on the customer of record’s behalf according to local regulatory requirements.

“Array” - A list of objects or values as defined by Arrays in [RFC 8259 Section 5].

“date” - A string representing date in the format of full-date as defined by [RFC 3339 Section 5.6] (e.g. “2024-01-01”).

“datetime” - A string representing date and time in the format of date-time as defined by [RFC 3339 Section 5.6] (e.g. “2024-01-01T00:00:00Z”).

“decimal” - A decimal value as defined by number in [RFC 8259 Section 6].

“GET” - A request method defined in [RFC 9110 Section 9].

“HTTPS” - A secure web request protocol defined in [RFC 9110 Section 4.2.2].

“JSON” - A data format defined in [RFC 8259].

“Map” - A JSON object as defined by Objects in [RFC 8259 Section 4].

“MIME type” - A string representing a document media type as defined in [RFC 6838] (e.g. “image/png”).

“null” - The null value defined in [RFC 8259 Section 3].

“Status Code” - A response status code defined in [RFC 9110 Section 15].

“string” - A series of unicode characters as defined in [RFC 8259 Section 7].

“URL” - A string representing resource as defined in [RFC 3986 Section 1.1.3] (e.g. “https://example.com/page1”).

Key Words: “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” are defined in accordance with [BCP 14].

3. Scenarios

Customer Data access is necessary for many different use cases, but not all use cases require the same type of access or same fields of Customer Data. For example, an energy efficiency auditor working with a Customer may need historical usage intervals, but no bill data. In contrast, another example is for a building management company to need ongoing access to a Customer’s bill statements for accounting and reporting.

This section defines “Scenarios” as sets of Scopes and configuration requirements for Scope Descriptions that are intended to meet the Scenario’s use cases. Because Scenarios are defined sets of Scopes and configuration requirements, they don’t actually appear in any API responses by the Server. Rather, Scenarios are intended to aide regulators, governing authorities, and Extensions in choosing which Scopes, data fields, and functionality they require Servers to implement.

Regulators, governing authorities, and extensions MAY choose to require implementation of any combination of Scenarios defined in this specification or choose to define new Scenarios. When defining new Scenarios, it is RECOMMENDED that those Scenarios are defined either as a list of modifications to one or more Scenarios from this specification or, if a completely new Scenario, using the same format as the Scenarios defined in this specification.

New Scenarios MAY include requirements to extend various object formats or numerated values to include additional fields. For example, a regulator could define a new Scenario that extends the “Meter Data” Scenario by requiring an additional CAISO_pricing_node field be included in the Service Contract object. It is RECOMMENDED that when requiring new fields for new Scenarios, that defining the new fields follows the Extensions section, including adding a relevant prefix to the new field names (e.g. CAISO_*).

New Scenarios MAY also define new Scopes that specify a specialized levels of access for Clients of the Scenario’s use cases. When defining new Scopes, it is RECOMMENDED that those Scopes are defined either as a list of modifications to one or more Scopes from this specification or, if a completely new Scope, using the same format as the otherScopes defined in this specification.

In addition to implementing requirements for their jurisdiction, Servers MAY implement any Scope or configuration that helps provide Customer Data access for relevant internal or external use cases. For example, a utility could enable Scopes that streamline how they transfer program participant meter data to their contracted program administrator vendor for internal program analysis and reporting.

Clients MUST NOT rely on stated Scenario compliance from regulators or Servers. Instead, Clients MUST parse the Server Metadata to evaluate if a Server’s offered Scopes and functionality is adequate for their use case.

3.1. Usage Self-Access

This section defines the Scenario “Usage Self-Access” in which a utility Customer wants to access their own accounts’ meter and usage data. For example, a commercial customer would like to download their historical meter usage feed for their owned properties, so that their energy management team can evaluate their buildings’ energy profiles. Another example is for a data center owner to want to integrate an automatic nightly update of their previous day’s meter usage, so that they can check their operations for discrepancies between their own energy monitoring systems.

To implement the “Usage Self-Access” Scenario, Servers MUST implement the following list of requirements.

  • Servers MUST include at least one of each Accounts Query, Service Contracts Query, Service Points Query, Meter Devices Query, and Usage Query Scope Descriptions in the Server Metadata cds_scope_descriptions object, as well as include those Scope Description id values in the Server Metadata scopes_supported list.
  • Servers MUST include any required steps for verifying the identity of a Client as the Customer in the Scope Description registration_requirements list. For example, if a Server requires Customers to associate their online web account with Clients they register, the Server would include a Registration Field [CDS-WG1-02 Section 3.5] with a type value of sso_verification.
  • Once Servers have verified the identity of the Client as the Customer, Servers MUST configure the Customer’s Accounts and Service Contracts to be accessible to the Client using the Accounts Query and Service Contracts Query scopes.
  • Servers MUST configure any Meter Devices, Service Points, and Usage Segments associated with the Customer’s Accounts and Service Contracts to be accessible to the Client using the Service Points Query, Meter Devices Query, and Usage Query scopes.
  • Servers MUST keep the list of Accounts, Service Contracts, Service Points, Meter Devices, and Usage Segments that are associated with the Client updated to reflect any changes to the Customer. For example, if a Customer builds a new warehouse on their property and installs a new electric service for the warehouse, the Client should see any new Accounts, Service Contracts, Service Points, Meter Devices, and Usage Segments for the new warehouse included in API objects returned when data is next synced from the Server.
  • The Usage Query Scope Description’s segment_start authorization details field MUST allow the Client to access for each connected Service Contract’s usage at least 1 year of historical usage data (i.e. minimum value set to at least P1Y).
  • The Usage Query Scope Description’s segment_end authorization details field MUST have the maximum field’s value set to infinite, which means Clients MAY authorize access to.
  • TODO: what include_* auth details

3.2. Billing Self-Access

This section defines the Scenario “Billing Self-Access” in which a utility Customer wants to access their own accounts’ utility bills. For example, an enterprise customer would like automate importing their utility bills into their accounting software.

To implement the “Billing Self-Access” Scenario, Servers MUST implement the following list of requirements.

  • Servers MUST include at least one of each Accounts Query, Service Contracts Query, Bill Statements Query, and Bill Sections Query Scope Descriptions in the Server Metadata cds_scope_descriptions object, as well as include those Scope Description id values in the Server Metadata scopes_supported list.
  • Servers MUST include any required steps for verifying the identity of a Client as the Customer in the Scope Description registration_requirements list. For example, if a Server requires Customers to associate their online web account with Clients they register, the Server would include a Registration Field [CDS-WG1-02 Section 3.5] with a type value of sso_verification.
  • Once Servers have verified the identity of the Client as the Customer, Servers MUST configure the Customer’s Accounts and Service Contracts to be accessible to the Client using the Accounts Query and Service Contracts Query scopes.
  • Servers MUST also configure any Bill Statements and Bill Sections associated with the Customer’s Accounts and Service Contracts to be accessible to the Client using the Bill Statements Query and Bill Sections Query scopes.
  • Servers MUST keep the list of Accounts, Service Contracts, Bill Statements, and Bill Sections that are associated with the Client updated to reflect any changes to the Customer. For example, if a Customer buys a property and transfers the utility services for that property to a new account under their profile, the Client should see any new Accounts, Service Contracts, Bill Statements, and Bill Sections for the new account in API objects returned when data is next synced from the Server.
  • Bill Statement object file_uri and file_mimetype fields are REQUIRED to be included, so that Clients MAY download copies of their utility bill statements.
  • The Bill Statements Query Scope Description’s statement_date_start authorization details field MUST allow the Client to access for each connected Account at least 1 year of historical bill statements (i.e. minimum value set to at least P1Y).
  • The Bill Statements Query Scope Description’s statement_date_end authorization details field MUST allow the Client to access for each connected Account for any future duration of time (i.e. maximum value set to at least in).
  • The Bill Sections Query Scope Description’s start_date authorization details field MUST allow the Client to access for each connected Service Contract at least 1 year of historical bill sections (i.e. minimum value set to at least P1Y).
  • TODO: what include_* auth details

3.3. Usage and Billing Self-Access

This section defines the Scenario “Usage and Billing Self-Access” in which a utility Customer wants to access their own accounts’ usage and bills. For example, an enterprise customer would like automate a energy billing.

To implement the “Usage and Billing Self-Access” Scenario, Servers MUST implement the following list of requirements.

3.4. Meter Data

This section defines the Scenario “Meter Data” in which a Client requests access to a Customer’s historical and/or ongoing usage data. For example, an energy efficiency auditor is working with building owner, and needs to download their previous year’s usage.

To implement the “Meter Data” Scenario, Servers MUST implement the following list of requirements.

  • Servers MUST include at least one of each Accounts Query, Service Contracts Query, Service Points Query, Meter Devices Query, and Usage Query Scope Descriptions in the Server Metadata cds_scope_descriptions object, as well as include those Scope Description id values in the Server Metadata scopes_supported list.
  • The Usage Query Scope Description’s segment_start authorization details field MUST allow the Client to access for each connected Service Contract’s usage at least 1 year of historical usage data (i.e. minimum value set to at least P1Y).

3.5. Rate Plan

TODO

3.6. Program Participation

TODO

3.7. Program Analysis

TODO

3.8. Bill Amount Due

TODO

3.9. Bill Statements

TODO

3.10. Service Charges

TODO

3.11. Whole-Building Data

TODO

3.12. Aggregated Data

TODO

3.13. EAC Data

TODO

3.14. Internal Access

TODO

4. CDS-WG1-02 Extension

As the framework for providing Client registration, onboarding, communication, management, and grant authorizations, Servers MUST implement CDS’s Client Registration specification [CDS-WG1-02]. This specification in subsequent sections extends the CDS’s Client Registration framework by defining additional fields, values, and APIs that are relevant to Customer Data access, so that Servers implementing this specification can satisfy Customer Data use cases.

TODO

5. Server Metadata

This specification extends CDS’s Authorization Server Metadata object [CDS-WG1-02 Section 3.2] to include the following named values:

6. Scopes Supported

This specification extends CDS’s Client Registration Scopes Supported [CDS-WG1-02 Section 3.3] to define the following additional Scope Descriptions [CDS-WG1-02 Section 3.4] that a Server MAY add to the scopes_supported field in the Authorization Server Metadata object [CDS-WG1-02 Section 3.2].

TODO

6.1. Rate Plan

TODO

6.2. Program Participation

TODO

6.3. Account List

TODO

6.4. Service List

TODO

6.5. Meter List

TODO

6.6. Bill Statements

TODO

6.7. Service Bills

TODO

6.8. Meter Usage

TODO

6.9. Aggregation Inclusion

TODO

6.10. Accounts Query

TODO

6.11. Service Contracts Query

TODO

6.12. Service Points Query

TODO

6.13. Meter Devices Query

TODO

6.14. Bill Statements Query

TODO

6.15. Bill Sections Query

TODO

6.16. Aggregations Query

TODO

6.17. Usage Query

TODO

7. Authorization Details Fields

This section defines Authorization Details Fields that are available to be included in Scope definitions. When supported, these fields can be used in authorization_details parameters as part of OAuth’s Rich Authorization Requests [RFC 9396] to define tailored authorization experiences and scopes of access that meet specific use case needs.

When a Server supports an Authorization Details Field defined by this section, the Server MUST include an Authorization Details Field Object [CDS-WG1-02 Section 3.8] for the field in the authorization_details_fields_supported array in the Server’s relevant Scope Description objects [CDS-WG1-02 Section 3.4]. This allows Clients to automate discovery of which Authorization Details Fields are supported when formatting authorization and token request parameters.

Extensions of this specification MAY define additional Authorization Details Fields that define additional behavior for Scope defined in this specification. When defining additional Authorization Details Fields, it is RECOMMENDED to define them in the same format as those defined in this section.

7.1. Allow Scope Modifications

For some use cases, a Client may have a specific set of data fields that they are required to have to complete their process. For example, an energy audit contractor could be required to obtain the last 12 months of meter usage data from a Customer in order to complete their energy audit report.

In these relevant use cases, Clients benefit from being able to configure an authorization request that cannot be modified by a Customer during the authorization process, so that the Customer does not inadvertently remove required data fields or ranges. This authorization data field is intended to allow Clients a way to configure a Server’s authorization form as editable or non-editable.

To support this authorization details field, the Authorization Details Field Object MUST meet the following requirements:

  • The id value MUST be "allow_scope_modifications".
  • The format value MUST be "boolean".

Servers MUST NOT include an object for this authorization field in a Scope Description’s authorization_details_fields_supported array when the Scope Description’s response_types_supported list is empty (i.e. no authorization request method is available).

When this authorization field is included in a Rich Authorization Request authorization_details parameter, Servers MUST implement the following requirements:

  • When the field value is true, Servers MAY render authorization form presented to the user as editable, meaning that the user MAY modify the requested scope within the authorization form and authorize that modified scope.
  • When this field value is false, Servers MUST render the authorization from presented to the user as non-editable, meaning that the user MUST be able to only authorize or decline the authorization request as a whole and cannot modify the requested scope.

7.2. Error If No Preselections

For some use cases, when requesting authorization from a Customer, a Client may want to preselect certain fields on the authorization form. These preselections are configured by other authorization details fields (e.g. service_types). However, sometimes a Customer does not have any Accounts, Meter Devices, or other relevant objects that meet the preselection criteria. For example, an energy audit contractor Client may request access to all of a Customer’s electric Service Contracts using the service_types authorization details field (i.e. "service_types": ["electric"]). If the Customer does not have any electric meters (e.g. they are a gas-only customer), the authorization form will not be able to have any Service Contracts preselected. In other situations, a Customer may have multiple accounts they control, such as a commercial Customer with multiple locations, and may need to reauthenticate as a different user if they are accidentally logged in as the wrong user for an authorization request with a specific list of preselected account numbers (e.g. "account_numbers": ["1234-5"]).

In these relevant use cases, Clients benefit from being able to configure the authorization request to automatically render a Preselection Error for an authenticated Customer if they do not have any objects that can be preselected. That way, Customers are given a chance to re-authenticate as a different user or decline the authorization and be redirected back to the Client with a specific error. This allows Clients to present relevant messages to Customers that do not have required objects for the Client’s use case (e.g. “You don’t appear to have any electric meters, so we won’t be able to run an energy audit for your account.”).

To support this authorization details field, the Authorization Details Field Object MUST meet the following requirements:

  • The id value MUST be "error_if_no_preselections".
  • The format value MUST be "boolean".

Servers MUST NOT include an object for this authorization field in a Scope Description’s authorization_details_fields_supported array when the Scope Description’s response_types_supported list is empty (i.e. no authorization request method is available).

When this authorization field is included in a Rich Authorization Request authorization_details parameter, Servers MUST implement the following requirements:

  • When this field value is true, after the user is authenticated and prior to rendering the authorization form to the user, the Server MUST determine if the user will need to select any objects relevant to preselection fields included in the authorization details of the request (e.g. "account_numbers": ["1234-5"] didn’t match any of the user’s Account account_number values, so no Accounts will be preselected and the user will be asked to select the Accounts they want to apply to this authorization). If the user will need to select any objects relevant to preselection fields included in the authorization details of the request, the Server MUST render and present a Preselection Error to the user, which allows the user to either reauthenticate or cancel the authorization request. If the user selects to cancel the authorization request, the Server MUST redirect the user back to the Client’s redirect_uri with an error parameter value of no_preselections.
  • If the authorization request did not include any preselection fields, defined by Sections 7.3 through 7.9, or this field value is false, the Server MUST ignore this field and treat the authorization request as if this field was not included.

7.3. Preselect Account Numbers

For some use cases, a Client may need to request access to datasets for a specific list of Customer accounts. For example, an energy services company may be working with a property management Customer to analyze the energy use for a specific subset of utility accounts that the Customer has specified. In these relevant use cases, Clients benefit from being able to configure an authorization request that preselects a set of Accounts with the provided account_number values.

To support this authorization details field, the Authorization Details Field Object MUST meet the following requirements:

  • The id value MUST be "account_numbers".
  • The format value MUST be "string_list_or_null".
  • If this object is included in a Scope Description where the response_types_supported field is not empty array (e.g. Customer authorization is supported):
    • The is_required value MUST be false.
    • The default value MUST be one of null, ["_ALL"], or ["_ALL", "_FUTURE"].

When this authorization field is included in a Rich Authorization Request authorization_details parameter, Servers MUST implement the following requirements:

  • If the value is null, the Server MUST render any Account Selection, Service Contract Selection, or Meter Device Selection sections of the authorization form for the authorization details field’s scope with no preselections.
  • If the value is an array of strings with the string "_ALL" included, the Server MUST render any Account Selection, Service Contract Selection, or Meter Device Selection sections of the authorization form for the authorization details field’s scope with all Accounts preselected.
  • If the value is an array of strings with the string "_FUTURE" included, the Server MUST render any Account Selection, Service Contract Selection, or Meter Device Selection sections of the authorization form for the authorization details field’s scope with the include-future option preselected.
  • If the value is an array of strings that does NOT include "_ALL", the Server MUST render any Account Selection, Service Contract Selection, or Meter Device Selection sections of the authorization form for the authorization details field’s scope with Accounts preselected that match their account_number value to one of the strings included in the provided array.
  • If Accounts are also preselected by other authorization details fields for the same scope (e.g. the account_programs field), the Accounts preselected MUST be the intersection of Accounts preselected by the authorization details fields.

7.4. Preselect Contract Numbers

For some use cases, a Client may need to request access to datasets for a specific list of Customer service contracts. For example, an energy auditor may be working with a commercial Customer to produce a report on the energy use for a specific set of electric services on a Customer’s property. In these relevant use cases, Clients benefit from being able to configure an authorization request that preselects a set of Service Contract with the provided contract_number values.

To support this authorization details field, the Authorization Details Field Object MUST meet the following requirements:

  • The id value MUST be "contract_numbers".
  • The format value MUST be "string_list_or_null".
  • If this object is included in a Scope Description where the response_types_supported field is not empty array (e.g. Customer authorization is supported):
    • The is_required value MUST be false.
    • The default value MUST be one of null, ["_ALL"], or ["_ALL", "_FUTURE"].

When this authorization field is included in a Rich Authorization Request authorization_details parameter, Servers MUST implement the following requirements:

  • If the value is null, the Server MUST render any Service Contract Selection or Meter Device Selection sections of the authorization form for the authorization details field’s scope with no preselections.
  • If the value is an array of strings with the string "_ALL" included, the Server MUST render any Service Contract Selection or Meter Device Selection sections of the authorization form for the authorization details field’s scope with all Service Contracts preselected.
  • If the value is an array of strings with the string "_FUTURE" included, the Server MUST render any Service Contract Selection or Meter Device Selection sections of the authorization form for the authorization details field’s scope with the include-future option preselected.
  • If the value is an array of strings that does NOT include "_ALL", the Server MUST render any Service Contract Selection or Meter Device Selection sections of the authorization form for the authorization details field’s scope with Service Contracts preselected that match their contract_number value to one of the strings included in the provided array.
  • If Service Contracts are also preselected by other authorization details fields for the same scope (e.g. the service_types field), the Service Contracts preselected MUST be the intersection of Service Contracts preselected by the authorization details fields.

7.5. Preselect Meter Numbers

  • meter_numbers

TODO

7.6. Preselect Addresses

  • addresses

TODO

7.7. Preselect Service Types

  • service_types

TODO

7.8. Preselect Account Programs

  • account_programs

TODO

7.9. Preselect Contract Programs

  • contract_programs

TODO

7.10. Sync Until

  • sync_until

TODO

7.11. Bill Statement Date Start

  • statement_date_start

TODO

7.12. Bill Statement Date End

  • statement_date_end

TODO

7.13. Bill Section Start Date

  • start_date

TODO

7.14. Bill Section End Date

  • end_date

TODO

7.15. Usage Segment Start

  • segment_start

TODO

7.16. Usage Segment End

  • segment_end

TODO

7.17. Include Bill Statements

  • include_bill_statements

TODO

7.18. Include Bill Statement Files

  • include_bill_statement_files

TODO

7.19. Include Bill Sections

  • include_bill_sections

TODO

7.20. Include Bill Section Line Items

  • include_bill_section_line_items

TODO

7.21. Include Account Numbers

  • include_account_numbers

TODO

7.22. Include Account Details

  • include_account_details

TODO

7.23. Include Contract Numbers

  • include_contract_numbers

TODO

7.24. Include Contract Details

  • include_contract_details

TODO

7.25. Include Premise Numbers

  • include_premise_numbers

TODO

7.26. Include Addresses

  • include_addresses

TODO

7.27. Include Coordinates

  • include_coordinates

TODO

8. Client Registration Requirements

TODO

9. Customer Authorizations

TODO

10. Accounts API

This specification requires Servers provide a set of Application Programming Interfaces (APIs) allowing Clients to retrieve a Customer’s Account details for which they are authorized to access. These APIs are authenticated using a Bearer access_token granted that provisions access for a scope that allows access to the Accounts API.

10.1. Account Object Format

Account objects are formatted as JSON objects and contain the following named values:

  • cds_account_id - string - (REQUIRED) The Server’s unique identifier for this Account object.
  • cds_created - datetime - (REQUIRED) When the Server created this Account object.
  • cds_modified - datetime - (REQUIRED) When the Server last modified this Account object.
  • cds_account_parent - string or null - (REQUIRED) The cds_account_id of a parent Account object of which this Account is grouped under. If the Account is not a part of a parent grouping, this value is null.
  • customer_number - string or null - (REQUIRED) The identifier that a Customer has access to that identifies a collection of Accounts as being for the same Customer. If a Server only stores Accounts as the top-level identifier for Customers, or does not have a Customer-accessible identifier set for this Account, this value is null.
  • account_number - string - (REQUIRED) The number that a Customer sees on their bill and online user interface as the identifier for this Account.
  • account_name - string - (OPTIONAL) The name that a Customer sees on their bill and online user interface as the name for this Account, if available.
  • account_address - string - (OPTIONAL) The address that a Customer sees on their bill and online user interface as the address for this Account, if available. This string MAY have linebreaks, such as when the address is multiple lines.
  • account_type - AccountType - (REQUIRED) What type of Account this is.
  • account_contacts - Array[AccountContact] - (REQUIRED) A list of Account Contacts for the Account.

10.2. Listing Accounts

Clients may request to list Account objects that they have access to by making an HTTPS GET request, authenticated with a valid Bearer access_token that is scoped to provide access to a set of Accounts, to the cds_accounts_api URL included in the Client Registration Response or Clients API. The Account listing request responses are formatted as JSON objects and contain the following named values.

  • accounts - Array[Account] - (REQUIRED) A list of Accounts to which the requesting access_token is scoped to have access. If no Accounts are accessible, this value is an empty list ([]). If more than 100 Accounts are available to be listed, Servers MAY truncate the list and use the next value to link to the next segment of the list of Accounts.
  • next - URL or null - Where to request the next segment of the list of Accounts. If no next segment exists (i.e. the requester is at the end of the list), this value is null.
  • previous - URL or null - Where to request the previous segment of the list of Accounts. If no previous segment exists (i.e. the requester is at the front of the list), this value is null.

Servers MUST support Clients adding any of the following URL parameters to the GET request, which will filter the list of Accounts to be the intersection of results for each of the URL parameters filters:

  • cds_account_ids - A space-separated list of cds_account_id values for which the Servers MUST filter the Accounts.
  • customer_numbers - A space-separated list of customer_number values for which the Servers MUST filter the Accounts. Customer number values of null MUST be treated as invalid for this URL parameter filter (i.e. only populated customer_number values are available to be filtered using URL parameters).
  • account_numbers - A space-separated list of account_number values for which the Servers MUST filter the Accounts.
  • q - A search term for which the Servers MUST filter the Accounts following fields for values that case-insensitive contains the search term, if the field is accessible based on the Client’s access_token scope.
    • cds_account_id
    • customer_number
    • account_number
    • account_address
    • account_name

Listings of Account objects MUST be ordered in reverse chronological order by cds_modified timestamp, where the most recently updated relevant Account MUST be first in each listing.

11. Service Contracts API

This specification requires Servers provide a set of APIs allowing Clients to retrieve a Customer’s Service Contract details for which they are authorized to access. These APIs are authenticated using a Bearer access_token granted that provisions access for a scope that allows access to the Service Contracts API.

11.1. Service Contract Object Format

Service Contract objects are formatted as JSON objects and contain the following named values:

  • cds_servicecontract_id - string - (REQUIRED) The Server’s unique identifier for this Service Contract object.
  • cds_created - datetime - (REQUIRED) When the Server created this Service Contract object.
  • cds_modified - datetime - (REQUIRED) When the Server last modified this Service Contract object.
  • cds_account_id - string - (REQUIRED) The Account to which this Service Contract belongs.
  • account_number - string - (REQUIRED) The Account’s account_number duplicated to this Service Contract.
  • contract_number - string or null - (REQUIRED) The identifier that a Customer sees on their bill or online user interface as the identifier for this Service Contract. If a Server does not have a Customer-facing identifier for a Service Contract and the Client is not authorized to see the Server’s internal identifier for this Service Contract, this value is null.
  • contract_address - string - (OPTIONAL) The address that a Customer sees on their bill or online user interface as the address for this Service Contract, if available. This string MAY have linebreaks, such as when the address is multiple lines.
  • contract_status - ContractStatus - (REQUIRED) The current status of the Service Contract.
  • contract_type - ContractType - (REQUIRED) The type of agreement that this Service Contract represents.
  • contract_entity - string - (REQUIRED) With which entity the Customer has agreement for this Service Contract.
  • contract_start - date - (OPTIONAL) When the agreement that this Service Contract represents started.
  • contract_end - date or null - (OPTIONAL) When the agreement that this Service Contract represents ended. If the agreement is still ongoing, this value is null.
  • service_type - ServiceType - (REQUIRED) The type of utility or other service that this Service Contract provides.
  • service_class - ServiceClass - (REQUIRED) The class of service for which this Service Contract is categorized.
  • rateplan_code - string - (REQUIRED) A unique code for the current rate plan or tariff on which costs for this Service Contract are calculated.
  • rateplan_name - string - (REQUIRED) The name that a Customer sees on their bill or online user interface as the rate plan or tariff that applies to this Service Contract.

11.2. Listing Service Contracts

Clients may request to list Service Contract objects that they have access to by making an HTTPS GET request, authenticated with a valid Bearer access_token that is scoped to provide access to a set of Service Contracts, to the cds_servicecontracts_api URL included in the Client Registration Response or Clients API. The Service Contract listing request responses are formatted as JSON objects and contain the following named values.

  • service_contracts - Array[ServiceContract] - (REQUIRED) A list of Service Contracts to which the requesting access_token is scoped to have access. If no Service Contracts are accessible, this value is an empty list ([]). If more than 100 Service Contracts are available to be listed, Servers MAY truncate the list and use the next value to link to the next segment of the list of Service Contracts.
  • next - URL or null - Where to request the next segment of the list of Service Contracts. If no next segment exists (i.e. the requester is at the end of the list), this value is null.
  • previous - URL or null - Where to request the previous segment of the list of Service Contracts. If no previous segment exists (i.e. the requester is at the front of the list), this value is null.

Servers MUST support Clients adding any of the following URL parameters to the GET request, which will filter the list of Service Contracts to be the intersection of results for each of the URL parameters filters:

  • cds_servicecontract_ids - A space-separated list of cds_servicecontract_id values for which the Servers MUST filter the Service Contracts.
  • account_numbers - A space-separated list of account_number values for which the Servers MUST filter the Service Contracts.
  • contract_numbers - A space-separated list of contract_number values for which the Servers MUST filter the Service Contracts.
  • service_types - A space-separated list of service_type values for which the Servers MUST filter the Service Contracts.
  • q - A search term for which the Servers MUST filter the Service Contracts following fields for values that case-insensitive contains the search term, if the field is accessible based on the Client’s access_token scope.
    • cds_servicecontract_id
    • account_number
    • contract_number
    • contract_address
    • rateplan_code
    • rateplan_name

Listings of Service Contract objects MUST be ordered in reverse chronological order by cds_modified timestamp, where the most recently updated relevant Service Contract MUST be first in each listing.

12. Service Points API

This specification requires Servers provide a set of APIs allowing Clients to retrieve a Customer’s and Server’s Service Point details for which they are authorized to access. These APIs are authenticated using a Bearer access_token granted that provisions access for a scope that allows access to the Service Points API.

12.1. Service Point Object Format

Service Point objects are formatted as JSON objects and contain the following named values:

  • cds_servicepoint_id - string - (REQUIRED) The Server’s unique identifier for this Service Point object.
  • cds_created - datetime - (REQUIRED) When the Server created this Service Point object.
  • cds_modified - datetime - (REQUIRED) When the Server last modified this Service Point object.
  • servicepoint_number - string or null - (REQUIRED) The identifier that a Customer sees on their bill or online user interface as the identifier for this Service Point. If a Server does not have a Customer-facing identifier for a Service Point and the Client is not authorized to see the Server’s internal identifier for this Service Point, this value is null.
  • servicepoint_type - ServicePointType - (REQUIRED) The type of service point that this Service Point represents.
  • servicepoint_address - string or null - (REQUIRED) The address that a Customer sees on their bill or online user interface as the address for this Service Point, if available. Strings MAY have linebreaks, such as when the address is multiple lines. If a Server does not have a Customer-facing address for a Service Point and the Client is not authorized to see the Server’s internal address for this Service Point, this value is null.
  • latitude - decimal - (REQUIRED) The latitude that a Customer sees on their bill or online user interface as the latitude for this Service Point. If a Server does not have a Customer-facing latitude for a Service Point and the Client is not authorized to see the Server’s internal latitude for this Service Point, or the Server does not have latitude stored for this Server Point, this value is null.
  • longitude - decimal - (REQUIRED) The longitude that a Customer sees on their bill or online user interface as the longitude for this Service Point. If a Server does not have a Customer-facing longitude for a Service Point and the Client is not authorized to see the Server’s internal longitude for this Service Point, or the Server does not have longitude stored for this Server Point, this value is null.
  • current_servicecontracts - Array[string] - (REQUIRED) The list of cds_servicecontract_id values that identify Service Contracts that are currently providing a service to a Customer via this Service Point. This list MUST only include identifiers that the Client is authorized to see as scoped by their requesting access_token.
  • previous_servicecontracts - Array[string] - (REQUIRED) The list of cds_servicecontract_id values that identify Service Contracts that have previously provided a service to a Customer via this Service Point. This list MUST only include identifiers that the Client is authorized to see as scoped by their requesting access_token.
  • premise_number - string or null - (REQUIRED) The premise identifier that a Customer sees on their bill or online user interface as the premise identifier for this Service Point, if available. If a Server does not have a Customer-facing premise identifier for a Service Point and the Client is not authorized to see the Server’s internal premise identifier for this Service Point, or the Server does not have premise identifiers stored for this Server Point, this value is null.
  • premise_type - PremiseType or null - (REQUIRED) The premise type that a Customer sees on their bill or online user interface as the premise type for this Service Point, if available. If a Server does not have a Customer-facing premise type for a Service Point and the Client is not authorized to see the Server’s internal premise type for this Service Point, or the Server does not have premise type stored for this Server Point, this value is null.

12.2. Listing Service Points

Clients may request to list Service Point objects that they have access to by making an HTTPS GET request, authenticated with a valid Bearer access_token that is scoped to provide access to a set of Service Points, to the cds_servicepoints_api URL included in the Client Registration Response or Clients API. The Service Point listing request responses are formatted as JSON objects and contain the following named values.

  • service_points - Array[ServicePoint] - (REQUIRED) A list of Service Points to which the requesting access_token is scoped to have access. If no Service Points are accessible, this value is an empty list ([]). If more than 100 Service Points are available to be listed, Servers MAY truncate the list and use the next value to link to the next segment of the list of Service Points.
  • next - URL or null - Where to request the next segment of the list of Service Points. If no next segment exists (i.e. the requester is at the end of the list), this value is null.
  • previous - URL or null - Where to request the previous segment of the list of Service Points. If no previous segment exists (i.e. the requester is at the front of the list), this value is null.

Servers MUST support Clients adding any of the following URL parameters to the GET request, which will filter the list of Service Points to be the intersection of results for each of the URL parameters filters:

  • cds_servicepoint_ids - A space-separated list of cds_servicepoint_id values for which the Servers MUST filter the Service Points.
  • servicepoint_number - A space-separated list of servicepoint_number values for which the Servers MUST filter the Service Points.
  • current_servicecontracts - A space-separated list of current_servicecontracts values for which the Servers MUST filter the Meter Devices.
  • previous_servicecontracts - A space-separated list of previous_servicecontracts values for which the Servers MUST filter the Meter Devices.
  • q - A search term for which the Servers MUST filter the Service Points following fields for values that case-insensitive contains the search term, if the field is accessible based on the Client’s access_token scope.
    • cds_servicepoint_id
    • servicepoint_address
    • servicepoint_number
    • premise_number
    • property_number
    • parcel_number

Listings of Service Point objects MUST be ordered in reverse chronological order by cds_modified timestamp, where the most recently updated relevant Service Point MUST be first in each listing.

13. Meter Devices API

This specification requires Servers provide a set of APIs allowing Clients to retrieve a Customer’s and Server’s Meter Device details for which they are authorized to access. These APIs are authenticated using a Bearer access_token granted that provisions access for a scope that allows access to the Meter Devices API.

13.1. Meter Device Object Format

Meter Device objects are formatted as JSON objects and contain the following named values:

  • cds_meterdevice_id - string - (REQUIRED) The Server’s unique identifier for this Meter Device object.
  • cds_created - datetime - (REQUIRED) When the Server created this Meter Device object.
  • cds_modified - datetime - (REQUIRED) When the Server last modified this Meter Device object.
  • meter_number - string or null - (REQUIRED) The identifier that a Customer sees on their bill or online user interface or on the face of their physical meter as the identifier for this Meter Device. If a Server does not have a Customer-facing identifier for a Meter Device and the Client is not authorized to see the Server’s internal identifier for this Meter Device, this value is null.
  • meter_type - MeterType - (REQUIRED) The type of metering device that this Meter Device represents.
  • current_servicepoints - Array[string] - (REQUIRED) The list of cds_servicepoint_id values that identify Service Points where this Meter Device is currently installed or associated. This list MUST only include identifiers that the Client is authorized to see as scoped by their requesting access_token.
  • previous_servicepoints - Array[string] - (REQUIRED) The list of cds_servicepoint_id values that identify Service Points where this Meter Device was previously installed or associated. This list MUST only include identifiers that the Client is authorized to see as scoped by their requesting access_token.

13.2. Listing Meter Devices

Clients may request to list Meter Device objects that they have access to by making an HTTPS GET request, authenticated with a valid Bearer access_token that is scoped to provide access to a set of Meter Devices, to the cds_meterdevices_api URL included in the Client Registration Response or Clients API. The Meter Device listing request responses are formatted as JSON objects and contain the following named values.

  • meter_devices - Array[MeterDevice] - (REQUIRED) A list of Meter Devices to which the requesting access_token is scoped to have access. If no Meter Devices are accessible, this value is an empty list ([]). If more than 100 Meter Devices are available to be listed, Servers MAY truncate the list and use the next value to link to the next segment of the list of Meter Devices.
  • next - URL or null - Where to request the next segment of the list of Meter Devices. If no next segment exists (i.e. the requester is at the end of the list), this value is null.
  • previous - URL or null - Where to request the previous segment of the list of Meter Devices. If no previous segment exists (i.e. the requester is at the front of the list), this value is null.

Servers MUST support Clients adding any of the following URL parameters to the GET request, which will filter the list of Meter Devices to be the intersection of results for each of the URL parameters filters:

  • cds_meterdevice_ids - A space-separated list of cds_meterdevice_id values for which the Servers MUST filter the Meter Devices.
  • meter_number - A space-separated list of meter_number values for which the Servers MUST filter the Meter Devices.
  • current_servicepoints - A space-separated list of current_servicepoint values for which the Servers MUST filter the Meter Devices.
  • previous_servicepoints - A space-separated list of previous_servicepoints values for which the Servers MUST filter the Meter Devices.
  • q - A search term for which the Servers MUST filter the Meter Devices following fields for values that case-insensitive contains the search term, if the field is accessible based on the Client’s access_token scope.
    • cds_meterdevice_id
    • meter_number

Listings of Meter Device objects MUST be ordered in reverse chronological order by cds_modified timestamp, where the most recently updated relevant Meter Device MUST be first in each listing.

14. Bill Statements API

This specification requires Servers provide a set of APIs allowing Clients to retrieve a Customer’s and Server’s Bill Statement details for which they are authorized to access. These APIs are authenticated using a Bearer access_token granted that provisions access for a scope that allows access to the Bill Statements API.

14.1. Bill Statement Object Format

Bill Statement objects are formatted as JSON objects and contain the following named values:

  • cds_billstatement_id - string - (REQUIRED) The Server’s unique identifier for this Bill Statement object.
  • cds_created - datetime - (REQUIRED) When the Server created this Bill Statement object.
  • cds_modified - datetime - (REQUIRED) When the Server last modified this Bill Statement object.
  • cds_account_id - string - (REQUIRED) The Account for which this Bill Statement was issued.
  • account_number - string - (REQUIRED) The Account’s account_number at the time that this Bill Statement was issued.
  • statement_date - date - (REQUIRED) The statement date that appears on the Customer-facing bill.
  • currency - string - (REQUIRED) The currency for this Bill Statement’s charge values as an [ISO 4217] currency code.
  • file_uri - URL - (OPTIONAL) A link to the bill statement file that was provided to the Customer, if available. If this Bill Statement was mailed to the Customer, this value is a link to the digital PDF copy of the mailed bill. Authentication for the linked file MUST be the same authentication as required for accessing this Bill Statement.
  • file_mimetype - string - (OPTIONAL) The MIME type for the file_uri. This field is required if the file_uri field is populated.
  • previous_balance_amount - decimal - (OPTIONAL) The value shown on the Customer-facing bill statement as the previous balance for the Account, if available.
  • previous_balance_paid - decimal - (OPTIONAL) The value shown on the Customer-facing bill statement as the previous balance paid for the Account, if available.
  • previous_balance_unpaid - decimal - (OPTIONAL) The value shown on the Customer-facing bill statement as the previous balance unpaid for the Account, if available.
  • new_charges_amount - decimal - (OPTIONAL) The value shown on the Customer-facing bill statement as the new credits and charges total, if available.
  • new_charges - Array[NewCharge] - (OPTIONAL) A list of new overall charges shown on the Customer-facing bill statement, if available.
  • new_balance_amount - decimal - (OPTIONAL) The value shown on the Customer-facing bill statement as the new Account balance, if available.
  • amount_due - decimal - (REQUIRED) The value shown on the Customer-facing bill statement as the amount due, if available.
  • amount_due_date - date - (REQUIRED) The value shown on the Customer-facing bill statement as the date that the amount_due value is due, if available.
  • shutoff_prevention_minimum_due - decimal or null - (REQUIRED) The value shown on the Customer-facing bill statement as the minimum amount due to prevent service shutoff, if available. If there is no shutoff notice on the Customer-facing bill statement, this value is null.
  • shutoff_prevention_date - date or null - (REQUIRED) The value shown on the Customer-facing bill statement as the date that the shutoff_prevention_minimum_due value is due, if available. If shutoff_prevention_minimum_due is null, this value is also null.
  • program_participations - Array[ProgramParticipation] - (REQUIRED) A list of Account-level programs in which the Customer is participating. If the Server does not have this information or the Customer is not participating in any Account-level programs, this value is and empty list ([]).

14.2. Listing Bill Statements

Clients may request to list Bill Statement objects that they have access to by making an HTTPS GET request, authenticated with a valid Bearer access_token that is scoped to provide access to a set of Bill Statements, to the cds_billstatement_api URL included in the Client Registration Response or Clients API. The Bill Statement listing request responses are formatted as JSON objects and contain the following named values.

  • bill_statements - Array[BillStatement] - (REQUIRED) A list of Bill Statements to which the requesting access_token is scoped to have access. If no Bill Statements are accessible, this value is an empty list ([]). If more than 100 Bill Statements are available to be listed, Servers MAY truncate the list and use the next value to link to the next segment of the list of Bill Statements.
  • next - URL or null - Where to request the next segment of the list of Bill Statements. If no next segment exists (i.e. the requester is at the end of the list), this value is null.
  • previous - URL or null - Where to request the previous segment of the list of Bill Statements. If no previous segment exists (i.e. the requester is at the front of the list), this value is null.

Servers MUST support Clients adding any of the following URL parameters to the GET request, which will filter the list of Bill Statements to be the intersection of results for each of the URL parameters filters:

  • cds_billstatement_ids - A space-separated list of cds_billstatement_id values for which the Servers MUST filter the Bill Statements.
  • before - A date for which the Server MUST filter the Bill Statement statement_date to values that are on or before this date.
  • after - A date for which the Server MUST filter the Bill Statement statement_date to values that are on or after this date.
  • cds_account_ids - A space-separated list of cds_account_id values for which the Servers MUST filter the Bill Statements.
  • account_numbers - A space-separated list of account_number values for which the Servers MUST filter the Bill Statements.

Listings of Bill Statement objects MUST be ordered in reverse chronological order by statement_date date, where the most recent dated relevant Bill Statement MUST be first in each listing. In situations where relevant Bill Statement objects have the same statement_date, those Bill Statements with the same statement_date are further ordered in reverse chronological order by cds_modified timestamp, where the most recently updated relevant Bill Statement is listed first.

15. Bill Sections API

This specification requires Servers provide a set of APIs allowing Clients to retrieve a Customer’s and Server’s Bill Section details for which they are authorized to access. These APIs are authenticated using a Bearer access_token granted that provisions access for a scope that allows access to the Bill Sections API.

15.1. Bill Section Object Format

Bill Section objects are formatted as JSON objects and contain the following named values:

  • cds_billsection_id - string - (REQUIRED) The Server’s unique identifier for this Bill Section object.
  • cds_created - datetime - (REQUIRED) When the Server created this Bill Section object.
  • cds_modified - datetime - (REQUIRED) When the Server last modified this Bill Section object.
  • cds_billstatement_id - string or null - (REQUIRED) The Bill Statement for which this Bill Section was issued. If the Client is not authorized to see the related Bill Statement, this value is null.
  • cds_account_id - string - (REQUIRED) The Account for which this Bill Section was issued.
  • account_number - string - (REQUIRED) The Account’s account_number at the time that this Bill Section was issued.
  • section_type - BillSectionType - (REQUIRED) The type of bill section that this Bill Section represents.
  • start_date - date - (REQUIRED) The start date of services provided for which this Bill Section covers.
  • end_date - date - (REQUIRED) The end date of services provided for which this Bill Section covers.
  • currency - string - (REQUIRED) The currency for this Bill Section’s charge values as an [ISO 4217] currency code.
  • distribution_entity - DistributionEntity or null - (REQUIRED) The details for the utility or other entity providing distribution for the services that this Bill Section covers. If the services provided that are covered by this Bill Section do not have distribution, this value is null.
  • load_serving_entity - LoadServingEntity or null - (REQUIRED) The details for the utility or other entity providing distribution for the services that this Bill Section covers. If the services provided that are covered by this Bill Section do not have a supply or retailer component, this value is null. If the load serving entity is the same as the distributor, the Load Serving Entity type value MUST be distributor and no other fields are populated in the Load Serving Entity object.
  • related_servicecontracts - Array[string] - (REQUIRED) The list of cds_servicecontract_id values that identify Service Contracts to which this Bill Section is applicable. This list MUST only include identifiers that the Client is authorized to see as scoped by their requesting access_token.
  • related_servicepoints - Array[string] - (REQUIRED) The list of cds_servicepoint_id values that identify Service Points to which this Bill Section is applicable. This list MUST only include identifiers that the Client is authorized to see as scoped by their requesting access_token.
  • related_meterdevices - Array[string] - (REQUIRED) The list of cds_meterdevice_id values that identify Meter Devices to which this Bill Section is applicable. This list MUST only include identifiers that the Client is authorized to see as scoped by their requesting access_token.
  • related_billsections - Array[string] - (REQUIRED) The list of cds_billsection_id that identify other Bill Sections that were issued alongside this Bill Section, where those Bill Sections represent another set of charges covering the same Service Contract. This list MUST only include identifiers that the Client is authorized to see as scoped by their requesting access_token.
  • line_items - Array[BillSectionLineItem] - (REQUIRED) A list of the Bill Section Line Item objects that denote the individual charges listed on the Customer-facing bill statement section represented by this Bill Section.
  • energy_summary - Array[BillSectionEnergySummary] - (REQUIRED) A list of the Bill Section Energy Summary objects that detail the service’s energy usage and other values on the Customer-facing bill statement section represented by this Bill Section.

15.2. Listing Bill Sections

Clients may request to list Bill Section objects that they have access to by making an HTTPS GET request, authenticated with a valid Bearer access_token that is scoped to provide access to a set of Bill Sections, to the cds_billsection_api URL included in the Client Registration Response or Clients API. The Bill Section listing request responses are formatted as JSON objects and contain the following named values.

  • bill_sections - Array[BillSection] - (REQUIRED) A list of Bill Sections to which the requesting access_token is scoped to have access. If no Bill Sections are accessible, this value is an empty list ([]). If more than 100 Bill Sections are available to be listed, Servers MAY truncate the list and use the next value to link to the next segment of the list of Bill Sections.
  • next - URL or null - Where to request the next segment of the list of Bill Sections. If no next segment exists (i.e. the requester is at the end of the list), this value is null.
  • previous - URL or null - Where to request the previous segment of the list of Bill Sections. If no previous segment exists (i.e. the requester is at the front of the list), this value is null.

Servers MUST support Clients adding any of the following URL parameters to the GET request, which will filter the list of Bill Sections to be the intersection of results for each of the URL parameters filters:

  • cds_billsection_ids - A space-separated list of cds_billsection_id values for which the Servers MUST filter the Bill Sections.
  • before - A date for which the Server MUST filter the Bill Section start_date to values that are on or before this date.
  • after - A date for which the Server MUST filter the Bill Section end_date to values that are on or after this date.
  • cds_billstatement_ids - A space-separated list of cds_billstatement_id values for which the Servers MUST filter the Bill Sections.
  • cds_account_ids - A space-separated list of cds_account_id values for which the Servers MUST filter the Bill Sections.
  • account_numbers - A space-separated list of account_number values for which the Servers MUST filter the Bill Sections.
  • cds_servicecontract_ids - A space-separated list of related_servicecontracts values for which the Servers MUST filter the Bill Sections.
  • contract_numbers - A space-separated list of related_servicecontracts listed Service Contract contract_number values for which the Servers MUST filter the Bill Sections.

Listings of Bill Section objects MUST be ordered in alphanumeric order by account_number. In situations where relevant Bill Section objects have the same account_number, those Bill Sections with the same account_number are further ordered in alphanumeric order by contract_number. In situations where relevant Bill Section objects have the same account_number and contract_number, those Bill Sections with the same account_number and contract_number are further ordered in chronological order by start_date, where the relevant Bill Section with the earliest date is listed first. In situations where relevant Bill Section objects have the same account_number, contract_number, and start_date, those Bill Sections with the same account_number, contract_number, and start_date are further ordered in reverse chronological order by modified, where the most recently updated relevant Bill Section is listed first.

16. Aggregations API

This specification requires Servers provide a set of APIs allowing Clients to retrieve a Server’s Aggregation objects for which they are authorized to access. These APIs are authenticated using a Bearer access_token granted that provisions access for a scope that allows access to the Aggregations API.

16.1. Aggregation Object Format

Aggregation objects are formatted as JSON objects and contain the following named values:

  • cds_aggregation_id - string - (REQUIRED) The Server’s unique identifier for this Aggregation object.
  • cds_created - datetime - (REQUIRED) When the Server created this Aggregation object.
  • cds_modified - datetime - (REQUIRED) When the Server last modified this Aggregation object.
  • aggregation_type - AggregationType - (REQUIRED) The type of aggregation that this Aggregation represents.
  • aggregation_number - string or null - (REQUIRED) The aggregation identifier that a Client sees in Server documentation or other online interfaces as the aggregation identifier for this Aggregation, if available. If a Server does not have a Client-facing aggregation identifier for an Aggregation and the Client is not authorized to see the Server’s internal aggregation identifier for this Aggregation, or the Server does not have aggregation identifiers stored for this Aggregation, this value is null.
  • addresses - Array[string] - (OPTIONAL) A list of addresses that are associated with this Aggregation, if applicable for the aggregation_type. Strings MAY have linebreaks, such as when the address is multiple lines.
  • regions - Array[AggregationRegion] - (OPTIONAL) A list of Aggregation Regions that are associated with this Aggregation, if applicable for the aggregation_type.
  • consents_required - Array[ConsentRequirement] - (OPTIONAL) A list of Consent Requirements that are required for this Aggregation, if applicable for the aggregation_type.

16.2. Listing Aggregations

Clients may request to list Aggregation objects that they have access to by making an HTTPS GET request, authenticated with a valid Bearer access_token that is scoped to provide access to a set of Aggregations, to the cds_aggregations_api URL included in the Client Registration Response or Clients API. The Aggregation listing request responses are formatted as JSON objects and contain the following named values.

  • aggregations - Array[Aggregation] - (REQUIRED) A list of Aggregations to which the requesting access_token is scoped to have access. If no Aggregations are accessible, this value is an empty list ([]). If more than 100 Aggregations are available to be listed, Servers MAY truncate the list and use the next value to link to the next segment of the list of Aggregations.
  • next - URL or null - Where to request the next segment of the list of Aggregations. If no next segment exists (i.e. the requester is at the end of the list), this value is null.
  • previous - URL or null - Where to request the previous segment of the list of Aggregations. If no previous segment exists (i.e. the requester is at the front of the list), this value is null.

Servers MUST support Clients adding any of the following URL parameters to the GET request, which will filter the list of Aggregations to be the intersection of results for each of the URL parameters filters:

  • cds_aggregation_ids - A space-separated list of cds_aggregation_id values for which the Servers MUST filter the Aggregations.
  • aggregation_numbers - A space-separated list of aggregation_number values for which the Servers MUST filter the Aggregations.
  • aggregation_types - A space-separated list of aggregation_type values for which the Servers MUST filter the Aggregations.
  • q - A search term for which the Servers MUST filter the Aggregations following fields for values that case-insensitive contains the search term, if the field is accessible based on the Client’s access_token scope.
    • cds_aggregation_id
    • aggregation_number
    • addresses
    • regions

Listings of Aggregation objects MUST be ordered in reverse chronological order by modified timestamp, where the most recently updated relevant Aggregation MUST be first in each listing.

17. Usage Segments API

This specification requires Servers provide a set of APIs allowing Clients to retrieve a Customer’s and Server’s Usage Segment objects for which they are authorized to access. These APIs are authenticated using a Bearer access_token granted that provisions access for a scope that allows access to the Usage Segments API.

17.1. Usage Segment Object Format

Usage Segment objects are formatted as JSON objects and contain the following named values:

  • cds_usagesegment_id - string - (REQUIRED) The Server’s unique identifier for this Usage Segment object.
  • cds_created - datetime - (REQUIRED) When the Server created this Usage Segment object.
  • cds_modified - datetime - (REQUIRED) When the Server last modified this Usage Segment object.
  • related_aggregations - Array[string] - (REQUIRED) The list of cds_aggregation_id values that identify Aggregations to which this Usage Segment is applicable.
  • related_accounts - Array[string] - (REQUIRED) The list of cds_account_id values that identify Accounts to which this Usage Segment is applicable.
  • related_servicecontracts - Array[string] - (REQUIRED) The list of cds_servicecontract_id values that identify Service Contracts to which this Usage Segment is applicable.
  • related_servicepoints - Array[string] - (REQUIRED) The list of cds_servicepoint_id values that identify Service Points to which this Usage Segment is applicable.
  • related_meterdevices - Array[string] - (REQUIRED) The list of cds_meterdevice_id values that identify Meter Devices to which this Usage Segment is applicable.
  • related_billsections - Array[string] - (REQUIRED) The list of cds_billsection_id values that identify Bill Sections to which this Usage Segment is applicable.
  • segment_start - datetime - (REQUIRED) The starting timestamp for the list of Usage Segment values.
  • segment_end - datetime - (REQUIRED) The ending timestamp for the list of Usage Segment values. For values that represent a duration (e.g. 15-min usage interval reading), the segment_end MUST represent the timestamp at the end of the duration.
  • interval - decimal - (REQUIRED) How long between values, in seconds. For values representing a duration interval (e.g. kwh usage intervals), this interval represents the duration of each interval, where the next value starts immediately at the end of the prior interval value with no time gap. For values representing instantaneous readings (e.g. register read), this interval represents the time between the readings provided in the values.
  • format - Array[ValueFormat] - (REQUIRED) For each entry in values, these are the formats of that are included, presented in the order in which the values are presented.
  • values - Array[ValueSet] - (REQUIRED) A list of Value Sets that represent the entries included in the Usage Segment.

Servers MUST only inlude unique identifiers in related_aggregations, related_accounts, related_servicecontracts, related_servicepoints, related_meterdevices, and related_billsections lists MUST only include identifiers that the Client is authorized to see as scoped by their requesting access_token.

17.2. Usage Segment Value Formats

The Usage Segment format field provides an ordered list of strings that denote the object types that are included in each Usage Segment values entry’s Value Set. Usage Segments are organized this way so that the format listing essentially provides a “schema” of object types to expect when parsing the values Value Sets, which removes the need for each object in each Value Set to include repeated fields, such as an object type value.

The following Usage Segment format strings are specified with their corresponding Value Set object types:

Value format strings MAY be repeated in the format listing, indicating there are multiple value objects in the Value Set for that format. This is useful when a Server provides multiple variations of optional fields for the same type of value.

Extensions to this specification MAY further define additional formats other that what is listed above. Client MUST ignore format values they do not know how to interpret.

17.3. Usage Segment Value Set Format

The Usage Segment values field provides an ordered list of Value Set entries. A Value Set entry is an array that contains an ordered list of Value objects, where the type of each Value object which is defined by the order of the format listing.

Each Value Set entry in the values listing represents an increment of interval seconds in the Usage Segment from the segment_start. For example, if a Usage Segment has a segment_start of 2025-01-01T00:00:00Z, an interval of 900, and four Value Set entries in the values, the Value Set entries would represent the each 15 minute period of a one hour segment (2025-01-01T00:00:00Z - 2025-01-01T00:15:00Z, 2025-01-01T00:15:00Z - 2025-01-01T00:30:00Z, 2025-01-01T00:30:00Z - 2025-01-01T00:45:00Z, and 2025-01-01T00:45:00Z - 2025-01-01T01:00:00Z).

If a Value object is not available for a specific Value Set. Servers MUST replace the item in the Value Set with null.

17.4. Usage Segment Value Object Format

TODO

17.5. Listing Usage Segments

Clients may request to list Usage Segment objects that they have access to by making an HTTPS GET request, authenticated with a valid Bearer access_token that is scoped to provide access to a set of Usage Segments, to the cds_usagesegments_api URL included in the Client Registration Response or Clients API. The Usage object listing request responses are formatted as JSON objects and contain the following named values.

  • usage_segments - Array[UsageSegment] - (REQUIRED) A list of Usage Segments to which the requesting access_token is scoped to have access. If no Usage Segments are accessible, this value is an empty list ([]). If more than 100 Usage Segments are available to be listed, Servers MAY truncate the list and use the next value to link to the next segment of the list of Usage Segments.
  • next - URL or null - Where to request the next segment of the list of Usage Segments. If no next segment exists (i.e. the requester is at the end of the list), this value is null.
  • previous - URL or null - Where to request the previous segment of the list of Usage Segments. If no previous segment exists (i.e. the requester is at the front of the list), this value is null.

Servers MUST support Clients adding any of the following URL parameters to the GET request, which will filter the list of Usage Segments to be the intersection of results for each of the URL parameters filters:

  • cds_usagesegment_ids - A space-separated list of cds_usagesegment_id values for which the Servers MUST filter the Usage Segments.
  • before - A datetime for which the Server MUST filter the Usage Segment object segment_start to values that are on or before this date.
  • after - A datetime for which the Server MUST filter the Usage Segment object segment_end to values that are on or after this date.
  • cds_account_ids - A space-separated list of cds_account_id values for which the Servers MUST filter the Usage Segments.
  • account_numbers - A space-separated list of account_number values for which the Servers MUST filter the Usage Segments.
  • cds_servicecontract_ids - A space-separated list of cds_servicecontract_id values for which the Servers MUST filter the Usage Segments.
  • contract_numbers - A space-separated list of contract_number values for which the Servers MUST filter the Usage Segments.
  • cds_servicepoint_ids - A space-separated list of cds_servicepoint_id values for which the Servers MUST filter the Usage Segments.
  • servicepoint_numbers - A space-separated list of servicepoint_number values for which the Servers MUST filter the Usage Segments.
  • cds_meterdevice_ids - A space-separated list of cds_meterdevice_ids values for which the Servers MUST filter the Usage Segments.
  • meter_numbers - A space-separated list of meter_numbers values for which the Servers MUST filter the Usage Segments.
  • cds_billsection_ids - A space-separated list of cds_billsection_id values for which the Servers MUST filter the Usage Segments.

Listings of Usage Segments MUST be ordered in alphanumeric order by aggregation_number. In situations where relevant Usage Segments have the same aggregation_number, those Usage Segments with the same aggregation_number are further ordered in alphanumeric order by account_number. In situations where relevant Usage Segments have the same account_number, those Usage Segments with the same account_number are further ordered in alphanumeric order by contract_number. In situations where relevant Usage Segments have the same contract_number, those Usage Segments with the same contract_number are further ordered in chronological order by segment_start, where the relevant Usage Segment object with the earliest date is listed first. In situations where relevant Usage Segments have the same segment_start, those Usage Segments with the same segment_start are further ordered in reverse chronological order by cds_modified, where the most recently updated relevant Usage Segment object is listed first.

18. Energy Attribute Certificates API

This specification requires Servers provide a set of APIs allowing Clients to retrieve a Customer’s and Server’s Energy Attribute Certificate (EAC) objects for which they are authorized to access. These APIs are authenticated using a Bearer access_token granted that provisions access for a scope that allows access to the Energy Attribute Certificates API.

18.1. Energy Attribute Certificate Object Format

EAC objects are formatted as JSON objects and contain the following named values:

  • cds_eac_id - string - (REQUIRED) The Server’s unique identifier for this EAC object.
  • cds_created - datetime - (REQUIRED) When the Server created this EAC object.
  • cds_modified - datetime - (REQUIRED) When the Server last modified this EAC object.
  • beneficiary_type - BeneficiaryType - (REQUIRED) The type of beneficiary to which this EAC is applied.
  • beneficiaries - Array[string] - (REQUIRED) The list of identifiers to which the EAC is allocated, based on the beneficiary_type.
  • eac_numbers - Array[string] - (REQUIRED) A list of EAC identifier that a Client or Customer sees in Server documentation, Customer documents, Certificate Registries, or other interfaces as the identifier for this EAC, if available. If a Server does not have a Client or Customer-facing EAC identifier and the Client is not authorized to see the Server’s internal EAC identifier for this EAC, or the Server does not have identifiers stored for this EAC, this value is an emtpy list ([]).
  • eac_format - string - (REQUIRED) The format of the EAC data linked in the ead_data_url. Possible values of this format MUST be included in the Server Metadata’s cds_eac_formats object. Clients MUST ignore eac_format values that they do not know how to interpret.
  • eac_data_url - URL - (REQUIRED) A link to an endpoint containing the EAC’s data (e.g. asset identifiers, values, locations, etc.). This is a URL, rather than a structured object because there are many EAC formats available across regions, registries, and jursidictions, and rather than this specification attempting to accomodate all EAC formats, Servers only need to link to the EAC data in the format they have the data accessible. URL endpoints provided in this field MUST be accessible under the same authentication and security requirements as accessing this specification’s EAC API endpoints. URLs may link to an individual formatted file, compressed archive files, the base URL to a set of APIs, or any other type of data location, as long as the data is formatted in the manner described by the eac_format field. In situations where the URL is the base URL to another set of APIs that contain the EAC data, Servers MUST scope the access to that API to only the relevant EAC data for the specific Grant that the access_token provides.
  • period_start - datetime - (REQUIRED) When the EAC coverage time period started.
  • period_end - datetime - (REQUIRED) When the EAC coverage time period ended or will end.

18.2. Beneficiary Types

EAC object beneficiary_type values MUST be one of the following:

  • customer - Within the EAC’s destination, the EAC is further applied to an individual Power Purchase Agreement (PPA) for a set of Customers. When the beneficiary_type is customer, the beneficiaries MUST have values of the relevant customer_number values. NOTE: listed customer_number values MUST be authorized to be visible to the Client, so while the destination MAY allocate beneficiaries of the EAC to multiple customers, only the customer numbers that are available to be seen as part of the Client’s authorization MUST be listed.
  • account - Within the EAC’s destination, the EAC is further applied to an individual Power Purchase Agreement (PPA) for a set of Customer accounts. When the beneficiary_type is account, the beneficiaries MUST have values of the relevant cds_account_id values. NOTE: listed cds_account_id values MUST be authorized to be visible to the Client, so while the destination MAY allocate beneficiaries of the EAC to multiple accounts, only the accounts that are available to be seen as part of the Client’s authorization MUST be listed.
  • servicecontract - Within the EAC’s destination, the EAC is further applied to an individual Power Purchase Agreement (PPA) for a set of Customer service contracts. When the beneficiary_type is servicecontract, the beneficiaries MUST have values of the relevant cds_servicecontract_id values. NOTE: listed cds_servicecontract_id values MUST be authorized to be visible to the Client, so while the destination MAY allocate beneficiaries of the EAC to multiple contracts, only the service contracts that are available to be seen as part of the Client’s authorization MUST be listed.
  • rateplan - Within the EAC’s destination, the EAC is further applied to a rate plan or tariff for the customers with service contracts on that rate plan. When the beneficiary_type is rateplan, the beneficiaries MUST have the value of the relevant rateplan_code values. NOTE: listed rateplan_code values MUST be authorized to be visible to the Client, so while the destination MAY allocate beneficiaries of the EAC to multiple rate plans or tariffs, only the rate plans that are available to be seen as part of the Client’s authorization MUST be listed.
  • program - Within the EAC’s destination, the EAC is further applied to a special program in which customers are participating. When the beneficiary_type is program, the beneficiaries MUST have the value of the relevant program_id values. NOTE: listed program_id values MUST be authorized to be visible to the Client, so while the destination MAY allocate beneficiaries of the EAC to multiple special programs, only the rate plans that are available to be seen as part of the Client’s authorization MUST be listed.
  • general - Within the EAC’s destination, the EAC is applied generally to the base energy usage profile for all customers. When the beneficiary_type is general, the beneficiaries MUST be an empty list ([]).

18.3. EAC Data Format Description Object

EAC Data Format Descriptions objects are formatted as JSON objects and contain the following named values:

  • id - string - (REQUIRED) The identifier of the EAC data format that is set as the EAC object eac_format value when the EAC object links to EAC data in the eac_data_url that is structured in this format.
  • name - string - (REQUIRED) A human-readable name of the EAC data format (e.g. “Energy Tag API”).
  • description - string - (REQUIRED) A human-readable description of the EAC data format.
  • documentation - URL - (REQUIRED) A link to developer documentation on the EAC data format.

18.4. Listing Energy Attribute Certificates

Clients may request to list EAC objects that they have access to by making an HTTPS GET request, authenticated with a valid Bearer access_token that is scoped to provide access to a set of EACs, to the cds_eacs_api URL included in the Client Registration Response or Clients API. The EAC object listing request responses are formatted as JSON objects and contain the following named values.

  • eacs - Array[EnergyAttributeCredit] - (REQUIRED) A list of EACs to which the requesting access_token is scoped to have access. If no EACs are accessible, this value is an empty list ([]). If more than 100 EACs are available to be listed, Servers MAY truncate the list and use the next value to link to the next segment of the list of EACs.
  • next - URL or null - Where to request the next segment of the list of EACs. If no next segment exists (i.e. the requester is at the end of the list), this value is null.
  • previous - URL or null - Where to request the previous segment of the list of EACs. If no previous segment exists (i.e. the requester is at the front of the list), this value is null.

Servers MUST support Clients adding any of the following URL parameters to the GET request, which will filter the list of EACs to be the intersection of results for each of the URL parameters filters:

  • cds_eac_ids - A space-separated list of cds_eac_id values for which the Servers MUST filter the EACs.
  • eac_numbers - A space-separated list of eac_numbers values for which the Servers MUST filter the EACs.
  • beneficiaries - A space-separated list of beneficiaries values for which the Servers MUST filter the EACs. Since beneficiaries contains values based on the beneficiary_type, different types of beneficiaries may have the same value (e.g. customer_number and account_number may be the same). For listings returned using this filter parameter, Clients SHOULD check the beneficiary_type for each returned result to filter out any results that may have been inadvertent inclusions due to value collision on the Server.
  • before - A datetime for which the Server MUST filter the EAC object period_start to values that are on or before this datetime.
  • after - A datetime for which the Server MUST filter the EAC object period_end to values that are on or after this datetime.

Listings of EACs MUST be ordered in reverse chronological order by period_start, where the most recently started EAC is first. In situations where relevant EACs have the same period_start, those EACs with the same period_start are further ordered in reverse chronological order by cds_created, where the most recently created EAC is first. In situations where relevant EACs have the same period_start and cds_created, those EACs with the same period_start and cds_created are further ordered in alphanumeric order by cds_eac_id.

19. Extensions

TODO

20. Security Considerations

TODO

21. Examples

TODO

22. References

BCP 14 - “Best Current Practice 14”, Internet Engineering Task Force (IETF),
https://www.rfc-editor.org/info/bcp14

CDS-WG1-02 - “Client Registration”, CDS-WG1-02, LF Energy Standards and Specifications (LFESS),
https://cds-registration.lfenergy.org/specs/cds-wg1-02/

CDS-WG1-02 Section 3.2 - “Metadata Object Format”, CDS-WG1-02, LF Energy Standards and Specifications (LFESS),
https://cds-registration.lfenergy.org/specs/cds-wg1-02/#auth-server-metadata-format

CDS-WG1-02 Section 3.3 - “Scopes Supported”, CDS-WG1-02, LF Energy Standards and Specifications (LFESS),
https://cds-registration.lfenergy.org/specs/cds-wg1-02/#scopes

CDS-WG1-02 Section 3.4 - “Scope Descriptions Object Format”, CDS-WG1-02, LF Energy Standards and Specifications (LFESS),
https://cds-registration.lfenergy.org/specs/cds-wg1-02/#scope-descriptions-format

CDS-WG1-02 Section 3.5 - “Registration Field Object Format”, CDS-WG1-02, LF Energy Standards and Specifications (LFESS),
https://cds-registration.lfenergy.org/specs/cds-wg1-02/#registration-field-format

CDS-WG1-02 Section 3.8 - “Authorization Details Field Object Format”, CDS-WG1-02, LF Energy Standards and Specifications (LFESS),
https://cds-registration.lfenergy.org/specs/cds-wg1-02/#auth-details-field-formats

ISO 4217 - “Currency Codes”, ISO 4217, International Organization for Standardization (ISO),
https://www.iso.org/iso-4217-currency-codes.html

RFC 3339 Section 5.6 - Section 5.6. Internet Date/Time Format, “Date and Time on the Internet: Timestamps”, RFC 3339, Internet Engineering Task Force (IETF),
https://www.rfc-editor.org/rfc/rfc3339#section-5.6

RFC 3986 Section 1.1.3 - Section 1.1.3. URI, URL, and URN, “Uniform Resource Identifier (URI): Generic Syntax”, RFC 3986, Internet Engineering Task Force (IETF),
https://www.rfc-editor.org/rfc/rfc3986#section-1.1.3

RFC 6749 Section 4.1 - Section 4.1. Authorization Code Grant, “The OAuth 2.0 Authorization Framework”, RFC 6749, Internet Engineering Task Force (IETF),
https://www.rfc-editor.org/rfc/rfc6749#section-4.1

RFC 6749 Section 4.4 - Section 4.4. Client Credentials Grant, “The OAuth 2.0 Authorization Framework”, RFC 6749, Internet Engineering Task Force (IETF),
https://www.rfc-editor.org/rfc/rfc6749#section-4.4

RFC 6838 - “Media Type Specifications and Registration Procedures”, RFC 6838, Internet Engineering Task Force (IETF),
https://www.rfc-editor.org/rfc/rfc6838

RFC 8259 - “The JavaScript Object Notation (JSON) Data Interchange Format”, RFC 8259, Internet Engineering Task Force (IETF),
https://www.rfc-editor.org/rfc/rfc8259

RFC 8259 Section 3 - Section 3. Values, “The JavaScript Object Notation (JSON) Data Interchange Format”, RFC 8259, Internet Engineering Task Force (IETF),
https://www.rfc-editor.org/rfc/rfc8259#section-3

RFC 8259 Section 4 - Section 4. Objects, “The JavaScript Object Notation (JSON) Data Interchange Format”, RFC 8259, Internet Engineering Task Force (IETF),
https://www.rfc-editor.org/rfc/rfc8259#section-4

RFC 8259 Section 5 - Section 5. Arrays, “The JavaScript Object Notation (JSON) Data Interchange Format”, RFC 8259, Internet Engineering Task Force (IETF),
https://www.rfc-editor.org/rfc/rfc8259#section-5

RFC 8259 Section 6 - Section 6. Numbers, “The JavaScript Object Notation (JSON) Data Interchange Format”, RFC 8259, Internet Engineering Task Force (IETF),
https://www.rfc-editor.org/rfc/rfc8259#section-6

RFC 8259 Section 7 - Section 7. Strings, “The JavaScript Object Notation (JSON) Data Interchange Format”, RFC 8259, Internet Engineering Task Force (IETF),
https://www.rfc-editor.org/rfc/rfc8259#section-7

RFC 9110 Section 4.2.2 - Section 4.2.2. https URI Scheme, “HTTP Semantics”, RFC 9110, Internet Engineering Task Force (IETF),
https://www.rfc-editor.org/rfc/rfc9110#section-4.2.2

RFC 9110 Section 9 - Section 9. Methods, “HTTP Semantics”, RFC 9110, Internet Engineering Task Force (IETF),
https://www.rfc-editor.org/rfc/rfc9110#section-9

RFC 9110 Section 15 - Section 15. Status Codes, “HTTP Semantics”, RFC 9110, Internet Engineering Task Force (IETF),
https://www.rfc-editor.org/rfc/rfc9110#section-15

RFC 9396 - “OAuth 2.0 Rich Authorization Requests”, RFC 9396, Internet Engineering Task Force (IETF),
https://www.rfc-editor.org/rfc/rfc9396

23. Acknowledgments

The authors would like to thank the late Shuli Goodman, who was the Executive Director of LFEnergy, for her incredible leadership in initially organizing the CDS.

24. Authors’ Addresses

Daniel Roesler
Daniel Roesler LLC
Email: daniel@danielroesler.com
URI: https://danielroesler.com/

Other Drafts