> ## Documentation Index > Fetch the complete documentation index at: https://docs.incentives.leap.energy/llms.txt > Use this file to discover all available pages before exploring further. # Refresh incentives > Re-run eligibility for a customer you've already looked up, using their stored address and devices — no need to resend them. Use this to pick up newly launched programs or updated incentive amounts. ## OpenAPI ````yaml /api-reference/specs/gcs-incentives.json post /beta/incentives/refreshes openapi: 3.0.1 info: title: Leap Incentives — Lookups description: > Check which rebate programs a customer qualifies for, and keep that answer current as their situation changes. Three operations share one request shape: * `POST /beta/incentives/lookups` is the first call for a customer. It stores the customer and their devices, resolves the serving utility from the address, and evaluates eligibility. * `POST /beta/incentives/refreshes` re-evaluates a customer you have already looked up, against their stored address and devices. Send it to pick up newly launched programs and updated amounts, or to add, update, or remove individual devices. * `POST /beta/incentives/overrides` rebuilds an existing customer from a fresh request body: it re-resolves the address and serving utility, replaces the device set, and clears the customer attributes you previously supplied. Use it to correct a customer record before any application is submitted. Authenticate every call with your Leap API key as a bearer token. Your account is identified by that key, so the customers, devices, and applications you read and write are always your own. contact: email: apiteam@leap.energy version: '0.1' servers: - url: https://api.leap.energy description: Production - url: https://api.staging.leap.energy description: Staging security: - BearerAuth: [] tags: - name: incentives-lookups paths: /beta/incentives/refreshes: post: tags: - incentives-lookups summary: Refresh incentives description: >- Re-run eligibility for a customer you've already looked up, using their stored address and devices — no need to resend them. Use this to pick up newly launched programs or updated incentive amounts. operationId: refreshIncentives requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RefreshIncentivesRequest' responses: '200': description: Eligibility re-evaluated using the customer's stored state. content: application/json: schema: $ref: '#/components/schemas/EligibilityResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalServerError' components: schemas: RefreshIncentivesRequest: type: object required: - reference_id properties: reference_id: type: string minLength: 1 maxLength: 256 description: > Partner's stable identifier for the customer. Must match an existing customer scoped to the authenticated `partner_id`; unknown reference IDs return 404. customer_details: type: object description: >- 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](/setup-data-preferences) lists every key and its value form. Omit or leave empty for no attribute changes. Maximum 100 entries. maxProperties: 100 additionalProperties: type: string customer_devices: type: array maxItems: 50 description: >- 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. items: $ref: '#/components/schemas/CustomerDeviceRef' remove_customer_device_ids: type: array description: >- Remove installations by `customer_device_id`. Ids that don't match a device on this customer are ignored, so retries are safe. items: type: string format: uuid remove_device_references: type: array description: >- Remove installations by `partner_device_reference`. Every installation with a matching reference is removed; unknown references are ignored. items: type: string eiaid: type: string minLength: 1 description: >- 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. create_application: type: boolean default: false description: >- 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. EligibilityResult: type: object required: - reference_id - customer_classification - customer_devices - incentive_summary - utilities - program_details properties: reference_id: type: string description: >- Echoes the `reference_id` from the request — the partner's stable identifier for this customer. customer_classification: $ref: '#/components/schemas/CustomerClassification' customer_devices: type: array description: > Per-installation echo. One entry per request entry, with the resolved (server-filled if absent) `partner_device_reference` and the upserted `customer_device.id`. items: $ref: '#/components/schemas/CustomerDeviceRefEcho' connect_url: type: string format: uri description: >- 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. incentive_summary: $ref: '#/components/schemas/IncentiveSummary' utilities: $ref: '#/components/schemas/UtilityMatch' program_details: type: array description: >- One entry per eligible (or conditionally eligible) program. Empty when no candidate programs match the (utility, customer_classification, device_category) filter. items: $ref: '#/components/schemas/EligibleProgram' geocoding: $ref: '#/components/schemas/Geocoding' partner: $ref: '#/components/schemas/PartnerBranding' devices_ignored: type: array description: > `/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. items: $ref: '#/components/schemas/IgnoredCustomerDevice' CustomerDeviceRef: type: object description: >- One installation. New installations name their catalog device with `device_id`. On **Refresh incentives**, `customer_device_id` instead targets an installation already on file, for an in-place update. properties: device_id: type: string format: uuid description: >- The catalog device's `id`, from **Search device catalog** or the portal's Device profile mapping. Required on a new installation. Optional when `customer_device_id` targets an installation already on file, and must match that installation's catalog device when you do send it. A `device_id` that is not in the catalog is rejected with 422 `INVALID_DEVICE_ID`. customer_device_id: type: string format: uuid description: >- Identifies one installation — this customer, this catalog device, your device reference. Leap assigns it on the first lookup and echoes it back in `customer_devices[]`; it is stable across later lookups and refreshes, and is regenerated only by **Override incentives**, which replaces the device set. Send it on **Refresh incentives** to update that installation in place; it is rejected with 400 on lookups and overrides. partner_device_reference: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z0-9_-]+$ description: > Partner-supplied per-installation identifier. Unique within the request. Echoed back in the response so partners can join their local records to the upserted `customer_device`. Supplying it makes it the installation's identity: the entry addresses the stored installation holding that reference for that `device_id`, and nothing else. Omitting it is supported and stable. The server matches the entry against the installations already on file for the customer by `device_id`, so reordering the array or sending a subset resolves to the same installations as before. It assigns `"1"`, `"2"`, ... (skipping any value already in use) only when it actually creates a new installation. Two entries for the same `device_id` with no reference are only accepted when the customer has no installation of that device yet; otherwise nothing but array position tells them apart, and the request is rejected with 400 `INVALID_REQUEST` asking for an explicit reference. details: type: object description: >- Attributes for this one installation, keyed by field name, for example `{"customer_device.purchase_price": "699.00"}`. Values are always strings. Facts about the customer go in the request's `customer_details` object instead. An unrecognised key returns 400 and no incentives. The [Requirements reference](/setup-data-preferences) lists every key and its value form. Maximum 50 entries. maxProperties: 50 additionalProperties: type: string CustomerClassification: description: >- 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. type: string enum: - RESIDENTIAL - MULTIFAMILY - MANUFACTURED_HOME - COMMERCIAL CustomerDeviceRefEcho: type: object required: - device_id - partner_device_reference - customer_device_id properties: device_id: type: string format: uuid description: The catalog `device.id` resolved for this installation. partner_device_reference: type: string description: > Server-resolved value (echoed verbatim if the partner supplied one; assigned `"1"`, `"2"`, ... otherwise). customer_device_id: type: string format: uuid description: >- Leap's identifier for this installation. Store it — it's how you address that specific device on later calls. IncentiveSummary: type: object required: - upfront_amount - install_amount - ongoing_amount properties: upfront_amount: type: number description: >- Reserved for a payment kind Leap does not pay yet, so it is always 0. Read `install_amount` for the one-time total. install_amount: type: number description: >- Total one-time incentives across all eligible programs, paid at install time. ongoing_amount: type: number description: >- Total recurring incentives across all eligible programs, **per year**. UtilityMatch: type: object required: - primary - possible_utilities properties: primary: description: > The utility resolved as serving this address — the one whose programs drive the eligibility result. allOf: - $ref: '#/components/schemas/IncentiveUtility' possible_utilities: type: array description: > Every utility whose service territory covers this address (including `primary`); more than one can appear where territories overlap. items: $ref: '#/components/schemas/IncentiveUtility' EligibleProgram: type: object required: - name - upfront_amount - install_amount - ongoing_amount - tiers properties: name: type: string description: >- Program name as shown to the customer. Leap sets this for utility, state, and market programs; for your own partner offer it is the offer name you configure in the portal. operator_name: type: string nullable: true description: >- The utility or agency that operates the program, as shown to the customer. On your own partner offer it is the operator name you configure in the portal. Null when Leap holds no display name for the program. device_category: type: string nullable: true description: Category name (e.g., `EV_CHARGER`, `HEAT_PUMP`). upfront_amount: type: number description: >- Reserved for a payment kind Leap does not pay yet, so it is always 0. Read `install_amount` for this program's one-time incentive. install_amount: type: number description: This program's one-time incentive, paid at install time. ongoing_amount: type: number description: This program's recurring incentive, **per year**. display_name: type: string nullable: true description: >- Partner offers only: the branded offer name shown to the customer, as configured in the portal. Null for rebate programs. logo_url: type: string nullable: true description: >- Partner offers only: URL to the logo shown alongside the offer, as configured in the portal. Null for rebate programs. terms_url: type: string nullable: true description: >- Partner offers only: URL to the offer's terms and conditions, as configured in the portal. Null for rebate programs. description: type: string nullable: true description: >- Partner offers only: the offer description shown to the customer, as configured in the portal. Null for rebate programs. is_partner_offer: type: boolean nullable: true description: >- `true` when this entry is your own partner offer (which bundles one or more underlying programs); `false` for utility, state, and market rebate programs. Use it to separate your offer from rebates in your own UI. covered_programs: type: array description: >- Partner offers only: the rebate programs bundled into this offer that the customer qualified for, and whose value is summed into this entry's amounts. Empty for every other kind of entry. items: $ref: '#/components/schemas/CoveredProgram' program_identifier: type: string nullable: true description: >- Stable identifier for this program — your offer's identifier for a partner offer, or the catalog identifier (for example `PGE-ART`) otherwise. Use it to correlate the same program across lookups. included_leap_program_ids: type: array items: type: string description: >- Partner offers only: identifiers of the underlying programs this offer covers for this customer. Empty for every other kind of entry. tiers: type: array description: > The program's incentive tiers evaluated for this customer. Each tier carries its payment type, total amount, and per-device results. items: $ref: '#/components/schemas/MatchedTier' Geocoding: type: object required: - latitude - longitude - formatted_address properties: latitude: type: number format: double description: Latitude of the geocoded address, in decimal degrees. longitude: type: number format: double description: Longitude of the geocoded address, in decimal degrees. formatted_address: type: string description: The address as normalized by the geocoder. PartnerBranding: type: object description: >- 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. required: - name properties: name: type: string description: The partner's external brand name (identity `Account.name`). logo_url: type: string format: uri nullable: true description: >- URL to your logo, as configured on your Leap account. Null when no logo is configured. IgnoredCustomerDevice: type: object required: - device_id - reason properties: device_id: type: string format: uuid description: The catalog `device.id` the skipped entry named. partner_device_reference: type: string nullable: true description: > The `partner_device_reference` the caller supplied on this entry, or null when the entry omitted it. Never a server-generated value — nothing was written, so no reference was assigned. reason: type: string enum: - NOT_ON_EXISTING_CUSTOMER description: > `NOT_ON_EXISTING_CUSTOMER`: the request resolved to a customer that already exists, and this entry named an installation that customer does not have. ErrorResponse: type: object required: - error properties: error: type: object required: - message properties: message: type: string details: type: array items: type: object properties: error_code: type: string description: >- Stable wire code from `IncentivesErrorCode` (e.g., `INVALID_DEVICE_ID`, `GEOCODING_NO_RESULTS`, `NO_UTILITY_AT_ADDRESS`, `ADDRESS_OWNED_BY_ANOTHER_CUSTOMER`, `INCLUDE_PREVIEW_NOT_SUPPORTED`, `CONNECT_APPLICATIONS_IN_FLIGHT`, `CONNECT_CUSTOMER_SHARED`, `CONNECT_REFERENCE_ID_TAKEN`, `CONNECT_RESET_REFUSED`, `CONNECT_RESET_UNAVAILABLE`, `CONNECT_RESET_FAILED`, `CONNECT_RESET_REJECTED`, `CONNECT_RESET_REFUSED_AFTER_REBUILD`, `CONNECT_REFERENCE_ID_TAKEN_AFTER_REBUILD`, `CONNECT_RESET_WOULD_STRAND_CUSTOMER`). reason: type: string description: >- Human-readable explanation. Safe to surface to partners; no internal identifiers. IncentiveUtility: description: > EIA-keyed utility identity used in incentive eligibility responses. Distinct from `common-schemas.yaml#/components/schemas/Utility`, which carries Connect's UUID-based shape with logo + connection URL. type: object required: - eiaid - name properties: eiaid: type: string description: EIA utility identifier. name: type: string description: Human-readable utility name. state: type: string nullable: true description: Two-letter US state abbreviation. CoveredProgram: type: object required: - identifier - name properties: identifier: type: string description: >- Identifier of the bundled program. Use it to tell the covered programs apart across lookups; it is not a value any other endpoint accepts. name: type: string description: Human-readable label for the wrapped program (`program.label`). MatchedTier: type: object required: - tier_id - payment_type - incentive_amount - device_results properties: tier_id: type: string description: > Stable tier identifier: the spec tier id for non-offer programs, or the offer spec's payment-leg tier id for Partner Offer rows. Always present. Prefer `tier_name` for display when it is present; this field is stable across relabeling and safe to use as a join key. tier_name: type: string description: > Customer-facing display name for the tier, when one exists. Non-offer programs surface the spec tier's `label` when the author set one; absent when the tier has no authored label — this field never falls back to `tier_id`. Partner Offer legs always populate this — "Enrollment Incentive" (up-front leg) / "Participation Incentive" (recurring leg). Partner Offers emit one tier per payment leg. payment_type: $ref: '#/components/schemas/PaymentType' incentive_amount: type: number description: >- Tier total across the devices that passed this tier's requirements; per-device outcomes are in `device_results[]`. Units follow `payment_type`: `UPFRONT` and `INSTALL` amounts are one-time, `ONGOING` amounts are per year. device_results: type: array description: > One entry per `customer_device` evaluated for this tier. Each shows whether that install passed/failed/ignored the tier's requirements and the per-check details. items: $ref: '#/components/schemas/DeviceTierResult' PaymentType: type: string enum: - UPFRONT - INSTALL - ONGOING DeviceTierResult: type: object required: - partner_device_reference - customer_device_id - status - eligibility_details properties: partner_device_reference: type: string description: > Echoes the `partner_device_reference` from the request's `customer_devices[]` entry. customer_device_id: type: string format: uuid description: >- The `customer_device.id` of the installation evaluated in this result. status: type: string description: Per-device tier outcome (`COMPLETED`, `FAILED`, `IGNORED`). eligibility_details: type: array description: > Per-requirement check results behind this device's tier `status` — one entry per eligibility rule evaluated. items: $ref: '#/components/schemas/EligibilityCheck' EligibilityCheck: type: object required: - requirement - status - code - reason properties: requirement: type: string description: Human-readable requirement label. status: type: string description: Engine outcome (e.g., `COMPLETED`, `FAILED`, `IGNORED`). code: type: string description: > Categorical requirement-type code. Says what KIND of requirement this is, not which individual check produced it. The vocabulary is `UTIL-*` (utility relationship), `EQUIP-*` (equipment identity, rating and condition), `CONT-*` (contractor, permit and inspection), `VEH-*` (vehicle), `CUST-*` (who the customer is and what they live in), `APP-*` (application timing and signatures) and `MISC`. Prefixes are stable and matchable, so `code.startsWith("EQUIP-")` is a supported way to group. `APP-002` is defined by the axis "this requires a signature or declaration from the customer", regardless of subject matter — a terms-and-conditions acceptance, a one-rebate-per-address attestation and a trade-ally confirmation are all `APP-002`. THE SAME CODE CAN APPEAR ON SEVERAL CHECKS IN ONE RESPONSE. Twenty distinct agreement checks all carry `APP-002`, and a program can require more than one of them, so a single card can show several `APP-002` rows that the customer must each act on. Do not treat `code` as a key: group or de-duplicate by it deliberately, and use `requirement` to tell two rows of the same code apart. Codes are additive and stable: an existing code is never renumbered or repurposed, and new kinds arrive as new codes. A check whose kind has not been categorised yet reports `MISC`. reason: type: string description: Human-readable explanation of the outcome. source_program_identifier: type: string nullable: true description: >- On a partner offer, the program this check came from — your offer's identifier for checks on the offer itself, or the identifier of an underlying program for checks it inherits. Null on rebate programs. expected_values: type: array nullable: true description: > The values on the far side of the comparison, in the same display spelling as `reason`. Read with `operator`: for `eq`/`in` these are the values the program accepts, for `neq`/`not_in` the values it rejects, and for `gt`/`gte`/`lt`/`lte`/`between` the bounds. Casing permutations a spec enumerates are collapsed, so a spec listing `LEVEL_2`, `LEVEL 2` and `level_2` yields one entry. Null on checks that compare nothing, and on `present`/`absent`. items: type: string actual_value: type: string nullable: true description: > The customer's value, in the same display spelling as `reason`. Null when the customer has no value on file, and on checks that compare nothing. operator: type: string nullable: true description: > The comparison applied: `eq`, `neq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between`, `present`, `absent`. Null on checks that compare nothing. severity: type: string nullable: true description: > What this check means for the application, derived from `status`: `met` (COMPLETED), `pending` (IGNORED — the customer still has to supply or agree to something) or `blocking` (FAILED). Null when the status is not one of those three. responses: BadRequest: description: Malformed or invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: You are not authenticated content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: You do not have permission to perform this operation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: >- Address is not covered by any utility we have territory data for. This is a coverage gap, not an internal failure — the caller should not retry. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' UnprocessableEntity: description: >- Request was syntactically valid but could not be processed (e.g., unknown device id, address could not be geocoded) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' RateLimited: description: > The shared per-partner rate limit for /incentives endpoints was exceeded (`error_code: RATE_LIMIT_EXCEEDED`). Back off and retry after the number of seconds indicated by the `Retry-After` header. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalServerError: description: An internal server error occurred content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: BearerAuth: type: http scheme: bearer description: >- Your Leap API key as a Bearer token. Send it in the `Authorization` header: `Authorization: Bearer `. ````