Check Incentives

Overview

Calculate incentives across multiple utility programs for a customer address and device. This endpoint automatically handles customer creation, utility lookup, and incentive aggregation. Use lookup for first-time customers (requires full address) or refresh for returning customers (faster, uses cached data).

The reference_id is required and must be unique. It enables faster lookups on subsequent calls.

Performance Tip: Use operation_type="refresh" for returning customers to skip geocoding and use cached utility data. This is significantly faster than lookup operations.

For more details on operation types, organization scoping, and best practices, see the API Guide.

Authorizations

x-api-key

string

header

required

API key for authentication. Include your Leap API key in the x-api-key header: x-api-key: leap_live_...

Body

application/json

Customer address, building type, and device information for incentive calculation

operation_type

enum<string>

required

Operation type: 'lookup' for new calculations with geocoding, 'refresh' for using cached utility data (faster)

Available options:

lookup,

refresh

Example:

"lookup"

reference_id

string

required

Your internal reference ID for tracking this customer within your organization (unique per organization)

Example:

"external-ref-123"

building_type

enum<string>

required

Type of building for which to calculate incentives

Available options:

RESIDENTIAL,

MULTIFAMILY,

COMMERCIAL

Example:

"RESIDENTIAL"

device_id

integer

required

ID of the device for which to calculate incentives

Example:

42

address

object

Customer's address information. Required for 'lookup' operation, optional for 'refresh' operation (uses stored address if not provided)

Show child attributes

address.street_1

string

required

Street address line 1 (primary street address)

Example:

"123 Main St"

address.city

string

required

City name

Example:

"San Francisco"

address.state_or_province_code

string

required

State or province code (2-letter abbreviation)

Example:

"CA"

address.postal_code

string

required

Postal/ZIP code

Example:

"94102"

address.country_code

string

required

Country code (2-letter ISO code)

Example:

"US"

address.street_2

string

Street address line 2 (apartment, suite, unit, etc.). Optional.

Example:

"Apt 4B"

create_application

boolean

Whether to create/update application records and return a connect_url

Example:

true

Response

Successful response with aggregated incentive data

utility

object

required

Information about the utility serving the address

Show child attributes

utility.eiaid

integer

required

EIA utility identification number

Example:

14354

utility.name

string

required

Name of the utility company

Example:

"PacifiCorp (Oregon)"

address

object

required

Address object returned from the utility lookup

Show child attributes

address.street_1

string

Example:

"456 Main St"

address.street_2

string

Example:

"Apt 2B"

address.city

string

Example:

"Bend"

address.state_or_province_code

string

Example:

"OR"

address.postal_code

string

Example:

"97701"

address.country_code

string

Example:

"US"

possible_utilities

object[]

required

List of possible utilities that could serve this address

Show child attributes

possible_utilities.eiaid

string

EIA utility identification number

Example:

"14354"

possible_utilities.name

string

Name of the utility company

Example:

"PacifiCorp (Oregon)"

building_type

enum<string>

required

The building type that was queried

Available options:

RESIDENTIAL,

MULTIFAMILY,

MANUFACTURED_HOME,

COMMERCIAL

Example:

"RESIDENTIAL"

customer_id

integer

required

The customer ID (created or found based on address)

Example:

453

reference_id

string

required

Your internal reference ID that was provided in the request

Example:

"ref-abc123"

programs_evaluated

integer

required

Number of programs that were evaluated

Example:

2

incentives

object

required

Show child attributes

incentives.total_incentive_amount

number<float>

required

Total incentive amount across all programs (in USD)

Example:

2250

incentives.total_eligible_combinations

integer

required

Total number of eligible device-tier combinations across all programs

Example:

4

incentives.by_program

object[]

required

Breakdown of incentives by individual program

Show child attributes

incentives.by_program.program_id

integer

required

Unique identifier for the program

Example:

838

incentives.by_program.program_name

string

required

Name of the incentive program

Example:

"Pacific Power – Oregon \"Charge at Home\" EV Charger Rebate"

incentives.by_program.total_incentive

number<float>

required

Total incentive amount for this program (in USD)

Example:

2250

incentives.by_program.eligible_combinations

integer

required

Number of eligible device-tier combinations for this program

Example:

4

incentives.by_program.device_tier_results

object[]

required

Detailed results for each device-tier combination

Show child attributes

incentives.by_program.device_tier_results.device_id

integer

required

Unique identifier for the device type

Example:

123

incentives.by_program.device_tier_results.device_name

string

required

Name of the device type

Example:

"Level 2 EV Charger"

incentives.by_program.device_tier_results.tier_id

integer

required

Unique identifier for the incentive tier

Example:

456

incentives.by_program.device_tier_results.tier_name

string

required

Name of the incentive tier

Example:

"Standard Rebate"

incentives.by_program.device_tier_results.eligible

boolean

required

Whether this device-tier combination is eligible for the customer. True if all eligibility checks passed and incentive amount > 0.

Example:

true

incentives.by_program.device_tier_results.incentive_amount

number<float>

required

Incentive amount for this device-tier combination (in USD)

Example:

750

incentives.by_program.device_tier_results.failed_requirements

string[]

required

List of eligibility requirements that failed for this combination. Empty if eligible is true.

Example:

[]

incentives.by_program.device_tier_results.ignored_requirements

string[]

required

List of eligibility requirements that were ignored/skipped. Provided for transparency.

Example:

[]

incentives.by_program.device_tier_results.calculation_details

string

Details about how the incentive was calculated

Example:

"Fixed rebate per device: $750"

connect_url

string

URL to connect/apply for incentives (only returned if create_application=true)

Example:

"https://connect.leap.energy?refId=ref-abc123"

Getting Started

API Reference

Guides

Overview

Authorizations

Body

Response

Getting Started

API Reference

Guides

​Overview

Authorizations

Body

Response

Overview