> ## 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.

# Enrollment URLs, Partner Attribution, and Supplier Links

> Understand the two partner-stamped enrollment URLs on every plan and how attribution works so your conversions are tracked back to your account.

Every plan returned by the API includes two partner-stamped enrollment URLs you can hand customers off to when they're ready to sign up. Both URLs are pre-configured with your partner code so conversions attribute to your account automatically.

## Hosted enrollment (enrollmentUrl)

`enrollmentUrl` links to a full-page, PowerHQ-hosted enrollment flow. Use this when you want to redirect the customer to a standalone page managed entirely by PowerHQ. Your partner code is embedded in the URL as both the `utm_source` and `ref` query parameters, so every completed enrollment is attributed to you.

<Tip>
  The hosted flow is the fastest integration path. Drop the URL into a button or link and PowerHQ handles the rest — plan display, customer information collection, and supplier hand-off.
</Tip>

## Headless enrollment (headlessEnrollmentUrl)

`headlessEnrollmentUrl` provides an embeddable enrollment flow you can render inside your own UI — for example, inside an iframe or a modal. Like the hosted URL, it is already partner-stamped with your `utm_source` and `ref` values.

Use the headless URL when you want customers to complete enrollment without leaving your product's visual context.

**Example URL pattern:**

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

* `utm_source` and `ref` — your partner code for attribution
* `utm_campaign` — comes back as `partners`. Replace it with your own value to pass attribution
* `plan_id` — the unique plan identifier from the API
* `zip_code` — the customer's ZIP code passed through from your query

## Prefilling the enrollment

The URLs on a plan start the customer at the beginning of checkout. When you already know something about the customer, [`residentialEnrollmentUrl`](/queries/residential-enrollment-url) and [`businessEnrollmentUrl`](/queries/business-enrollment-url) build a link that carries it, so they do not type it twice.

Supply the customer's name and contact details through the `customer` argument, their consumption through `monthlyUsage` (residential) or `annualUsageInkWh` (business), and their service account through `utilityAccountNumber`. Each value you pass appears in the returned link and prefills the matching field at checkout.

### Prefilling the service address

The service address is attached through the customer's utility account, not through the address itself. It is a two-step flow.

<Steps>
  <Step title="Find the account">
    Query [`utilityAccounts`](/queries/utility-accounts) to resolve the customer's service account. Search by `accountNumber` when the customer can give you their ESID, which is the reliable path:

    ```graphql theme={null}
    { utilityAccounts(accountNumber: "1008901000158230011100") { accountNumber } }
    ```

    Searching by address works too, but the match is strict: `street` must be spelled the way the utility spelled it, unit included, and `street2` is compared exactly. Prefer the ESID whenever you can get one.
  </Step>

  <Step title="Pass the account number">
    Send the `accountNumber` from that result as the `utilityAccountNumber` argument on the enrollment URL query.
  </Step>

  <Step title="Check the returned link">
    The URL comes back carrying `prospect_id`, PowerHQ's identifier for that service account, and `state`. Their presence confirms the address is attached.
  </Step>
</Steps>

<Warning>
  Pass the `accountNumber`, not the account's `id`. `utilityAccounts` returns both, and sending the `v2-` prefixed `id` as `utilityAccountNumber` is accepted but attaches nothing — the link comes back without `prospect_id` and no error is raised. The `address` argument behaves the same way. Only `accountNumber` resolves.
</Warning>

## Supplier enrollment link

Some plans include a `LinkType.ENROLLMENT` entry inside the `documents[]` array. This entry points directly to the **supplier's own website** and is not a PowerHQ-hosted flow.

<Warning>
  The `documents[]` enrollment link is **not** guaranteed to be present on every plan. Do not rely on it as your primary enrollment path. Use `enrollmentUrl` or `headlessEnrollmentUrl` for a consistent, partner-attributed experience. The supplier link is best treated as a fallback or reference only.
</Warning>

## Attribution

Your partner code replaces the `YOUR_PARTNER_CODE` placeholder shown in the example URL above. The API returns URLs already stamped with your actual code, so attribution works without you doing anything.

To pass your own attribution, set `utm_campaign` on the returned link, the same way you do on a [Drop-in Storefront](/storefront) link. Whatever it holds when the customer converts appears in your daily conversion file and your monthly commission report. Leave the rest of the link as returned.

<Note>
  Before presenting any enrollment URL to a customer, make sure all applicable disclosure documents are visible. Customers must have access to plan disclosures before they enroll. See [Disclosure Documents](/concepts/disclosure-documents) for requirements.
</Note>