Requirements reference

A program pays only after its requirements are met. This page lists every requirement and shows how to claim the ones you’ll supply. It then explains how to send each kind through the API. Claim what you can supply reliably and let Connect collect the rest from the customer.

Requirements come in three kinds

A requirement is anything a program needs before it pays: a fact, a file, or a signature. Each kind reaches Leap a different way:

Fields: facts about the customer or the installation, such as a utility account number or a purchase price. You send them as key and value pairs on lookups and applications.
Documents: files such as invoices, photos, and permits. You upload them as attachments on the application.
Agreements: terms, attestations, and enrollment consents the customer signs. Connect collects these on screen, so they aren’t listed here and you can’t claim them.

Claim the requirements you’ll supply

Under Settings → Data Preferences, mark each field and document you’ll supply. Leap removes a claimed requirement from the customer’s Connect form and expects it from you through the API. Anything you leave unclaimed, Connect asks the customer for. Claim only what you can supply reliably, and leave the rest.

Field names say what they describe

Every field name starts with a prefix that tells you which object it belongs to:

customer. fields describe the applicant: their name, their utility account, their home. An application has one set.
customer_device. fields describe one installation: what it cost, when it went in, who installed it. Each installation on an application has its own values.

Documents have no prefix. They attach to the application as a whole, so one upload covers the claim rather than a single installation.

Send fields in stages

You don’t need every value up front. Send what you have when you quote, on Look up incentives. Send the rest, such as the purchase date and the installation cost, on later Refresh incentives calls. Write each field name exactly as it appears on this page. Customer fields go in customer_details. Installation fields go in the details object on the matching customer_devices[] entry. This lookup sends one of each:

{
  "reference_id": "customer-123",
  "customer_details": {
    "customer.utility_account_number": "0123456789"
  },
  "customer_devices": [
    {
      "device_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "details": {
        "customer_device.purchase_price": "699.00"
      }
    }
  ]
}

On an application, drop the prefix and nest the field under the object its scope names. customer.email becomes email inside customer, and customer_device.purchase_price becomes purchase_price inside that customer_devices[] entry.

Leap checks every key in the request before writing anything. One unrecognized key returns 400 and no incentives, and the response reports every bad key at once, so you can fix them in one pass.

Value formats

Send every value as a string. Leap parses it into the type the field expects. Expected formats:

Booleans: true or false
Dates: YYYY-MM-DD
Numbers: digits with an optional decimal point, no currency symbol and no thousands separator
Enums: the documented value as written, matched without regard to case

An absent key, a JSON null, and a blank string all mean the same thing: the value isn’t supplied.

Send documents as attachments

File bytes never pass through the Applications API. Instead, you upload each file straight to storage with a pre-authorized URL, the same pattern as an S3 pre-signed PUT. Only two Leap calls need your API key: one to get the URL, one to commit the file.

Request an upload URL

Call POST /applications/attachments with the attachment_type, filename, and contentType. The response returns a short-lived uploadUrl and a path. Leap prefixes your filename with a unique ID, so two files named invoice.pdf never collide.

curl -X POST "https://api.incentives.leap.energy/alpha/applications/attachments?application_id=123" \
  -H "x-api-key: leap_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "attachment_type": "INVOICE_EQUIPMENT", "filename": "invoice.pdf", "contentType": "application/pdf" }'
# → { "uploadUrl": "https://storage.example.com/attachments/app-123/1a2b3c4d-invoice.pdf?token=...",
#     "path": "app-123/1a2b3c4d-invoice.pdf" }

Upload the file

PUT the raw bytes to that uploadUrl with the file’s Content-Type. This request goes straight to storage and needs no API key.

curl -X PUT "$uploadUrl" \
  -H "Content-Type: application/pdf" \
  --data-binary @invoice.pdf

Commit the attachment

Call POST /applications/attachments/commit with the same attachment_type and the path from step 1. Leap records the attachment on the application.

curl -X POST "https://api.incentives.leap.energy/alpha/applications/attachments/commit?application_id=123" \
  -H "x-api-key: leap_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "attachment_type": "INVOICE_EQUIPMENT", "path": "app-123/1a2b3c4d-invoice.pdf" }'

To read a file back, call Download attachment for a signed URL. The URL is valid for one hour.

Customer fields

These describe the applicant. Send them in customer_details on a lookup, or under customer on an application.

Identity and contact (5 fields)

string

The customer’s first name.

string

The customer’s last name.

string

The customer’s email address.

string

The customer’s phone number.

string

Mailing address, where it differs from the address the equipment was installed at. Programs that mail a check use it.

Utility account (3 fields)

string

The customer’s account number with their serving utility. Programs run by a utility check that the applicant is their customer.

enum

Standing of the utility account: active, delinquent, closed, inactive, or pending. Most programs require an account in good standing.

string

The rate plan or tariff on the utility account. Some programs pay only on a particular plan, such as a time-of-use tariff.

Household and property (8 fields)

boolean

Whether the customer owns the property. Most programs pay only the owner, or route renters to a different tier.

boolean

Whether the customer meets the program’s income threshold. Income-qualified tiers usually pay more.

boolean

Whether the customer identifies as Indigenous. A few programs add an adder or a dedicated tier.

number

Age of the building in years. Retrofit programs set a minimum.

number

Number of dwelling units at the address. Separates single-family from multifamily where a program pays differently.

number

Customer-collected. Capacity of the electrical panel in amps. Programs that fund a panel upgrade check whether the existing service can carry the new load.

