Skip to main content

​
Overview

This guide covers key concepts, workflows, and best practices for working with the Leap API. For detailed endpoint specifications, see the individual API reference pages.

​
Authentication

All API requests require authentication via the x-api-key header: 
curl -X GET "https://api.incentives.leap.energy/alpha/applications" \
  -H "x-api-key: leap_live_..."
Never expose API keys in client-side code or public repositories. Always use environment variables and keep keys secure.

​
Best Practices

​
Performance Optimization

  1. Pagination: Use appropriate limit values for search endpoints (default: 50, max: 100)
  2. Cache reference data: Store customer IDs and reference IDs locally to avoid repeated lookups
  3. Poll efficiently: Use reasonable intervals when monitoring application status changes

​
Error Handling

Common HTTP status codes:
  • 400 Bad Request: Missing required fields, invalid parameters, or validation errors
  • 401 Unauthorized: Missing or invalid x-api-key header
  • 403 Forbidden: API key valid but lacks permission (e.g., IP restrictions)
  • 404 Not Found: Resource doesn’t exist (Incentives API: address has no utility match)
  • 422 Unprocessable Entity: Incentives API — address could not be geocoded, or building type could not be resolved during refresh
  • 500 Internal Server Error: Server-side error (contact support if persistent)
  • 502 Bad Gateway: Incentives API — upstream geocoder or programs service is unavailable. Safe to retry with exponential backoff.
Error response shape depends on the API:
  • Incentives API (/incentives, /batch-lookups, /webhook-config): returns error (human-readable message) and error_code (stable typed identifier). Branch retry logic on error_code, not on error. See the Incentives API Guide error reference for the full table.
  • Applications API (/applications, attachments): returns code (machine-readable identifier), message (human-readable), and requestId (include in support tickets).
Both shapes may include a details object with diagnostic context (e.g. upstream + upstream_status for Incentives 5xx responses).

​
Testing & Validation

  1. Test with test keys: Always develop against test environment first
  2. Validate data: Test your integration with various scenarios before going live

​
Security Considerations

  1. Never commit API keys: Use environment variables and secret management
  2. Rotate keys regularly: Generate new keys periodically and revoke old ones
  3. Use HTTPS only: All API requests must use HTTPS
  4. Validate input: Always validate user input before sending to the API

​
API Guides

For detailed information on working with specific APIs, see:

​
Support & Resources

  • API Reference: Detailed endpoint specifications in the API Reference section
  • OpenAPI Spec: Download the full OpenAPI specification for use with API tools
  • Support: Contact support@leap.energy with your requestId for troubleshooting