Home / Specifications / cdsc-wg3-01 - Customer Data / Overview
Customer Data - Overview
This is a summary overview of cdsc-wg3-01, which
describes how companies and technical users (“Clients”) can request access to customer data from
utilities and other centralized entities (“Servers”). This specification builds upon
cdsc-wg1-02, which allows Clients to register with
a Server and be granted access to request various scopes of data from that Server using the OAuth
protocol.
For example, this specification describes how an energy efficiency app can request access from a utility customer to see their account number, rate plan, and last year of energy usage.
Customer Data Scopes 🔗
cds_accounts_basiccds_accounts_contactscds_accounts_detailedcds_servicecontracts_basiccds_servicecontracts_supplierscds_servicecontracts_detailedcds_bill_amount_duecds_bill_statements_basiccds_bill_statements_detailedcds_bill_statements_filescds_bill_sections_basiccds_bill_sections_detailedcds_usage_basiccds_usage_detailed
Accounts Endpoint 🔗
==Request==
GET /api/accounts HTTP/1.1
Host: demoutility.com
==Response==
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"accounts": [
{
"cds_account_id": "111111111111-1",
"cds_created": "2024-01-01T00:00:00Z",
"cds_modified": "2024-01-01T00:00:00Z",
"cds_account_parent": null,
"account_number": "22222-222-22222",
"account_name": "Example Company",
"account_address": "123 Main St\nAnytown, TX 11111",
"account_type": "business",
"account_contacts": [
{
"type": "primary_phone",
"value": "+15555555555",
},
{
"type": "primary_email",
"value": "example.company@example.com",
},
...
],
},
...
],
"next": null,
"previous": null
}
Service Contract Endpoint 🔗
==Request==
GET /api/servicecontracts HTTP/1.1
Host: demoutility.com
==Response==
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"service_contracts": [
{
"cds_servicecontract_id": "3333333333-33",
"cds_created": "2024-01-01T00:00:00Z",
"cds_modified": "2024-01-01T00:00:00Z",
"cds_account_id": "111111111111-1",
"account_number": "22222-222-22222",
"contract_number": "333333-33-333333",
"contract_address": "123 Main St - PARKING LOT",
"contract_status": "active",
"contract_type": "distribution_and_supply",
"contract_entity": "Demo Utility",
"contract_start": "2024-01-01",
"contract_end": null,
"service_type": "electric",
"service_class": "commercial",
"rateplan_code": "COMM-1A",
"rateplan_name": "General Commerical 1A",
},
...
],
"next": null,
"previous": null
}
Service Point Endpoint 🔗
==Request==
GET /api/servicepoints HTTP/1.1
Host: demoutility.com
==Response==
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"service_points": [
{
"cds_servicepoint_id": "444444444-44",
"cds_created": "2024-01-01T00:00:00Z",
"cds_modified": "2024-01-01T00:00:00Z",
"servicepoint_type": "electric_meter",
"servicepoint_number": "P4444LOT",
"servicepoint_address": "123 Main St - PARKING LOT\nAnytown, TX 11111",
"latitude": null,
"longitude": null,
"current_servicecontracts": [
"3333333333-33",
],
"previous_servicecontracts": [],
"premise_number": "P4444",
"premise_type": "parking_lot",
},
...
],
"next": null,
"previous": null
}
Meter Device Endpoint 🔗
==Request==
GET /api/meterdevices HTTP/1.1
Host: demoutility.com
==Response==
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"meter_devices": [
{
"cds_meterdevice_id": "55555555-55",
"cds_created": "2024-01-01T00:00:00Z",
"cds_modified": "2024-01-01T00:00:00Z",
"meter_number": "M55555555",
"meter_type": "usage_forward_only",
"current_servicepoints": [
"444444444-44",
],
"previous_servicepoints": [],
},
...
],
"next": null,
"previous": null
}
Bill Statement Endpoint 🔗
==Request==
GET /api/billstatements HTTP/1.1
Host: demoutility.com
==Response==
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"bill_statements": [
{
"cds_billstatement_id": "66666666-66",
"cds_created": "2024-01-01T00:00:00Z",
"cds_modified": "2024-01-01T00:00:00Z",
"cds_account_id": "111111111111-1",
"account_number": "22222-222-22222",
"statement_date": "2024-01-01",
"currency": "USD",
"file_uri": "https://demoutility.com/api/rawfiles/66666666-66.pdf",
"file_mimetype": "application/pdf",
"previous_balance_amount": 10.00,
"previous_balance_paid": -10.00,
"previous_balance_unpaid": 0.00,
"new_charges_amount": 9.99,
"new_charges": [
{
"name": "Electric Charges",
"cost": 4.99,
},
{
"name": "Account Fixed Fee",
"cost": 5.00,
},
],
"new_balance_amount": 9.99,
"amount_due": 9.99,
"amount_due_date": "2024-02-01",
"shutoff_prevention_minimum_due": null,
"shutoff_prevention_date": null,
"program_participations": [
{
"program_type": "financial_program",
"program_id": "fixed_01",
"name": "Fixed-fee account",
},
],
},
...
],
"next": null,
"previous": null
}
Bill Section Endpoint 🔗
==Request==
GET /api/billsections HTTP/1.1
Host: demoutility.com
==Response==
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"bill_sections": [
{
"cds_billsection_id": "77777777-77",
"cds_created": "2024-01-01T00:00:00Z",
"cds_modified": "2024-01-01T00:00:00Z",
"cds_billstatement_id": "66666666-66",
"cds_account_id": "111111111111-1",
"account_number": "22222-222-22222",
"section_type": "distribution_and_supply_charges",
"start_date": "2023-12-01",
"end_date": "2023-12-31",
"currency": "USD",
"distribution_entity": {
"type": "distributor",
"entity": "Demo Utility",
"cds_servicecontract_id": "3333333333-33",
"contract_number": "333333-33-333333",
"rateplan_code": "COMM-1A",
"rateplan_name": "General Commerical 1A",
"program_participations": [
{
"program_type": "aggregated_demand_response",
"program_id": "adr_app01",
"name": "Acme Demand Response App",
},
],
},
"load_serving_entity": {
"type": "distributor",
},
"related_servicecontracts": [
"3333333333-33",
],
"related_servicepoints": [
"444444444-44",
],
"related_meterdevices": [
"55555555-55",
],
"related_billsections": [],
"line_items": [
{
"item_type": "charge",
"for": "distribution_entity",
"name": "Electric delivery",
"start": "2023-12-01T00:00:00Z",
"end": "2024-01-01T00:00:00Z",
"cost": 2.00,
"value": 50.0,
"rate": 0.0400,
"unit": "kwh",
},
{
"item_type": "subtotal",
"for": "distribution_entity",
"name": "Total delivery charges",
"cost": 2.00,
},
{
"item_type": "charge",
"for": "load_serving_entity",
"name": "Electric supply",
"start": "2023-12-01T00:00:00Z",
"end": "2024-01-01T00:00:00Z",
"cost": 2.00,
"value": 50.0,
"rate": 0.0400,
"unit": "kwh",
},
{
"item_type": "subtotal",
"for": "load_serving_entity",
"name": "Total supply charges",
"cost": 2.00,
},
{
"item_type": "charge",
"for": "other",
"name": "Local taxes",
"cost": 0.99,
},
{
"item_type": "subtotal",
"for": "other",
"name": "Total other charges",
"cost": 0.99,
},
{
"item_type": "total",
"for": null,
"name": "Total electric charges",
"start": "2023-12-01T00:00:00Z",
"end": "2024-01-01T00:00:00Z",
"cost": 2.00,
},
],
"energy_summary": [
{
"summary_type": "meter_reading",
"cds_meterdevice_id": "55555555-55",
"start": "2023-12-01T00:00:00Z",
"end": "2024-01-01T00:00:00Z",
"start_reading": 100000,
"end_reading": 100050,
"multiplier": 1,
"adjustment": 0,
"value": 50.0,
"unit": "kwh",
},
{
"summary_type": "usage_net",
"name": "Net Consumption",
"start": "2023-12-01T00:00:00Z",
"end": "2024-01-01T00:00:00Z",
"value": 50.0,
"unit": "kwh",
"tier_level": null,
"tou_bucket": null,
},
{
"summary_type": "usage_reverse",
"name": "Feed-in Generation",
"start": "2023-12-01T00:00:00Z",
"end": "2024-01-01T00:00:00Z",
"value": -1.0,
"unit": "kwh",
"tier_level": null,
"tou_bucket": null,
},
{
"summary_type": "usage_forward",
"name": "Total Consumption",
"start": "2023-12-01T00:00:00Z",
"end": "2024-01-01T00:00:00Z",
"value": 51.0,
"unit": "kwh",
"tier_level": null,
"tou_bucket": null,
},
{
"summary_type": "demand",
"name": "Commercial Peak Demand",
"start": "2023-12-01T00:00:00Z",
"end": "2024-01-01T00:00:00Z",
"value": 0.0,
"unit": "kw",
"tier_level": null,
"tou_bucket": null,
},
],
},
...
],
"next": null,
"previous": null
}
Aggregation Endpoint 🔗
==Request==
GET /api/aggregations HTTP/1.1
Host: demoutility.com
==Response==
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"aggregations": [
{
"cds_aggregation_id": "888888888-88",
"cds_created": "2024-01-01T00:00:00Z",
"cds_modified": "2024-01-01T00:00:00Z",
"aggregation_type": "building",
"aggregation_number": "B1111111",
"addresses": [
{
"full_address": "123 Main St\nAnytown, TX 11111",
},
],
"regions": [],
"needs_consent": false,
"consents_required": [],
},
...
],
"next": null,
"previous": null
}
Usage Segment Endpoint 🔗
==Request==
GET /api/usagesegments HTTP/1.1
Host: demoutility.com
==Response==
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"usage_segments": [
{
"cds_usagesegment_id": "99999999-99",
"cds_created": "2024-01-01T00:00:00Z",
"cds_modified": "2024-01-01T00:00:00Z",
"related_aggregations": [],
"related_accounts": [
"111111111111-1",
],
"related_servicecontracts": [
"3333333333-33",
],
"related_servicepoints": [
"444444444-44"
],
"related_meterdevices": [
"55555555-55",
]
"related_billsections": [],
"segment_start": "2023-12-01T00:00:00Z",
"segment_end": "2024-01-01T00:00:00Z",
"interval": 900,
"format": ["kwh_net", "kwh_fwd", "kwh_rev"],
"values": [
[{"v": 1.2}, {"v": 1.2}, {"v": 0.0}],
[{"v": 1.1}, {"v": 1.1}, {"v": 0.0}],
...
],
},
...
],
"next": null,
"previous": null
}
Energy Attribute Certificate Endpoint 🔗
==Request==
GET /api/eacs HTTP/1.1
Host: demoutility.com
==Response==
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"eacs": [
{
"cds_eac_id": "99999999-dk3",
"cds_created": "2024-01-01T00:00:00Z",
"cds_modified": "2024-01-01T00:00:00Z",
"eac_numbers": ["AAAZZZ-123"],
"eac_format": "energytag",
"eac_data_url": "https://example.com/energytagapi/v1/",
"beneficiary_type": "servicecontract",
"beneficiaries": ["3333333333-33"],
"period_start": "2024-01-01T00:00:00Z",
"period_end": "2024-02-01T00:00:00Z",
},
...
],
"next": null,
"previous": null
}
Examples for various situations 🔗
Meter usage with monthly readings (e.g. AMR meters) 🔗
Show example
GET /api/usagesegments
{
"usage_segments": [
{
"cds_usagesegment_id": "99999999-ab",
"cds_created": "2025-01-01T00:00:00Z",
"cds_modified": "2025-01-01T00:00:00Z",
"related_aggregations": [...],
"related_accounts": [...],
"related_servicecontracts": [...],
"related_servicepoints": [...],
"related_meterdevices": [...],
"related_billsections": [...],
"related_eacs": [...],
"segment_start": "2024-01-15T00:00:00Z",
"segment_end": "2024-02-15T00:00:00Z",
"interval": 2678400,
"format": ["kwh_fwd"],
"values": [
[
{"v": 500.0}
]
],
},
{
"cds_usagesegment_id": "99999999-z3",
"cds_created": "2025-01-01T00:00:00Z",
"cds_modified": "2025-01-01T00:00:00Z",
"related_aggregations": [],
"related_accounts": [...],
"related_servicecontracts": [...],
"related_servicepoints": [...],
"related_meterdevices": [...],
"related_billsections": [...],
"related_eacs": [...],
"segment_start": "2024-02-15T00:00:00Z",
"segment_end": "2024-03-15T00:00:00Z",
"interval": 2505600,
"format": ["kwh_fwd"],
"values": [
[
{"v": 450.0}
]
],
},
...
],
"next": null,
"previous": null
}
Meter usage with interval readings (e.g. AMI meters) 🔗
Show example
GET /api/usagesegments
{
"usage_segments": [
{
"cds_usagesegment_id": "99999999-3c",
"cds_created": "2025-01-01T00:00:00Z",
"cds_modified": "2025-01-01T00:00:00Z",
"related_aggregations": [...],
"related_accounts": [...],
"related_servicecontracts": [...],
"related_servicepoints": [...],
"related_meterdevices": [...],
"related_billsections": [...],
"related_eacs": [...],
"segment_start": "2024-01-15T00:00:00Z",
"segment_end": "2024-02-15T00:00:00Z",
"interval": 900,
"format": ["kwh_fwd"],
"values": [
[
{"v": 1.24}
],
[
{"v": 1.01}
],
... # 2,976 entries total (one for each 15-minute segment)
],
},
...
],
"next": null,
"previous": null
}
Net meter usage (e.g. AMI meter + distributed generation) 🔗
Show example
GET /api/usagesegments
{
"usage_segments": [
{
"cds_usagesegment_id": "99999999-349",
"cds_created": "2025-01-01T00:00:00Z",
"cds_modified": "2025-01-01T00:00:00Z",
"related_aggregations": [...],
"related_accounts": [...],
"related_servicecontracts": [...],
"related_servicepoints": [...],
"related_meterdevices": [...],
"related_billsections": [...],
"related_eacs": [...],
"segment_start": "2024-01-15T00:00:00Z",
"segment_end": "2024-02-15T00:00:00Z",
"interval": 3600,
"format": ["kwh_net", "kwh_fwd", "kwh_rev"],
"values": [
[
{"v": 1.50},
{"v": 2.00},
{"v": -0.50}
],
[
{"v": 1.00},
{"v": 2.00},
{"v": -1.00}
],
... # 744 entries total (one for each 1-hour segment)
],
},
...
],
"next": null,
"previous": null
}
Interval meter with interval-level supply mix 🔗
Show example
GET /api/usagesegments
{
"usage_segments": [
{
"cds_usagesegment_id": "99999999-349",
"cds_created": "2025-01-01T00:00:00Z",
"cds_modified": "2025-01-01T00:00:00Z",
"related_aggregations": [...],
"related_accounts": [...],
"related_servicecontracts": [...],
"related_servicepoints": [...],
"related_meterdevices": [...],
"related_billsections": [...],
"related_eacs": [...],
"segment_start": "2024-01-15T00:00:00Z",
"segment_end": "2024-02-15T00:00:00Z",
"interval": 3600,
"format": ["kwh_fwd", "supply_mix"],
"values": [
[
{"v": 2.00},
[
{"type": "solar", "mix": 0.5},
{"type": "wind", "mix": 0.5}
]
],
[
{"v": 1.50},
[
{"type": "solar", "mix": 0.5},
{"type": "wind", "mix": 0.5}
]
],
... # 744 entries total (one for each 1-hour segment)
],
},
...
],
"next": null,
"previous": null
}
Interval meter with monthly supply mix 🔗
Show example
GET /api/usagesegments
{
"usage_segments": [
{
"cds_usagesegment_id": "99999999-3c",
"cds_created": "2025-01-01T00:00:00Z",
"cds_modified": "2025-01-01T00:00:00Z",
"related_aggregations": [...],
"related_accounts": [...],
"related_servicecontracts": [...],
"related_servicepoints": [...],
"related_meterdevices": [...],
"related_billsections": [...],
"related_eacs": [...],
"segment_start": "2024-01-15T00:00:00Z",
"segment_end": "2024-02-15T00:00:00Z",
"interval": 3600,
"format": ["kwh_fwd"],
"values": [
[
{"v": 1.24}
],
[
{"v": 1.01}
],
... # 744 entries total (one for each 1-hour segment)
],
},
{
"cds_usagesegment_id": "99999999-x5z",
"cds_created": "2025-01-01T00:00:00Z",
"cds_modified": "2025-01-01T00:00:00Z",
"related_aggregations": [...],
"related_accounts": [...],
"related_servicecontracts": [...],
"related_servicepoints": [...],
"related_meterdevices": [...],
"related_billsections": [...],
"related_eacs": [...],
"segment_start": "2024-01-15T00:00:00Z",
"segment_end": "2024-02-15T00:00:00Z",
"interval": 2678400,
"format": ["supply_mix"],
"values": [
[
[
{"type": "solar", "mix": 0.25},
{"type": "wind", "mix": 0.5},
{"type": "other", "mix": 0.25},
]
]
],
},
...
],
"next": null,
"previous": null
}
Interval meter with monthly EAC 🔗
Show example
GET /api/usagesegments
{
"usage_segments": [
{
"cds_usagesegment_id": "99999999-6j",
"cds_created": "2025-01-01T00:00:00Z",
"cds_modified": "2025-01-01T00:00:00Z",
"related_aggregations": [...],
"related_accounts": [...],
"related_servicecontracts": [...],
"related_servicepoints": [...],
"related_meterdevices": [...],
"related_billsections": [...],
"related_eacs": [...],
"segment_start": "2024-01-15T00:00:00Z",
"segment_end": "2024-02-15T00:00:00Z",
"interval": 3600,
"format": ["kwh_fwd"],
"values": [
[
{"v": 1.24}
],
[
{"v": 1.01}
],
... # 744 entries total (one for each 1-hour segment)
],
},
{
"cds_usagesegment_id": "99999999-vc3",
"cds_created": "2025-01-01T00:00:00Z",
"cds_modified": "2025-01-01T00:00:00Z",
"related_aggregations": [...],
"related_accounts": [...],
"related_servicecontracts": [...],
"related_servicepoints": [...],
"related_meterdevices": [...],
"related_billsections": [...],
"segment_start": "2024-01-01T00:00:00Z",
"segment_end": "2024-02-01T00:00:00Z",
"interval": 2678400,
"format": ["eac_kwh"],
"values": [
[
{"eac": "99999999-dk3", "nums": ["AAAZZZ-123"], "v": 580.0}
]
],
},
...
],
"next": null,
"previous": null
}
GET /api/eacs
{
"eacs": [
{
"cds_eac_id": "99999999-dk3",
"cds_created": "2024-01-01T00:00:00Z",
"cds_modified": "2024-01-01T00:00:00Z",
"eac_numbers": ["AAAZZZ-123"],
"eac_format": "energytag",
"eac_data_url": "https://example.com/energytagapi/v1/", # contains the full EAC details
"beneficiary_type": "servicecontract",
"beneficiaries": ["3333333333-33"],
"period_start": "2024-01-01T00:00:00Z",
"period_end": "2024-02-01T00:00:00Z",
},
...
],
"next": null,
"previous": null
}