boolean

Customer-collected. Whether the customer files taxes jointly. Income-qualified programs use it to read the household income threshold correctly.

number

Customer-collected. Dependents claimed on the customer’s tax filing. Income thresholds usually scale with household size.

Vehicle (6 fields)

These describe the customer’s vehicle. Programs that pay on the vehicle itself rather than on the charger read the installation-level set instead: customer_device.vehicle_vin, .dealership and .vehicle_type under Installation fields. Both sets exist on purpose.

string

Make of the customer’s electric vehicle.

string

Model of the customer’s electric vehicle.

number

Model year of the customer’s electric vehicle. Some programs set a cutoff.

string

Vehicle identification number. Programs that pay once per vehicle use it to tell vehicles apart.

string

Dealership the vehicle came from. A few programs pay only on a participating dealer.

date

Date the vehicle was registered. Programs that require a recent purchase check it.

Installation fields

These describe one installation. Send them in the details object of the matching customer_devices[] entry on a lookup, or directly on that entry on an application.

Cost (3 fields)

number

Price paid for the equipment, excluding installation labor and materials.

number

Cost of the installation: labor, materials, permits, and any electrical work.

number

Equipment and installation together, where you hold one figure rather than a split.

Dates (4 fields)

date

Date the customer bought the equipment. Programs check it against their program year.

date

Date the equipment was installed and operational. Claim windows run from this date.

date

Date the utility granted permission to operate. Programs that require interconnection run their claim window from this date instead.

date

Date the installation passed its final inspection. Programs that require a signed-off inspection check it, and some run their claim window from it.

Equipment (7 fields)

string

Serial number on the installed unit. Programs use it to confirm the equipment and to stop a second claim on it.

number

The count of identical units this entry covers.

boolean

Whether the equipment is new rather than used or refurbished. Most programs pay only on new equipment.

number

Length of the equipment warranty in months. Some programs set a minimum.

string

Where the customer bought the equipment. Programs that pay only on approved retailers check it.

boolean

Whether the install needed underground trenching. Some programs pay an adder for it.

string

Customer-collected. How the home is cooled today. Weatherization and heat-pump programs price against what the equipment replaces.

Permits and inspection (2 fields)

string

Permit number issued by the local authority. Programs that require a permitted installation check it.

boolean

Whether the installation passed inspection.

Vehicle (3 fields)

Use these where the program pays on the vehicle at the installation level. The customer’s own vehicle details live under Customer fields.

string

Identification number of the vehicle this installation serves.

string

Dealership the vehicle came from.

string

Type of vehicle the charger serves. Programs that price by vehicle type check it.

Contractor (10 fields)

string

Company that performed the installation.

string

License number of the installing contractor. Programs that require a licensed installation check it.

string

Named contact at the contracting company.

string

Email address for that contact. Programs email them when paperwork is missing.

string

Phone number for that contact.

string

Street address of the contracting company. Programs that pay the contractor need it for tax reporting.

string

City of the contracting company.

string

State of the contracting company. Programs check the contractor is licensed where the work happened.

string

ZIP code of the contracting company.

string

Website of the contracting company.

Document types

These are the files a program can ask for. Send the type name as attachment_type on the upload and commit calls.

Proof of purchase and installation (5 types)

attachment

Itemized invoice or receipt for the equipment, showing the model and the price paid.

attachment

Invoice for the installation work, showing labor and materials.

attachment

Photo of the finished installation in place.

attachment

Photo of the equipment nameplate, showing the model and rating.

attachment

Photo of the serial number on the installed unit.

Permits and inspection (2 types)

attachment

The electrical or building permit issued for the work.

attachment

Photo of the electric meter, showing the meter number so the utility can match the account to the premise.

Equipment specifications (4 types)

attachment

Manufacturer specification sheet for the installed model.

attachment

Manufacturer specification sheet for the inverter.

attachment

Certificate from the Air-Conditioning, Heating, and Refrigeration Institute. It confirms the rated performance of a matched heating or cooling system, which is what efficiency programs pay against.

attachment

Report from the National Energy Audit Tool. It lists the weatherization measures an energy audit recommends for the home, and which of them the program will fund.

Site drawings (2 types)

attachment

Electrical one-line diagram showing the system configuration.

attachment

Site plan showing where the equipment sits on the property.

Customer and account documents (8 types)

attachment

A recent utility bill, used to confirm the account and the service address.

attachment

Proof of income for an income-qualified program.

attachment

A completed W-9, needed where the program pays the customer or the contractor directly.

attachment

Confirmation that the customer is on the rate plan the program requires.

attachment

Purchase or lease agreement for the electric vehicle.

attachment

The vehicle’s registration document.

attachment

The customer’s signature, captured in Connect. The customer signs on screen and Connect uploads the result, so you do not send this one.

attachment

Anything a program asks for that no other type covers.

Get Started

VPP Offers

Incentives

Applications

Programs

Devices

Requirements come in three kinds

Claim the requirements you’ll supply

Field names say what they describe

Send fields in stages

Value formats

Send documents as attachments

Customer fields

Installation fields

Document types

​Requirements come in three kinds

​Claim the requirements you’ll supply

​Field names say what they describe

​Send fields in stages

​Value formats

​Send documents as attachments

​Customer fields

​Installation fields

​Document types

Requirements come in three kinds

Claim the requirements you’ll supply

Field names say what they describe

Send fields in stages

Value formats

Send documents as attachments

Customer fields

Installation fields

Document types