API Access

Note: Your IP address(es) will need to be whitelisted and you will need API keys from us to access our API environment.

Playground: https://eapi.cert.energybot.xyz/graphql
Production: https://eapi.energybot.com/graphql

Integration

Customers can use any GraphQL client and can query the data in a manner that suits their use case.

API key can be specified as an HTTP header: x-api-key

‍

Schema

1schema {
2query: Query
3}
4type Query {
5"Get a list of business plans for the given zip code."
6businessPlans(annualUsageInkWh: Float, isMoveIn: Boolean, startDate: Date, zipCode: String!): [BusinessPlan!]
7"Get average residential energy rates and renewable/non-renewable electricity generation percentage, given state code"
8energyInfoByState(isBusiness: Boolean!, stateCode: String!): EnergyInfo
9"Get business plan next/minimum start date for the given zip code."
10nextStartDate(isMoveIn: Boolean, zipCode: String!): PlanNextStartDate!
11"Get a list of residential plans. If utility id/code is provided it will take precedence otherwise zip code will be resolved to default utility for that area."
12residentialPlans(utilityId: ID, zipCode: String): [ResidentialPlan!]!
13"Get utilities for a given zip code and associated data like pricing etc."
14utilities(zipCode: String!): [Utility!]
15"Search utility service accounts by account number and/or address."
16utilityAccounts(accountNumber: String, city: String, isBusiness: Boolean, state: String, street: String, street2: String, zipCode: String): [UtilityAccount!]
17"Forecast usage by address and property data."
18forecastedUsage(usageRequest: ForecastedUsageRequestInput!): ForecastedUsage
19}
20type ResidentialPlan {
21title: String!
22description: String!
23enrollmentUrl: String!
24headlessEnrollmentUrl: String!
25id: ID!
26price: Float!
27supplier: Supplier!
28term: Int!
29renewablePercentage: Int!
30}
31type Supplier {
32id: ID!
33logoUrl: String!
34name: String!
35}
36type Utility {
37id: ID!
38name: String!
39residentialPlans: [ResidentialPlan!]
40}
41type Address {
42street: String!
43street2: String
44city: String!
45state: String!
46zipCode: String!
47}
48type UtilityAccount {
49id: ID!
50accountNumber: String
51accountStatus: AccountStatus
52serviceAddress: Address!
53displayAddress: String
54isBusiness: Boolean!
55utilityCode: String!
56}
57type EnergyInfo {
58averagePrice: Float!
59electricityGenerationPercentage: ElectricityGenerationPercentage
60stateCode: String!
61stateName: String!
62}
63type ElectricityGenerationPercentage {
64nonRenewableGeneration: Int!
65renewableGeneration: Int!
66}
67enum AccountStatus {
68ACTIVE
69DE_ENERGIZED
70INACTIVE
71}
72type BusinessPlan {
73agreementUrl: String!
74enrollmentUrl: String!
75headlessEnrollmentUrl: String!
76id: ID!
77monthlyFee: Float!
78price: Float!
79supplier: Supplier!
80term: Int!
81renewablePercentage: Int!
82}
83type PlanNextStartDate {
84nextStartDate: Date!
85businessPlans: [BusinessPlan!]
86}
87enum EnergySource {
88ELECTRIC
89GAS
90UNKNOWN
91}
92enum PropertyType {
93APARTMENT
94COMMERCIAL
95CONDOMINIUM
96MOBILE_HOME
97MULTI_FAMILY_RESIDENCE
98SINGLE_FAMILY_RESIDENCE
99TOWNHOUSE
100UNKNOWN
101}
102input ElectricVehiclesInput {
103count: Int!
104vehicleProperties: [VehiclePropertiesInput!]
105}
106input EnergyUsageRequestInput {
107accountNumber: String!
108address: AddressInput!
109companyName: String
110firstName: String!
111lastName: String!
112loa: LetterOfAuthorizationInput!
113phoneNumber: String!
114residential: Boolean!
115utilityCode: String!
116}
117input ForecastedUsageRequestInput {
118address: AddressInput!
119electricVehicles: ElectricVehiclesInput!
120isBusiness: Boolean!
121propertyDetails: PropertyDetailsInput
122}
123input VehiclePropertiesInput {
124make: String!
125model: String!
126trim: String
127vin: String
128year: Int!
129}
130type ForecastedUsage {
131annualUsage: Int!
132monthlyUsage: [Usage!]!
133}
134"Type representing a YYYY-MM-DD formatted Date"
135scalar Date

