> ## Documentation Index
> Fetch the complete documentation index at: https://docs.incentives.leap.energy/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Applications

> Search and filter applications with pagination. Returns a list of applications matching the specified criteria. Applications are automatically filtered to your organization.

## Overview

Search and filter applications with pagination.

<Note>
  **Truncated Response**: The search endpoint returns a simplified version of application data. For complete application details including all customer fields and customer devices, use the [Get Application](/api-reference/endpoint/get-application) endpoint.
</Note>

For more information and best practices, see the [Applications API Guide](/applications-guide).


## OpenAPI

````yaml GET /applications
openapi: 3.0.3
info:
  title: Leap Energy API
  description: >-
    The Leap Energy API provides a unified interface for managing rebate
    incentives and applications.


    ## Incentives API

    Search for and calculate incentive amounts across multiple utility programs.
    Given a customer

    address and building type, the API identifies applicable utility programs
    and calculates potential

    incentive amounts for various device and tier combinations. When your
    organization has a webhook URL

    configured (Webhook Config API), each successful lookup triggers a POST to
    your URL with the response

    and optional custom fields (`webhook_custom_fields`).


    ## Applications API

    Manage rebate applications on behalf of customers. Applications represent a
    customer's request

    for a rebate under a specific utility program, including customer
    information, device details,

    and application metadata.
  version: 2.0.0
  contact:
    name: Leap Energy
    url: https://leap.energy
servers:
  - url: https://api.incentives.leap.energy/alpha
    description: Production API
security:
  - ApiKeyAuth: []
  - BearerAuth: []
paths:
  /applications:
    get:
      summary: Search applications
      description: >
        Search and filter applications with optional pagination. Returns a list
        of applications

        matching the specified criteria. All results are automatically filtered
        to applications belonging to your organization.


        **Authentication:**

        Requires API key authentication via `x-api-key` header.


        **Organization Scoping:**

        Results are automatically filtered by your organization ID. You can only
        access applications that belong to your organization.
      operationId: searchApplications
      parameters:
        - name: refId
          in: query
          description: >-
            Reference ID to filter applications for a specific customer within
            your organization
          required: false
          schema:
            type: string
            example: 982734ihksjhfwoe8u
        - name: application_status
          in: query
          description: Filter by application status
          required: false
          schema:
            type: string
            enum:
              - not_started
              - in_progress
              - awaiting_customer
              - awaiting_partner
              - completed
              - submitted
              - approved
              - rejected
            example: awaiting_partner
        - name: page_token
          in: query
          description: Token for pagination to fetch the next page of results
          required: false
          schema:
            type: string
            example: 242c3e24-43e6-4ad7-88b3-666cda21582b
        - name: limit
          in: query
          description: Maximum number of results to return per page
          required: false
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
            example: 50
      responses:
        '200':
          description: Successful response with list of applications
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationSearchResponse'
              examples:
                awaiting_partner_applications:
                  summary: Applications awaiting partner data
                  value:
                    next_page_token: 242c3e24-43e6-4ad7-88b3-666cda21582b
                    results:
                      - id: 123
                        program_id: 339
                        customer_id: 609
                        customer_device_id:
                          - 45
                          - 46
                        status: awaiting_partner
                        rebate_type: instant
                        payee_type: customer
                        total_requested_amount: 150
                        created_at: '2025-01-10T15:30:00Z'
                        updated_at: '2025-01-15T10:45:00Z'
                        customer:
                          id: 609
                          first_name: John
                          last_name: Doe
                          email: john.doe@example.com
                          phone: 555-123-4567
                          address_line1: 123 Peachtree St
                          city: Atlanta
                          state: GA
                          zip_code: '30303'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Application not in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: forbidden
                message: Application not in your organization
                requestId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl -X GET \
              "https://api.incentives.leap.energy/alpha/applications?application_status=awaiting_partner&limit=50" \
              -H "x-api-key: leap_live_..." \
              -H "Content-Type: application/json"
        - lang: python
          label: Python
          source: |-
            import requests

            url = "https://api.incentives.leap.energy/alpha/applications"
            params = {
                "application_status": "awaiting_partner",
                "limit": 50
            }
            headers = {
                "x-api-key": "leap_live_...",
                "Content-Type": "application/json"
            }

            response = requests.get(url, params=params, headers=headers)
            print(response.json())
        - lang: javascript
          label: JavaScript
          source: |-
            const response = await fetch(
              'https://api.incentives.leap.energy/alpha/applications?application_status=awaiting_partner&limit=50',
              {
                method: 'GET',
                headers: {
                  'x-api-key': 'leap_live_...',
                  'Content-Type': 'application/json'
                }
              }
            );

            const data = await response.json();
            console.log(data);
