Skip to main content

Client agent enrollment

Client agent enrollment is an extension of the basic enrollment flow that lets you accept an electricity plan on a customer's behalf, using a limited power of attorney (POA). This is useful when you need to coordinate enrollment with an external event (like a hardware installation) rather than having the customer act at a specific moment.

When to use a client agent enrollment​

Two common scenarios where client agent enrollment improves the experience:

Hardware installation workflows​

For solar, battery, or EV charger installations, electricity service needs to start when hardware comes online. That happens after installation and permission to operate (PTO) is granted, which can be weeks or months after the customer signed up. Rather than contacting the customer again at that moment and asking them to enroll, you can collect their authorization upfront and activate service yourself when the installation is complete.

Streamlined logistics​

If your onboarding already collects everything needed (identity, payment, and the customer's agreement), adding a separate electricity enrollment step creates unnecessary friction. With client agent authorization, you can complete enrollment in the background as part of your existing workflow, without requiring the customer to take another action.

In both cases, the customer consents upfront and you act when the time is right.

Transparency and consent

Using client agent authorization requires explicit, informed consent from the customer. Before using this flow, customers must clearly understand:

  • That you will enroll them in an electricity plan on their behalf
  • Approximately when you will do so (e.g., "when your installation is complete")
  • What plan they will be enrolled in

You are responsible for obtaining a signed limited power of attorney agreement and retaining it. The client_agent_accepted and client_agent_accepted_at fields in the API are your attestation that you hold valid authorization.

How it differs from basic enrollment​

The client agent flow follows the basic enrollment steps with two differences:

  1. You record POA after creating the account. Call POST /v1/app/accounts/{account_uuid}/record-client-agent to register your authorization. This must happen before you call plans/accept on the customer's behalf, but it can otherwise be made at any point after account creation.

  2. You accept the plan, not the customer. When the service start date is known and approaching, you request plans and call plans/accept using the account token. The customer does not need to take any action at this point.

Everything else (identity verification, credit check, payment method, address) works exactly as described in the basic enrollment guide and can be completed in any order.

1. Create the account​

This step is the same as basic enrollment step 1. Include any customer information you already have (name, phone, date of birth) to prevent additional API calls and reduce what the customer needs to provide themselves.

2. Record power of attorney​

Call POST /v1/app/accounts/{account_uuid}/record-client-agent to record the customer's authorization. This must be done before you call plans/accept on the customer's behalf, but can otherwise happen at any point after account creation.

Fields:

FieldRequiredDescription
client_agent_accepted_atNoISO 8601 datetime when the customer granted authorization (e.g. "2026-03-01T14:30:00Z"). Defaults to now if omitted.
const response = await fetch(
  `https://api.light.dev/v1/app/accounts/${accountUuid}/record-client-agent`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.LIGHT_APP_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      client_agent_accepted_at: "2026-03-01T14:30:00Z",
    }),
  },
);

3. Complete prerequisites​

Follow basic enrollment steps 3–9 to collect the customer's address, verify their identity, run a credit check, and add a payment method. You can supply any of these upfront (at account creation or via the API) to reduce what the customer needs to provide themselves.

Once all prerequisites are satisfied the account moves to enrollment_pending_client_agent. Monitor progress by polling GET /v1/app/accounts/{account_uuid} or listening for webhooks.

4. Request plans and accept on the customer's behalf​

When the service start date is known and approaching (for example, when PTO is confirmed), request available plans and accept on the customer's behalf.

Timing​

Call plans/request 7 to 30 days before the intended start date. Priced plans expire after 5 business days if not accepted, so don't call this too far in advance.

Use POST /v1/app/accounts/{account_uuid}/enroll/plans/request to retrieve current plans:

const { plans } = await fetch(
  `https://api.light.dev/v1/app/accounts/${accountUuid}/enroll/plans/request`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.LIGHT_APP_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ esi_id: "55512345671234567" }),
  },
).then((r) => r.json());

Then accept the chosen plan using POST /v1/account/enroll/plans/accept with the account token. Make sure to pass the esi_id alongside the plan_uuid and service_start_date, as it's required to create the service location.

Service start date must be 7–30 days in the future

service_start_date must be sometime between 7–30 days from today. The 7-day minimum gives the customer time to opt out before service begins; the 30-day maximum keeps pricing current.

await fetch("https://api.light.dev/v1/account/enroll/plans/accept", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accountToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    plan_uuid: "d25c31d4-...",
    esi_id: "55512345671234567",
    service_start_date: "2026-04-01",
    terms_accepted: true,
  }),
});

After the plan is accepted, finalize the enrollment following basic enrollment step 10. Once finalized, the enrollment.plan_accepted and enrollment.finalized webhooks will fire.

As part of plan confirmation, a Letter of Authorization (LOA) is automatically generated and sent to the customer. This documents that you accepted the plan on their behalf and what they were enrolled in, and is part of fulfilling your transparency obligations to them.

Frozen credit​

If the customer's credit is frozen, the account moves to credit_check_frozen and the customer receives an email with a link to Experian's unfreeze portal. Once they unfreeze their credit, we automatically retry the check and the account returns to enrollment_pending_client_agent. No action needed on your end.

Webhooks let your application receive real-time notifications about status changes without polling. Learn more

enrollment.plan_accepted​

Triggered when a plan is accepted on the customer's behalf.

enrollment.finalized​

Triggered when enrollment finalization completes.

account.payment_method_added​

Triggered when the customer adds a payment method.

location.service_active​

Triggered when electricity service becomes active for the location.