PowerHQ Plan Data API: Get Started With Your First Query

This guide walks you through everything you need to go from zero to live plan data. By the end you’ll have sent your first request to the API, retrieved the utility serving a ZIP code, and fetched real residential electricity plans complete with pricing tiers and an enrollment URL.

Get your credentials

You need one thing: an API key, a static secret you send on every request in the x-api-key HTTP header. It works from serverless functions, containers and CI just as well as from a fixed server.Contact your PowerHQ representative to receive your key. Want to run real queries before you have one? The playground needs no key at all.

Choose your environment

PowerHQ provides two identical endpoints. Use Certification while you build and test your integration, then point to Production when you go live.

Environment	Endpoint
Production	`https://eapi.prod.powerhq.co/graphql`
Certification (staging)	`https://eapi.cert.powerhq.co/graphql`

All code examples in this guide use the Certification endpoint. Swap the hostname when you’re ready for production traffic.

Send your first request

Start with a utilities query — it’s the simplest call and confirms your key is working. This example looks up the transmission and distribution utility (TDU) for ZIP code 75231 (Dallas, TX).

curl -s -X POST https://eapi.cert.powerhq.co/graphql \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ utilities(zipCode: \"75231\") { id name } }"}'

A successful response looks like this:

{
  "data": {
    "utilities": [
      {
        "id": "ONCOR",
        "name": "Oncor"
      }
    ]
  }
}

The id value (here "ONCOR") is the utilityId you’ll pass in subsequent plan queries for addresses in this service territory.

Fetch residential plans

Now query for residential plans. The example below requests plans for ZIP code 77002 (Houston, TX) sized for a customer using 1,000 kWh per month. It asks for the plan title, base price, contract term, rate type, supplier name, tiered rate details, and a ready-to-use enrollment URL.

{
  residentialPlans(zipCode: "77002", monthlyUsage: 1000) {
    title
    price
    term
    rateType
    supplier {
      name
    }
    rates {
      usageKwh
      allInRateUsdPerKwh
      avgMonthlyBillUsd
    }
    headlessEnrollmentUrl
  }
}

Send it with curl:

curl -s -X POST https://eapi.cert.powerhq.co/graphql \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ residentialPlans(zipCode: \"77002\", monthlyUsage: 1000) { title price term rateType supplier { name } rates { usageKwh allInRateUsdPerKwh avgMonthlyBillUsd } headlessEnrollmentUrl } }"
  }'

The response includes one or more plans. Here’s an example entry:

{
  "data": {
    "residentialPlans": [
      {
        "title": "12 Month (No Min Usage Fee)",
        "price": 0.138,
        "term": 12,
        "rateType": "FIXED",
        "supplier": { "name": "Constellation NewEnergy, Inc." },
        "rates": [
          { "usageKwh": 500,  "allInRateUsdPerKwh": 0.1428,  "avgMonthlyBillUsd": 71.4 },
          { "usageKwh": 1000, "allInRateUsdPerKwh": 0.1379,  "avgMonthlyBillUsd": 137.9 },
          { "usageKwh": 2000, "allInRateUsdPerKwh": 0.13545, "avgMonthlyBillUsd": 270.9 }
        ],
        "headlessEnrollmentUrl": "https://www.cert.powerhq.co/partner-app.html?utm_source=YOUR_PARTNER_CODE&utm_medium=referral&utm_campaign=partners#/redirect?ftype=RESIDENTIAL_PARTNER&plan_id=7a8c1d9f-f83a-4322-850f-c6939ccf4fb3&zip_code=77002&ref=YOUR_PARTNER_CODE"
      }
    ]
  }
}

The headlessEnrollmentUrl takes a customer directly into the enrollment flow for that plan. Replace YOUR_PARTNER_CODE with the partner code provided by your PowerHQ representative before surfacing these URLs to customers.

Next Steps

Authentication

How the x-api-key header works, why there is nothing else to configure, and how to handle 403 errors in production.

Reading Pricing

Understand the difference between price, allInRateUsdPerKwh, and avgMonthlyBillUsd, and when to display each.

Residential Plans Query

Full reference for every parameter and return field on the residentialPlans query.

All Queries

Browse the complete query reference — business plans, utilities, start dates, accounts, and more.

Integrate with PowerHQ

Plan Data API

Core Concepts

Queries

Playground

Reference

PowerHQ Plan Data API: Get Started With Your First Query

Next Steps

Authentication

Reading Pricing

Residential Plans Query

All Queries

​Next Steps

Authentication

Reading Pricing

Residential Plans Query

All Queries

Next Steps