Sample GraphQL query

Query for residential plans

monthlyUsage and priceType are optional parameters.

monthlyUsage - the price will be calculated based on the passed monthly usage. The default is 1000.

priceType - by default the prices are calculated using a “SEASONALIZED” price. That is, using the given average monthly usage, the returned price is the overall average price which accounts for seasonal variability in usage. A priceType of “FLAT” will return the plan price calculated using the exact monthlyUsage value.

{ residentialPlans(zipCode: "75035", monthlyUsage: 1000, priceType: "FLAT") { description price supplier { name } term } }

‍

Query for utilities in a zip code and residential plans associated with them

{ utilities(zipCode: "75035") { id name residentialPlans { id description } } }

‍

Query utilities and residential rate plans separately

{ utilities(zipCode: "75035") { id, name } residentialPlans(zipCode: "75035") { id, description } }

‍

Query for utility accounts based on account number

Note: accountNumber is required

{ utilityAccounts(accountNumber: "1008901024900370190109") { id isBusiness accountNumber utilityCode serviceAddress { street city state zipCode } accountStatus displayAddress } }

‍

Query for utility accounts based on address

Note: street field is required

{ utilityAccounts(street: "947 STREETLIGHT STLG 250HPS", city: "BROWNSVILLE", state: "TX", zipCode: "78521") { id isBusiness accountNumber utilityCode serviceAddress { street street2 city state zipCode } accountStatus displayAddress } }

‍

Query energy information for given state code

Note: stateCode and isBusiness params are required fields.
‍
Specify boolean value for isBusiness param in the query. The value true for business and false for residential.

{ energyInfoByState(stateCode: "TX", isBusiness: false) { averagePrice stateCode stateName electricityGenerationPercentage { renewableGeneration nonRenewableGeneration } } }

‍

Query for Business Plans for a given zip code

Note: zipCode is required.
‍
For new service, set isMoveIn as true. The default value is false (Switch).

annualUsageInkWh / startDate / isMoveIn params are optional.

API Error: If start date is before the next or minimum allowed start date.

{ businessPlans(zipCode: "75070", annualUsageInkWh: 23000, isMoveIn: true) { id term price monthlyFee supplier { id name logoUrl } enrollmentUrl headlessEnrollmentUrl agreementUrl } }

‍

Query for Plan’s next/minimum start date for a given zip code

Note: zipCode is required.
‍
For new service, set isMoveIn as true. The default value is false (Switch).

{ nextStartDate(zipCode: "75070", isMoveIn: false) { nextStartDate } }

‍

Optionally retrieve the corresponding Business Plans for a given zip code along with the next start date:

{ nextStartDate(zipCode: "75070", isMoveIn: true) { nextStartDate businessPlans { id term price monthlyFee supplier { id name logoUrl } enrollmentUrl headlessEnrollmentUrl agreementUrl } } }

‍

Query for Forecasted Usage by address and property data

Note: isBusiness is required.
‍
For home type, set isBusiness property to false. The default value is false (Home Type).

Note: address is required

Note: electricVehicles is required

{ forecastedUsage(usageRequest: { isBusiness: false, address: { street: "2326 Exeter Dr", city: "Dallas", state: "TX", zipCode: "75216" }, propertyDetails: { propertyType: TOWNHOUSE, livingSizeInSqft: 1260, poolAvailable: false, coolingSource: ELECTRIC, heatingSource: ELECTRIC }, electricVehicles: { count: 2, vehicleProperties: [ { make: "TESLA", model: "Y", year: 2021 }, { make: "BMW", model: "i3", year: 2022 } ] }, } ){ annualUsage, monthlyUsage { startDate, endDate, totalKwh } } }