Devices

Intro

A device is a battery, an EV charger, or a vehicle that takes part in a device program through the customer's plan. We enroll each device in its program. When we have a connection to the manufacturer, we also validate the device and keep its state in sync.

How a battery gets connected depends on who owns it. Each battery program is set up for one of two cases:

Program	Who connects the battery	What you build
Customer battery program	The customer, in a flow that we host and send.	Nothing. You can also show the flow in your app.
Partner battery program	You, with the App API.	One API call for each battery.

You always add EV chargers and vehicles with the App API.

Which program do my plans use?

We set this up when we add a device program to your plans. Ask our team if you are not sure which one applies.

Customer-connected batteries

Light-Hosted Flow

By default, we ask the customer to connect their battery. This happens automatically, with no implementation from your side. We send a link to our Light-Hosted Flow:

• In the email that we send after the customer enrolls.
• In reminder emails about 24 hours, 72 hours, and one week after service starts. We can delay these reminders for a program, for example to allow time for installation.
• In invoice emails, until a battery is connected.

In the flow, the customer selects their battery manufacturer and signs in to their manufacturer account. We then find the batteries on that account, enroll them in the program, and keep them in sync. We stop the reminders after a battery is connected.

Embedded Flow

To show the same flow in your app, for example right after enrollment, launch Embedded Flow with the connect-battery scope. You can also generate a Light-Hosted Flow link with this scope to send in your own messages. The flow is available only for accounts on a customer battery program.

Learn more about Embedded Flow

Add devices with the API

When you own or manage the device and the customer does not sign in to the manufacturer, add the device with the App API. For example, you installed the battery or you own the charger. We do not send connect-battery emails for partner battery programs. All device endpoints use AppToken authentication.

Before you add a device

The account must have accepted a plan that includes a device program for that device type:

Device	Program	When to add it
Battery	Battery	After the system receives permission to operate (PTO).
EV charger	EV charging	After the charger is installed.
Vehicle	EV charging	Any time after the plan is accepted.

The plan can be active or scheduled to start. If the account does not have a plan with the correct program, the request fails with a 409 status code. See the basic enrollment guide to accept a plan for an account.

Add a battery

Use POST /v1/app/accounts/{account_uuid}/devices/battery to add a battery to an account.

Fields:

Field	Required	Description
manufacturer	Yes	The battery manufacturer, for example tesla. The value is not case-sensitive.
identifier	Yes	The site or system ID from the manufacturer. The correct value is different for each manufacturer. The API reference gives the value for each one.
preliminary_capacity_kwh	Yes	The total capacity of all batteries at the location, in kWh. We use this value until we have an authorized connection to the battery.

Node.js

const battery = await fetch(
  `https://api.light.dev/v1/app/accounts/${accountUuid}/devices/battery`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.LIGHT_APP_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      manufacturer: "tesla",
      identifier: "429124",
      preliminary_capacity_kwh: "13.5",
    }),
  },
).then((r) => r.json());

Python

battery = requests.post(
    f"https://api.light.dev/v1/app/accounts/{account_uuid}/devices/battery",
    headers={
        "Authorization": f'Bearer {os.getenv("LIGHT_APP_TOKEN")}',
        "Content-Type": "application/json",
    },
    json={
        "manufacturer": "tesla",
        "identifier": "429124",
        "preliminary_capacity_kwh": "13.5",
    },
).json()

Add an EV charger

Use POST /v1/app/accounts/{account_uuid}/devices/charger to add an EV charger to an account. Send the charger manufacturer and the charger ID from the manufacturer:

{
  "manufacturer": "emporia",
  "identifier": "charger-001"
}

Add a vehicle

Use POST /v1/app/accounts/{account_uuid}/devices/vehicle to add a vehicle to an account. Send the vehicle manufacturer and the vehicle identification number (VIN):

{
  "manufacturer": "hyundai",
  "identifier": "KM8KRDDF3RU000001"
}

Device response

Each endpoint returns the new device:

Field	Description
uuid	The device ID.
account_uuid	The account that owns the device.
device_type	BATTERY, EVSE, or VEHICLE.
status	The device status. See Device statuses.
battery_details	The battery manufacturer, model, capacity, and settings. This field is null for other types.
charger_details	The charger manufacturer and model. This field is null for other types.
vehicle_details	The vehicle manufacturer and model. This field is null for other types.
program	The device program and its compliance status.

Device statuses

Status	Meaning	Action
active	The device works in its program, or we are connecting to it. We retry failed connections automatically.	None.
needs_attention	The device settings do not meet the program requirements, or we stopped syncing after repeated failures.	Check the device settings and its connection to the manufacturer.
inactive	The device is no longer in a program.	None.

Program compliance

The program object tells you if the device meets the program requirements. is_compliant is true when all requirements are met. compliance_checklist lists each requirement with the expected value and the actual value from the device. For a battery, the checks can include:

• The battery is online.
• The backup reserve is set to the program value.
• The battery can charge from the grid.
• The battery can export energy to the grid.

When a check fails, change the device setting to the expected value.

Errors

Status	When it happens
400	The request is not valid. For example, the manufacturer is not supported.
404	The account does not exist in your app.
409	The account does not have a plan with the correct device program.
409	The account already has a device of this type with the same identifier.
409	We cannot register the device.

The detail field in the response body tells you which 409 error occurred.