components:
  schemas:
    ApplicationSearchResponse:
      type: object
      required:
        - results
      properties:
        next_page_token:
          type: string
          nullable: true
          description: >-
            Token to fetch the next page of results. Null if no more pages
            available.
          example: 242c3e24-43e6-4ad7-88b3-666cda21582b
        results:
          type: array
          description: Array of applications matching the search criteria
          items:
            $ref: '#/components/schemas/ApplicationSearchResult'
    Error:
      type: object
      required:
        - code
        - message
        - requestId
      properties:
        code:
          type: string
          description: Error code identifying the type of error
          example: not_found
        message:
          type: string
          description: Human-readable error message
          example: Application 123 not found
        details:
          description: Additional error details (optional)
          example: Additional context about the error
        requestId:
          type: string
          description: Unique request identifier for tracking and debugging
          example: 550e8400-e29b-41d4-a716-446655440000
    ApplicationSearchResult:
      type: object
      description: Truncated application information returned in search results
      required:
        - id
        - program_id
        - customer_id
        - status
      properties:
        id:
          type: integer
          description: Unique identifier for the application
          example: 123
        program_id:
          type: integer
          description: ID of the rebate program this application is for
          example: 45
        customer_id:
          type: integer
          description: ID of the customer who owns this application
          example: 456
        organization_id:
          type: string
          format: uuid
          nullable: true
          description: Organization ID
          example: 550e8400-e29b-41d4-a716-446655440000
        reference_id:
          type: string
          nullable: true
          description: >-
            Your unique identifier for the customer in your system. Must be
            unique per customer within your organization and matches the value
            you use with the incentives API.
          example: external-ref-123
        customer_device_id:
          type: array
          items:
            type: integer
          description: Array of customer device IDs associated with this application
          example:
            - 10
            - 11
        rebate_type:
          type: string
          nullable: true
          description: Type of rebate being requested
          example: point_of_sale
        payee_type:
          type: string
          enum:
            - customer
            - contractor
            - instant
          nullable: true
          description: Who will receive the rebate payment
          example: customer
        submission_date:
          type: string
          format: date
          nullable: true
          description: Date the application was submitted
          example: '2025-01-15'
        approval_date:
          type: string
          format: date
          nullable: true
          description: Date the application was approved
          example: '2025-01-20'
        total_requested_amount:
          type: number
          format: decimal
          nullable: true
          description: Total rebate amount being requested
          example: 1500
        status:
          type: string
          enum:
            - not_started
            - in_progress
            - awaiting_customer
            - awaiting_partner
            - completed
            - submitted
            - approved
            - rejected
          default: not_started
          description: Current status of the application
          example: submitted
        equipment_complete:
          type: boolean
          nullable: true
          description: Whether all equipment documentation is complete
        permit_complete:
          type: boolean
          nullable: true
          description: Whether all permit documentation is complete
        utility_complete:
          type: boolean
          nullable: true
          description: Whether all utility documentation is complete
        created_at:
          type: string
          format: date-time
          description: Timestamp when application was created
          example: '2025-01-10T10:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: Timestamp when application was last updated
          example: '2025-01-15T14:30:00Z'
        customer:
          $ref: '#/components/schemas/CustomerSearchResult'
    CustomerSearchResult:
      type: object
      description: Truncated customer information returned in search results
      required:
        - id
        - address_line1
        - city
        - state
        - zip_code
      properties:
        id:
          type: integer
          description: Unique identifier for the customer
          example: 456
        first_name:
          type: string
          nullable: true
          description: Customer's first name
          example: Jane
        last_name:
          type: string
          nullable: true
          description: Customer's last name
          example: Doe
        email:
          type: string
          format: email
          nullable: true
          description: Customer's email address
          example: jane.doe@example.com
        phone:
          type: string
          nullable: true
          description: Customer's phone number
          example: '+15551234567'
        address_line1:
          type: string
          description: Street address line 1
          example: 123 Main St
        city:
          type: string
          description: City
          example: San Francisco
        state:
          type: string
          description: State code (2 letters)
          example: CA
        zip_code:
          type: string
          description: ZIP code
          example: '94102'
  responses:
    UnauthorizedError:
      description: API key is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >
        API key for authentication. Include your Leap API key in the `x-api-key`
        header: `x-api-key: leap_live_...`
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Clerk JWT token for portal authentication

````