Skip to main content
POST
/
incentives
cURL
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": 12345,
    "name": "Pacific Gas & Electric"
  },
  "address": "123 Main St, San Francisco, CA 94102",
  "possible_utilities": [
    {
      "eiaid": "12345",
      "name": "Pacific Gas & Electric"
    }
  ],
  "building_type": "RESIDENTIAL",
  "customer_id": 789,
  "programs_evaluated": 3,
  "incentives": {
    "total_incentive_amount": 5500,
    "total_eligible_combinations": 2,
    "by_program": [
      {
        "program_id": 101,
        "program_name": "Home Upgrade Program",
        "total_incentive": 3000,
        "eligible_combinations": 1,
        "device_tier_results": [
          {
            "device_id": 42,
            "device_name": "Heat Pump",
            "tier_id": 1,
            "tier_name": "Standard",
            "eligible": true,
            "incentive_amount": 3000,
            "calculation_details": "Base incentive for heat pump installation",
            "failed_requirements": [],
            "ignored_requirements": [],
            "completed_requirements": [
              "Income verification",
              "Building type check"
            ]
          }
        ]
      }
    ]
  },
  "reference_id": "external-ref-123",
  "connect_url": "https://connect.incentives.leap.energy/your-company/refId/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)
  • refresh: Returning customers using cached utilities (fastest, only requires reference_id)
  • override: Replace all customer devices with new ones, then refresh calculation
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.
For detailed operation type behavior, device ID 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 device IDs to associate with the customer. Required for 'lookup' and 'override' operations, optional for 'refresh' (uses existing devices if not provided). Can contain duplicates.

Example:
[32, 44, 44, 44]
​
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"
}

Response

Successful response with aggregated incentive data

​
utility
object
required

Information about the utility serving the address

​
address
string
required

Formatted address string

Example:

"123 Main St, San Francisco, CA 94102"

​
possible_utilities
object[]
required

List of possible utilities that could serve this address

​
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
​
connect_url
string

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

Example:

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