Skip to main content
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.
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.

​
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:
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 and businessEnrollmentUrl 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.
1

Find the account

Query utilityAccounts to resolve the customer’s service account. Search by accountNumber when the customer can give you their ESID, which is the reliable path:
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.
2

Pass the account number

Send the accountNumber from that result as the utilityAccountNumber argument on the enrollment URL query.
3

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

​
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 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.
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 for requirements.