> ## Documentation Index
> Fetch the complete documentation index at: https://docs.powerhq.co/llms.txt
> Use this file to discover all available pages before exploring further.

# PowerHQ Plan Data API: Get Started With Your First Query

> Make your first PowerHQ API call in minutes — fetch live utility data and real residential electricity plan pricing from a single GraphQL endpoint.

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.

<Steps>
  <Step title="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](/playground) needs no key at all.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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).

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="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.

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

    Send it with curl:

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    How the `x-api-key` header works, why there is nothing else to configure, and how to handle 403 errors in production.
  </Card>

  <Card title="Reading Pricing" icon="chart-line" href="/concepts/pricing">
    Understand the difference between `price`, `allInRateUsdPerKwh`, and `avgMonthlyBillUsd`, and when to display each.
  </Card>

  <Card title="Residential Plans Query" icon="house" href="/queries/residential-plans">
    Full reference for every parameter and return field on the `residentialPlans` query.
  </Card>

  <Card title="All Queries" icon="book" href="/queries/business-plans">
    Browse the complete query reference — business plans, utilities, start dates, accounts, and more.
  </Card>
</CardGroup>