Skip to main content
POST
/
incentives
curl -X POST \
  "https://api.incentives.leap.energy/alpha/incentives" \
  -H "x-api-key: leap_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "operation_type": "lookup",
    "reference_id": "external-ref-123",
    "address": {
      "street_1": "123 Main St",
      "street_2": "Apt 4B",
      "city": "San Francisco",
      "state_or_province_code": "CA",
      "postal_code": "94102",
      "country_code": "US"
    },
    "building_type": "RESIDENTIAL",
    "device_ids": [42],
    "create_application": true
  }'
{
  "utility": {
    "eiaid": "14354",
    "name": "PacifiCorp (Oregon)"
  },
  "possible_utilities": [
    {
      "eiaid": "14354",
      "name": "PacifiCorp (Oregon)"
    }
  ],
  "address": "123 Main St, Apt 4B, Bend, OR, 97701",
  "building_type": "RESIDENTIAL",
  "customer_id": 453,
  "programs_evaluated": 2,
  "incentives": {
    "total_incentive_amount": 750,
    "total_eligible_combinations": 1,
    "by_program": [
      {
        "program_id": 838,
        "program_name": "Pacific Power – Oregon \"Charge at Home\" EV Charger Rebate",
        "total_incentive": 750,
        "eligible_combinations": 1,
        "processing_enabled": true,
        "device_tier_results": [
          {
            "device_id": 42,
            "device_name": "Level 2 EV Charger",
            "tier_id": 456,
            "tier_name": "Standard Rebate",
            "eligible": true,
            "incentive_amount": 750,
            "calculation_details": "Fixed rebate per device: $750",
            "failed_requirements": [],
            "ignored_requirements": [
              "Installation must be within 90 days of application",
              "Must use licensed contractor"
            ],
            "completed_requirements": []
          }
        ]
      }
    ]
  },
  "processing_summary": {
    "program_ids": [
      838
    ],
    "incentive_amount": 750
  },
  "connect_url": "https://connect.incentives.leap.energy/your-company/refId/external-ref-123",
  "reference_id": "external-ref-123"
}

​
Overview

Calculate incentives across multiple utility programs for a customer address and device. This endpoint automatically handles customer creation, utility lookup, and incentive aggregation. The API supports three operation types:
  • lookup: First-time customers or when you need fresh utility data (requires full address and device_ids or device_names)
  • refresh: Returning customers using cached utilities (fastest, only requires reference_id)
  • override: Replace all customer devices with new ones, then refresh calculation
You can identify devices by Leap device ID (device_ids) or by your own equipment/product names (device_names). When using device_names, the API resolves them via your organization’s equipment map. See the Incentives API Guide for details on resolution behavior and handling partial matches.
Performance Tip: Use operation_type="refresh" for returning customers to skip geocoding and use cached utility data. You can even omit device_ids to use all existing devices automatically.
The response distinguishes between programs the customer is eligible for (incentives.by_program) and the subset Leap can complete an application for today (processing_summary). When surfacing an offer to a customer, prefer processing_summary.incentive_amount over incentives.total_incentive_amount — see Processing Status for the full rationale. The connect_url is populated only when at least one processing-enabled program is eligible. For detailed operation type behavior, device handling, and best practices, see the Incentives 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), 'override' for replacing all customer devices

Available options:
lookup,
refresh,
override
Example:

"lookup"

​
reference_id
string
required

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

Example:

"external-ref-123"

​
address
object

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

​
building_type
enum<string>

Type of building for which to calculate incentives. Required for 'lookup' and 'override' operations, optional for 'refresh' (uses stored building_type_id if not provided)

Available options:
RESIDENTIAL,
MULTIFAMILY,
MANUFACTURED_HOME,
COMMERCIAL
Example:

"RESIDENTIAL"

​
device_ids
integer[]

Array of Leap device IDs to check incentives for. Required for 'lookup' and 'override' operations unless device_names is provided. Optional for 'refresh' (uses existing devices if not provided). Can contain duplicates. Cannot be combined with device_names.

Example:
[32, 44, 44, 44]
​
device_names
string[]

Array of your equipment/product names to check incentives for. The API resolves these to Leap device IDs using your organization's equipment map. Required for 'lookup' and 'override' operations unless device_ids is provided. Not supported for 'refresh' operations. Cannot be combined with device_ids.

Example:
[
  "Mitsubishi Hyper-Heat MSZ-RXT09",
  "Rheem ProTerraDERA2060"
]
​
create_application
boolean

Whether to create/update application records and return a connect_url

Example:

true

​
webhook_custom_fields
object

Optional custom fields to include in the webhook payload when your organization has a webhook URL configured (e.g. Project ID, Record ID). Only keys allowed by your org's webhook field_names config are merged into the POST body.

Example:
{
  "Project ID": "proj-123",
  "Record ID": "row-5"
}
​
customer
object

Supplementary customer fields applied at customer creation time. Only honored on lookup operations that create a new customer — ignored for existing customers and for refresh/override. Use the Applications PATCH endpoint to update an existing customer's fields.

Example:
{
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "phone": "415-555-0100"
}
​
customer_devices
object[]

Supplementary device fields applied at device creation time, indexed positionally to device_ids. Only honored on lookup operations that create new customer devices — ignored for existing customers and for refresh/override. Each entry is partial; common fields include purchase_price, purchase_date, installation_date, contractor_name. Use the Applications PATCH endpoint to update existing device fields.

Example:
[
  {
    "purchase_price": 1500,
    "installation_date": "2026-03-01"
  },
  { "purchase_price": 2000 }
]

Response

Successful response with aggregated incentive data

​
utility
object
required

Information about the utility serving the address

​
address
string
required

Formatted address string built from the request address fields

Example:

"123 Main St, Apt 4B, San Francisco, CA, 94102"

​
possible_utilities
object[]
required

All utilities whose service territory contains this address. The primary utility is selected from this list; the others are returned so partners can see when an address falls in an overlap region.

​
building_type
enum<string>
required

The building type that was used for the calculation

Available options:
RESIDENTIAL,
MULTIFAMILY,
MANUFACTURED_HOME,
COMMERCIAL
Example:

"RESIDENTIAL"

​
customer_id
integer
required

Leap's internal customer ID (created or found based on reference_id and address)

Example:

453

​
reference_id
string
required

Your internal reference ID that was provided in the request, echoed back for correlation

Example:

"external-ref-123"

​
connect_url
string
required

Branded Connect URL where the customer completes their application. Populated only when create_application=true AND incentives.total_incentive_amount > 0; otherwise returned as an empty string.

Example:

"https://connect.incentives.leap.energy/your-company/refId/external-ref-123"

​
programs_evaluated
integer
required

Number of programs that were evaluated for this address + building type combination

Example:

2

​
incentives
object
required
​
processing_summary
object
required

Subset of incentives covering only programs that Leap is currently set up to process applications for (i.e. by_program[].processing_enabled === true). Use this to decide whether to surface the Connect URL and a concrete offer amount to the customer — programs that aren't processing-enabled may still be listed in by_program but Leap cannot complete the application for them today.

​
warnings
object

Present when device_names was used and some names could not be resolved. The API proceeds with the resolved devices and reports unresolved names here.