Skip to main content
POST
Refresh incentives

Authorizations

Authorization
string
header
required

Your Leap API key as a Bearer token. Send it in the Authorization header: Authorization: Bearer <api-key>.

Body

application/json
reference_id
string
required

Partner's stable identifier for the customer. Must match an existing customer scoped to the authenticated partner_id; unknown reference IDs return 404.

Required string length: 1 - 256
customer_details
object

Customer attributes to merge before re-evaluating, keyed by field name. Values are always strings. A key you send replaces what's on file, and a key you leave out is untouched. Use this to fill in facts as you learn them, rather than repeating a lookup.

An unrecognised key returns 400 and no incentives. The Requirements reference lists every key and its value form.

Omit or leave empty for no attribute changes. Maximum 100 entries.

customer_devices
object[]

Optional device merge set. An entry carrying a customer_device_id updates that installation in place; an entry without one adds a new installation. Installations already on file that you don't list are left untouched — sending a subset never deletes the rest.

Maximum array length: 50
remove_customer_device_ids
string<uuid>[]

Remove installations by customer_device_id. Ids that don't match a device on this customer are ignored, so retries are safe.

remove_device_references
string[]

Remove installations by partner_device_reference. Every installation with a matching reference is removed; unknown references are ignored.

eiaid
string

Optional utility override, matching the one on Look up incentives. Supply an EIA utility id to re-resolve the customer's serving utility instead of reusing the one on file. Leap re-selects candidate programs against it, re-runs eligibility, and keeps the override for later calls on this customer.

Minimum string length: 1
create_application
boolean
default:false

Create the Connect application records for this refresh's eligible programs, so the returned connect_url is a link the customer can open. It matches the flag on Look up incentives and defaults to false. Only a refresh that changes something has anything to create: one that supplies customer_devices, customer_details or a removal. A bare re-evaluation creates nothing, flag or no flag. No effect on billing or rate limits.

Response

Eligibility re-evaluated using the customer's stored state.

reference_id
string
required

Echoes the reference_id from the request — the partner's stable identifier for this customer.

customer_classification
enum<string>
required

The customer or site classification used to determine eligibility. RESIDENTIAL and COMMERCIAL are the long-standing values; MULTIFAMILY and MANUFACTURED_HOME exist because rebate qualification differs across single-family, multifamily, and manufactured housing.

Available options:
RESIDENTIAL,
MULTIFAMILY,
MANUFACTURED_HOME,
COMMERCIAL
customer_devices
object[]
required

Per-installation echo. One entry per request entry, with the resolved (server-filled if absent) partner_device_reference and the upserted customer_device.id.

incentive_summary
object
required
utilities
object
required
program_details
object[]
required

One entry per eligible (or conditionally eligible) program. Empty when no candidate programs match the (utility, customer_classification, device_category) filter.

connect_url
string<uri>

Deep link to hand the customer so they can apply: https://connect.incentives.leap.energy/{company}/refId/{reference_id}, where {company} is your registration nickname. Omitted entirely when the lookup surfaces no eligible incentive — there is nothing to apply for, so check that the field is present before showing a link.

geocoding
object
partner
object

Your brand name and logo as configured on your Leap account, so a surface rendering these results can show your branding without a second call.

devices_ignored
object[]

/incentives/lookups only. Entries the request named that were NOT written, because the request resolved to a customer that already exists and the entry named an installation that customer does not have. Absent or empty on every other outcome, and always absent for a customer created by this request. /incentives/lookups establishes a customer's device set. Adding to one that already exists is what /incentives/refreshes does — send the new installation there. The call still returns 200 and still evaluates the entries that WERE recognised, so a partner-side mistake never fails an otherwise-answerable eligibility request; the entries in this array are the ones that had no effect. Each entry echoes only what the caller sent. The customer's stored installations are never listed.