Enphase Energy Activations API

openapi: 3.2.0
info:
  title: Commissioning Activations API
  version: v4
servers:
- url: https://api.enphaseenergy.com
tags:
- name: Activations
paths:
  /api/v4/activations/{activation_id}/battery_mode:
    get:
      summary: API endpoint to get battery charge/discharge setting.
      description: This endpoint can be used to get the CFG and DTG settings of the site.
      parameters:
      - name: activation_id
        in: path
        description: The Enlighten ID of the activation(system). System-generated.
        required: true
        schema:
          type: integer
      tags:
      - Activations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  CFG_allowed:
                    type: boolean
                  DTG_allowed:
                    type: boolean
              example:
                CFG_allowed: true
                DTG_allowed: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '401'
                message:
                - Not authorized to access requested resource.
                - API Key missing in url/headers!
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '404'
                message:
                - System not found
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '405'
                message:
                - Method not allowed
        '422':
          description: Unprocessable entity. The body contains error information in a hash of errorMessages and an optional errorCode
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorMessages:
                    type: array
                    items:
                      type: string
              example:
                errorMessages:
                - This is a PV only site. Battery mode can only be fetched for sites with Enphase battery systems
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                    description: Response code
                  message:
                    type: array
                    items:
                      type: string
                      description: Error Messages
              example:
                reason: '429'
                message:
                - Usage limit exceeded for plan Partner (custom)
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '501'
                message:
                - Not Implemented
    put:
      summary: API endpoint to update battery charge/discharge setting.
      description: This endpoint can be used to setup/update the CFG and DTG settings of the site.
      parameters:
      - name: activation_id
        in: path
        description: The Enlighten ID of the activation(system). System-generated.
        required: true
        schema:
          type: integer
      tags:
      - Activations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Battery mode updated successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '401'
                message:
                - Not authorized to access requested resource.
                - API Key missing in url/headers!
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '404'
                message:
                - System not found
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '405'
                message:
                - Method not allowed
        '422':
          description: Unprocessable entity. The body contains error information in a hash of errorMessages and an optional errorCode
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorMessages:
                    type: array
                    items:
                      type: string
              example:
                errorMessages:
                - This is a PV only site. Battery mode can only be updated for sites with Enphase battery systems
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                    description: Response code
                  message:
                    type: array
                    items:
                      type: string
                      description: Error Messages
              example:
                reason: '429'
                message:
                - Usage limit exceeded for plan Partner (custom)
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '501'
                message:
                - Not Implemented
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                CFG_allowed:
                  type: boolean
                  description: true or false
                DTG_allowed:
                  type: boolean
                  description: true or false
              required:
              - CFG_allowed
              - DTG_allowed
  /api/v4/partner/activations:
    get:
      summary: List of Activations
      description: Returns a list of activations for which the user can make API requests. There is a limit to the number of activations which can be returned at one time. If the first request does not return a full list, use the 'next' attribute in the response body to request the next page. By default, activations are returned in batches of 100. The maximum page size is 1000. Provide only valid filters. During filter the activations empty and invalid filter fields are ignored. In case the installer ID doesn’t exist, API will return an empty array.
      parameters:
      - name: next
        in: query
        description: If the first request does not return a full list, use the 'next' attribute in the response body to request the next page. By default, activations are returned in batches of 100. The maximum page size is 1000. If the returned list below the limit, then response does not include the 'next' field.
        schema:
          type: string
      - name: limit
        in: query
        description: There is a limit to the number of activations which can be returned at one time
        schema:
          type: integer
      - name: stage
        in: query
        description: Filter activations by stage. Passing in_progress alone will consider as you have passed all the 1,2,3,4 stages. Passing multiple stage values using comma to filter. E.g. stage=1,2,3. Paasing in_progress with any other combination will give you empty systems. This parameter searches for an exact match of the input value.
        schema:
          type: string
          enum:
          - 1
          - 2
          - 3
          - 4
          - 5
          - in_progress
      - name: reference
        in: query
        description: Filter activations by company reference. This parameter searches for an exact match of the input value and is not case-sensitive.
        schema:
          type: string
      - name: installer_id
        in: query
        description: Filter activations by installer id. This parameter searches for an exact match of the input value.
        schema:
          type: integer
      - name: system_name
        in: query
        description: Filter activations by system name. This parameter searches for an exact match of the input value and is not case-sensitive.
        schema:
          type: string
      - name: city
        in: query
        description: Filter activations by city. This parameter searches for an exact match of the input value and is not case-sensitive.
        schema:
          type: string
      - name: state
        in: query
        description: Filter activations by state. This parameter searches for an exact match of the input value and is not case-sensitive.
        schema:
          type: string
      - name: country
        in: query
        description: Filter activations by country. This parameter searches for an exact match of the input value and is not case-sensitive.
        schema:
          type: string
      - name: postal_code
        in: query
        description: Filter activations by zipcode. This parameter searches for an exact match of the input value.
        schema:
          type: string
      - name: street1
        in: query
        description: Filter activations by street1. This parameter searches for an exact match of the input value and is not case-sensitive.
        schema:
          type: string
      - name: street2
        in: query
        description: Filter activations by street2. This parameter searches for an exact match of the input value and is not case-sensitive.
        schema:
          type: string
      - name: host_id
        in: query
        description: Filter activations by host_id. This parameter searches for an exact match of the input value. In addition to Integers, the filter will support null values too
        schema:
          type: integer
      - name: owner_id
        in: query
        description: Filter activations by owner_id. This parameter searches for an exact match of the input value. In addition to Integers, the filter will support null values too
        schema:
          type: integer
      tags:
      - Activations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  systems:
                    type: array
                    description: Zero or more activations
                    items:
                      type: object
                      properties:
                        system_id:
                          type: integer
                          description: The Enlighten ID of this system. System-generated
                        system_name:
                          type: string
                          description: The name of the system.
                        system_type:
                          type: string
                          description: The type of the system. One of 'residential', 'commercial', or 'other'. Default 'residential'. Cannot be null.
                        status:
                          type: string
                          description: System's status.
                        timezone:
                          type: string
                          description: System's timezone.
                        stage:
                          type: integer
                          description: What stage of the activation process this activation is in. System-generated.
                        internet_connection:
                          type: string
                          description: How the system's Envoys connect to the Internet. Possible values are none, cellular, broadband, dialup. Use 'dialup' if the Internet connection is satellite or dial-up
                        lease:
                          type: boolean
                          description: Whether the system is leased. Possible values true, false. Default false
                        operational:
                          type: boolean
                          description: Whether this system is permitted to operate. Possible values true, false. Default true
                        owner:
                          type: string
                          description: Name of the system owner. Owner must be an Enlighten user. If the user of the API is a self-installer, the owner must be himself
                        owner_id:
                          type: integer
                          description: The Enlighten ID of this system owner. System-generated
                        host:
                          type: string
                          description: Name of the system host. Please see “Specifying an Owner and Lease Arrangement”, above, for more information.
                        host_id:
                          type: integer
                          description: The Enlighten ID of this system host. System-generated
                        installer_name:
                          type: string
                          description: Name of the installer.
                        installer_id:
                          type: integer
                          description: The Enlighten ID of the installer of this system
                        maintainer_name:
                          type: string
                          description: Name of the maintainer.
                        maintainer_id:
                          type: integer
                          description: The Enlighten ID of the maintainer of this system
                        authorized_subcontractors:
                          type: array
                          description: List of sub-contractors of this system.
                          items:
                            type: object
                            properties:
                              authorized_subcontractor_id:
                                type: integer
                                description: The Enlighten ID of the sub-contractor of this system. System-generated.
                              authorized_subcontractor_name:
                                type: string
                                description: Name of the sub-contractor of this system.
                              status:
                                type: string
                                description: Current status of the subcontractor for the site. This field will be shown only for pending and rejected sub-contractors.
                        grid_connection_type:
                          type: object
                          description: 'Possible values for parameter: 1 – Net Billing Tariff (NEM 3.0), 2 – Net Metering, 3 – Net Feed-in tariff, 4 – Gross Feed-in tariff'
                          properties:
                            type:
                              type: integer
                            value:
                              type: string
                        battery_grid_mode:
                          type: string
                          description: Battery grid mode can be of two types - Export Only, Import Only
                        third_party_storage_device_installed:
                          type: boolean
                          description: If third party storage device is installed on the site.
                        third_party_storage_device_manufacturer:
                          type: string
                          description: Manufacturer name of the third party storage device.
                        interconnection_application_date:
                          type: integer
                          description: Date in epoch format
                        permission_to_operate:
                          type: boolean
                          description: boolean (true / false)
                        uri:
                          type: string
                          description: URI for this activation
                        updated_at:
                          type: integer
                          description: Activation last updated timestamp
                        reference:
                          type: string
                          description: The identifier of this system as provided by the calling user's company. This attribute is not present if the calling user's company does not have a reference for this system.
                        other_references:
                          type: array
                          description: The identifiers assigned to this activation by other companies which have access to it. This attribute is not present if there are no other references for this system.
                          items:
                            type: string
                            description: Name of the reference
                        address:
                          type: object
                          description: The location of the system. Use the ISO 3166-1 2-letter code for the country. Latitude and longitude are calculated by Enlighten, not provided by the client
                          properties:
                            street1:
                              type: string
                              description: Street line 1
                            city:
                              type: string
                              description: City
                            state:
                              type: string
                              description: State
                            postal_code:
                              type: string
                              description: Postal code
                            country:
                              type: string
                              description: Country
                            latitude:
                              type: integer
                              description: Latitude
                            longitude:
                              type: integer
                              description: Longitude
                            street2:
                              type: string
                              description: Street line 2. This field is Optional
                  next:
                    type: string
                    description: If the first request does not return a full list, use the 'next' attribute in the response body to request the next page. By default, activations are returned in batches of 10. The maximum page size is 1000
              example:
                systems:
                - system_id: 12345
                  system_name: System name
                  system_type: residential
                  status: Normal
                  timezone: US/Pacific
                  stage: 5
                  internet_connection: dialup
                  lease: false
                  operational: true
                  owner: Test User
                  owner_id: 123
                  host: 321
                  host_id: Host name
                  installer_name: Enphase & Energy
                  installer_id: 1
                  maintainer_name: Enphase & Energy
                  maintainer_id: 5
                  authorized_subcontractors:
                  - authorized_subcontractor_id: 67
                    authorized_subcontractor_name: Enphase India
                  - authorized_subcontractor_id: 68
                    authorized_subcontractor_name: Enphase India
                    status: Pending for system owner approval
                  grid_connection_type:
                    type: 1
                    value: Net Billing Tariff (NEM 3.0)
                  battery_grid_mode: Export Only
                  third_party_storage_device_installed: true
                  third_party_storage_device_manufacturer: Franklin
                  interconnection_application_date: 1727156880
                  permission_to_operate: true
                  uri: /api/v4/partner/activations/12345.json
                  updated_at: 1628153151
                  reference: ENPH123
                  other_references:
                  - OTHER1234
                  address:
                    street1: Bangalore Lane
                    city: San Diego
                    state: CA
                    postal_code: '92126'
                    country: US
                    latitude: 32.912785
                    longitude: -117.153778
                    street2: 2nd Street
                next: 4e6a6b344f5445774d446b350a
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '401'
                message:
                - Not authorized to access requested resource.
                - API Key missing in url/headers!
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '405'
                message:
                - Method not allowed
        '422':
          description: Unprocessable entity. The body contains error information in a hash of errorMessages and an optional errorCode
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: integer
                  errorMessages:
                    type: array
                    items:
                      type: string
              example:
                errorMessages:
                - Invalid stage option 11
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                    description: Response code
                  message:
                    type: array
                    items:
                      type: string
                      description: Error Messages
                  period:
                    type: string
                    description: Quota exceeded for minute/month
                  period_start:
                    type: integer
                    description: Starting period timestamp
                  period_end:
                    type: integer
                    description: Ending period timestamp
                  limit:
                    type: integer
                    description: Limit count for the period
              example:
                reason: '429'
                message:
                - Usage limit exceeded for plan Partner (custom)
                period: minute
                period_start: 1623825660
                period_end: 1623825720
                limit: 5
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '501'
                message:
                - Not Implemented
    post:
      summary: Create new activation.
      description: Create new activation. Address is mandatory if users company belongs to US.
      tags:
      - Activations
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  system_id:
                    type: integer
                    description: The Enlighten ID of this system. System-generated
                  system_name:
                    type: string
                    description: The name of the system.
                  system_type:
                    type: string
                    description: The type of the system. One of 'residential', 'commercial', or 'other'. Default 'residential'. Cannot be null.
                  status:
                    type: string
                    description: System's status.
                  stage:
                    type: integer
                    description: What stage of the activation process this activation is in. System-generated.
                  internet_connection:
                    type: string
                    description: How the system's Envoys connect to the Internet. Possible values are none, cellular, broadband, dialup. Use 'dialup' if the Internet connection is satellite or dial-up
                  lease:
                    type: boolean
                    description: Whether the system is leased. Possible values true, false. Default false
                  operational:
                    type: boolean
                    description: Whether this system is permitted to operate. Possible values true, false. Default true
                  owner:
                    type: object
                    description: Name of the system owner. Owner must be an Enlighten user. If the user of the API is a self-installer, the owner must be himself. If the query parameter 'expand=owner' passed in the request owner detail will appear in the response
                    properties:
                      first_name:
                        type: string
                      last_name:
                        type: string
                      email:
                        type: string
                      phone:
                        type: string
                      active:
                        type: boolean
                        description: Whether the user is allowed to log in to Enlighten. Values true, false. Default true.
                      user_id:
                        type: integer
                      user_roles:
                        type: array
                        items:
                          type: string
                          description: Role
                        description: What type of user this is in Enlighten. Possible values are ['self_installer']. For self installer user user_roles will be ['self_installer']. For other users user_roles will be empty.
                      enlighten_emails:
                        type: boolean
                      enlighten_view:
                        type: string
                      uri:
                        type: string
                      updated_at:
                        type: integer
                  owner_id:
                    type: integer
                    description: The Enlighten ID of this system owner. System-generated. This field is optional.
                  host:
                    type: object
                    description: Name of the system host. Please see “Specifying an Owner and Lease Arrangement”, above, for more information. If the query parameter 'expand=host' passed in the request host detail will appear in the response
                    properties:
                      first_name:
                        type: string
                      last_name:
                        type: string
                      email:
                        type: string
                      phone:
                        type: string
                      active:
                        type: boolean
                        description: Whether the user is allowed to log in to Enlighten. Values true, false. Default true.
                      user_id:
                        type: integer
                      user_roles:
                        type: array
                        items:
                          type: string
                          description: Role
                        description: What type of user this is in Enlighten. Possible values are ['self_installer']. For self installer user user_roles will be ['self_installer']. For other users user_roles will be empty.
                      enlighten_emails:
                        type: boolean
                      enlighten_view:
                        type: string
                      uri:
                        type: string
                      updated_at:
                        type: integer
                  host_id:
                    type: integer
                    description: The Enlighten ID of this system host. System-generated. This field is optional.
                  installer_name:
                    type: string
                    description: Name of the installer.
                  installer_id:
                    type: integer
                    description: The Enlighten ID of the installer of this system. Defaults to current user's company ID
                  maintainer_name:
                    type: string
                    description: Name of the maintainer.
                  maintainer_id:
                    type: integer
                    description: The Enlighten ID of the maintainer of this system. Defaults to current user's company ID
                  authorized_subcontractors:
                    type: array
                    description: List of sub-contractors of this system.
                    items:
                      type: object
                      properties:
                        authorized_subcontractor_id:
                          type: integer
                          description: The

# --- truncated at 32 KB (144 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/enphase/refs/heads/main/openapi/enphase-activations-api-openapi.yml