Skip to main content

Location management

Once a consumer has enrolled and their service is active, you can use the Location endpoints to manage various aspects of their service location. This guide will walk you through common location-related tasks.

Retrieving plan documents​

After enrollment, you will need to provide the consumer with important documents related to their service. These documents include the Electricity Facts Label (EFL), Terms of Service (TOS), and Your Rights as a Customer (YRAC).

note

These documents are also included in the /account/enroll/plans/request response payload when the customer is enrolling in a plan.

GET /account/locations/{location_uuid}/documents​

Example response payload​

{
  "efl": "https://example.com/efl.pdf",
  "tos": "https://example.com/tos.pdf",
  "yrac": "https://example.com/yrac.pdf"
}

These document links can be displayed to the user and used to download the documents for their records.

Getting support information​

To provide customers with the necessary support information, you can retrieve support details from the API. This includes details about their Transmission & Distribution Utility (TDU).

note

The TDU is the company that owns and operates the poles and wires that deliver electricity to the customer's location. The TDU is responsible for maintaining the infrastructure and restoring service in case of outages.

GET /account/locations/{location_uuid}/support-info​

Example response payload​

{
  "tdu_name": "CenterPoint Energy",
  "tdu_phone": "800-555-5555"
}

This information can be used to display the TDU's contact details to the customer in the case of outages or other service-related issues.

Retrieving usage data​

To help customers understand their energy consumption, you can retrieve their historical usage data. This data is typically provided as meter reads over specific periods.

note

Meter reads are performed roughly on a monthly basis, however the exact frequency may vary depending on a number of factors.

GET /account/locations/{location_uuid}/usage/meter-reads​

Example response payload​

[
  {
    period_start: "2023-05-01",
    period_end: "2023-05-31",
    total_kwh: "500.0",
  },
  {
    period_start: "2023-04-01",
    period_end: "2023-04-30",
    total_kwh: "450.0",
  },
  // ... more usage periods
];

This data can be used to create usage graphs or provide consumption information to the customer. If you need more detailed usage data, contact us to learn about options for retrieving more granular usage data.

Cancelling service​

If a customer needs to cancel their service, you can use the cancel service endpoint. This allows you to schedule the cancellation for a future date. Note that cancelling service only needs to be done if a customer is leaving their address, but not if they are switching just switching to a different provider.

POST /account/locations/{location_uuid}/cancel-service​

Example request payload​

{
  "final_service_date": "2023-06-30",
  "reason": "Moving out of state"
}

Example response​

A successful cancellation request will return a 200 OK status.

Remember that the final_service_date must be within 30 days of the current date, and the reason field is optional but can be helpful for record-keeping.