Release Notes

What's new

  • Allow TPO companies to set subcontractors and maintainer via Activation API
    • Thid-Party Owner (TPO) companies can now set or update maintainers and subcontractors via the POST and PUT Activation APIs.
    • This can be done for a site at any stage (stage 1 to 5).
  • Fix for Incorrect System Size in Systems Summary API
    • The System Summary endpoint was previously returning incorrect system sizes (a mismatch between the endpoint response and the system size shown in Enlighten).
    • This issue has been resolved.
  • Create activations with retired Envoys
    • Activations cannot be created for an Envoy that is already associated with an active site.
    • If the Envoy is retired, Enlighten/ITK allows users to create activations using the retired Envoy.
    • This functionality is now available via APIs as well.
  • Add interconnection date and PTO flag to Activations API
    • Interconnection date and Permission to Operate (PTO) flag are now added as request parameters in the Activations endpoint. These fields apply to Net Billing Tariff (NEM 3.0) systems. If the PTO flag is TRUE, the interconnection date must be provided. The interconnection date cannot be a future date and must be after 04/14/2023 (the NEM 2.0 sunset date). The interconnection date should be passed in epoch format.
  • Access token not revoked in case of Homeowner password change
    • For applications created via the Developer Plan, a homeowner access token used to be invalidated when the homeowner changed their Enlighten password. This issue has been fixed. Once an application is authorized, even if the homeowner changes their password, the access token will not be invalidated.
  • Revision to quick start guide
    • The Enphase API Quick Start Guide has been updated to reflect the latest changes, including:
      • Updated examples
      • Updated visual cues (images, chosen plan display)
      • Updated naming conventions to reflect the latest Enphase product names.

What's new

  • Filter api/v4/systems/search endpoint based on references and other references.
    • Allow users to filter systems based on references or other_references.
    • Search by reference is allowed only for string values, not arrays. Exact search will be done (case -insensitive).
    • Search by other_reference is allowed only for string values, not arrays. Exact search will be done (case -insensitive).
    • When searching by both reference and other_reference, sites that meet both conditions will be returned.
  • Add grid connection type and battery grid mode in Activations
    • While creating or updating an activation using POST /api/v4/partner/activations and PUT /api/v4/partner/activations/{activation_id}, Enphase API will validate the access token. If the Enlighten user credentials with which the token is generated belong to a company in the United States, the address needs to be passed as part of the activation request.
      • If the country is the United States and the address is not passed, the following error is returned “Address is mandatory for sites created in the United States.”
    • The following parameters are added to the Activations API and are optional as part of this release
      • grid_connection_type: Grid connection type is applicable only for CA state; For CA State, it cannot be empty. Accepted values are 1 – Net Billing Tariff (NEM 3.0) , 2 – Net Metering, 3 – Net Feed-in tariff, 4 – Gross Feed-in tariff
      • battery_grid_mode: Battery grid mode is applicable only for Battery sites with grid connection type as 1. It must not be passed for PV Only sites or grid connection type != 1. Accepted values are 1 – Import Only, 2 – Export Only
      • third_party_storage_device_installed: Applicable for sites without Encharges. Accepted values are true and false
      • third_party_storage_device_manufacturer: Accepted values are Tesla, Sonnen, LG Chem, Franklin, Others

What's new

  • FAQ page added to the developer portal
  • A new endpoint added to provide last reported power GET /api/v4/systems/{system_id}/latest_telemetry:
    • Returns a system's last reported PV Power, Consumption Power, and Battery Power in Watts. If the last_report_at is older than 7 days for a specific device, “last_report_at”, “power” and “operational_mode” parameters will be returned in the response with the value as null.
  • Enhancements to System Summary Endpoint
    • Added battery_charge_w, battery_discharge_w, and battery_capacity_wh fields to the systems summary

What’s new

  • Updated the Expiry time for refresh tokens
    • We recently updated the expiry time for Refresh tokens from 1 week to 30 days for all the Enphase Developer Portal applications. We have now extended this change to both new and old applications
  • Added product_name field to fetch devices endpoint
    • A new field named ‘product_name’ has been added to the response of the fetch devices endpoint with Datatype as a string
  • Corrected device counts in the telemetry endpoints
    • A bug in the telemetry endpoints was causing the device count to be incorrect. The bug was fixed by updating the logic to consider both the device’s last report time and the interval start time.

What’s new

  • GET /api/v4/systems and POST /api/v4/systems/search endpoints will always return the following 3 fields as -1: energy_lifetime, energy_today, system_size
  • Live Status API will show battery mode as ‘DR Event Active’ if the site has an ongoing Grid Services Event
    • If the Live Status API is called when a Grid Services DR Event is ongoing for a site, the battery mode is shown as ‘DR Event Active’
    • If the Live Status API is called when there is no active Grid Services DR Event, the battery mode is shown as per the default homeowner settings
  • Userswill receive an ‘API Key –Client mismatch’ error if the API Key and the Client ID are of 2 different applications
    • For all the APIs, users shall receive the following error if API Key and Client ID are of 2 different applications
      {"message": "API Key -Client mismatch","details": "API Key and Client ID of the access token do not match", "code": 401}
  • Added ‘Forgot your password’ link to HO OAuth login page
  • Updated error message when user requests unimplemented methods
    • Users shall receive '501 not implemented' error message when the requested method is not in POST, PUT, GET, DELETE, HEAD, OPTIONS, PATCH
    • This error message shall apply to all the endpoints on the v4 developer portal

What’s new

  • Added “Live Status” endpoint to provide real-time data for up to 300 seconds
    • API users can get real-time live status data on demand for a given system similar to the Enphase App.
    • Users can retrieve real-time power for PV Production, Grid Import/Export, Consumption, Battery Charge/Discharge, and Generator.
    • Users can also retrieve Grid Status, Battery Mode, and Battery State of Charge.
    • Users will receive the stream for a duration of 30 seconds by default. Users can configure the time in seconds by passing ‘duration’ as a parameter with a minimum value of 30 and a maximum value of 300.
    • The live status API will be supported only for sites with IQ Gateway version ≥ 6.0.0.

What’s new

  • Similar to the System Installer and Maintainer roles, the Authorized Subcontractor of a site will have access to all endpoints on the Enphase Developer Portal if subscribed to the Partner plan.
    • Users subscribed to the Partner plan can access all the endpoints listed on the Enphase Developer Portal if the user’s company is an authorized subcontractor for the site.
  • Telemetry APIs will return an empty list if the user asks for data between the last reported interval and the current time.
    • For the telemetry endpoints, users will see 200 responses with empty list if the "last interval" < "requested start time" < "current time" instead of "request date range is invalid for this system error"
    • This change is applicable for the following endpoints:
      • GET /systems/{system_id}/telemetry/production_meter
      • GET /systems/{system_id}/rgm_stats
      • GET /systems/{system_id}/telemetry/production_micro
      • GET /systems/{system_id}/telemetry/battery
      • GET /systems/{system_id}/telemetry/consumption_meter
      • GET /systems/{system_id}/devices/encharges/{serial_no}/telemetry
      • GET /systems/{system_id}/devices/acbs/{serial_no}/telemetry
      • GET /systems/{system_id}/devices/micros/{serial_no}/telemetry
      • GET /systems/{system_id}/energy_import_telemetry
      • GET /systems/{system_id}/energy_export_telemetry

What’s new

  • Updated API documentation for GET /api/v4/systems/config/{system_id}/battery settings endpoint
    • Updated description for battery_mode in the API documentation: “Current battery mode of the system. Possible values are Savings Mode, Full Backup, and Self – Consumption”
  • Updated response of GET /api/v4/systems/config/{system_id}/grid_status
    • API will return grid_state as:
      • “On Grid” if the site is connected to the grid
      • “Off Grid” if the site is not connected to the grid
      • “Unknown” if the site grid status is not known
  • Pagination option introduced to “List of systems” page on HO Authorization screen
    • On the ‘List of systems’ page, users can now see list of systems in a paginated format with a default page size of 100.
    • Users will have the ability to navigate between pages by clicking the “Next” or “Previous” buttons. Alternatively, users can enter a specific page number into the URL to go directly to that page.

What’s new

  • Added new endpoints under API group 'System Configurations'. List of endpoints
    • PUT /systems/config/{system_id}/battery_settings
    • PUT /systems/config/{system_id}/storm_guard

What’s new

  • Added new API group 'System Configurations' under Megawatt and Partner plan. List of endpoints
    • GET /systems/config/{system_id}/battery_settings
    • GET /systems/config/{system_id}/storm_guard
    • GET /systems/config/{system_id}/grid_status
    • GET /systems/config/{system_id}/load_control
  • Added new endpoints under 'Site Level Consumption Monitoring' API group. List of endpoints
    • GET /systems/{system_id}/battery_lifetime
    • GET /systems/{system_id}/energy_import_lifetime
    • GET /systems/{system_id}/energy_export_lifetime
    • GET /systems/{system_id}/energy_import_telemetry
    • GET /systems/{system_id}/energy_export_telemetry
  • Duplicate site name validation added for 'Create new Activation' API. Below conditions are
    • Any two sites can not have the same name and same owner email ID.
    • For a given site owner, creating a new site or updating an existing site - with an identical name to some other site is not allowed.
  • Added a new field 'config_type' under meters for the 'Retrieve devices' API.

What’s new

  • Added a new field reference and other_references in the /api/v4/systems endpoint. If the calling user belongs to a company and that company has provided its own identifier for a system, that ID is called reference. If any other companies have provided their own identifiers for a system, those identifiers are called other_references.
  • Added a new field emu_sw_version under gateways in the /api/v4/systems/{system_id}/devices endpoint. It is the firmware version of the gateway for a given site.
  • Added a new field energy_lifetime, energy_today and system_size in the /api/v4/systems endpoint. energy_lifetime is the energy generated by the system during its lifetime in Wh, energy_today is the energy generated by the system today in Wh, and system_size is the size of the system.
  • Support for 5 minutes intervals of telemetry data has been added for following endpoints. For systems configured for 5 minutes, 5 minutes telemetry data intervals can be generated by passing interval_duration in the request parameter.
    • /systems/{system_id}/telemetry/production_meter
    • /systems/{system_id}/telemetry/production_micro
    • /systems/{system_id}/telemetry/battery
    • /systems/{system_id}/telemetry/consumption_meter
    • /systems/{system_id}/devices/encharges/{serial_no}/telemetry
    • /systems/{system_id}/devices/acbs/{serial_no}/telemetry
    • /systems/{system_id}/devices/micros/{serial_no}/telemetry

Throttling limits for PUT, POST and DELETE endpoints under partner plan

  • For each of the PUT, POST and DELETE endpoints under partner plan, throttling limit is 200 hits per month now. Each of the GET endpoints under the partner plan are not impacted.

What’s new

  • Added a new field last_reported_aggregate_soc in the /api/v4/systems/{system_id}/telemetry/battery endpoint. It is the latest aggragate SOC value of all the batteries for a given site.
  • Added a new field last_reported_time and last_reported_soc in the /api/v4/systems/{system_id}/devices/acbs/{serial_no}/telemetry and /api/v4/systems/{system_id}/devices/encharges/{serial_no}/telemetry endpoint. last_reported_time is the timestamp (in epoch format) at which the device last submitted a report and last_reported_soc is the latest SOC value reported by the device.
  • Added a new field company_id in the /api/v4/users/search endpoint. It is the Enlighten ID of the company that the user belongs to. If the user does not belong to a company, this field will not be present in the response.

Enphase API v4 is released

Enphase API v4 is released with the following improvements over Enphase API v2

  • Enphase API v4 adheres to OAuth 2.0 protocol for authorization with grant_type as authorization_code for Monitoring APIs and grant_type as password for commissioning APIs.
  • Each API request must include OAuth2 access_token and API key as inputs, this enables an application to get access to Enphase systems data in a secured and simplified manner.
  • API v4 provides access to battery level and microinverter level data, in addition to site level production and consumption monitoring data.
  • API v4 supports fine grained access control, giving the application developers the ability to choose access control for each application.
  • Installer specific 'Partner Plan' is self-serve and gives access to commissioning APIs for their installed and maintained systems. Only registered Enphase installers with at least 10 installations can sign up for Partner plan.

Enphase API v4 and Enphase API v2 parity

  • /api/v2/systems/{system_id}/stats is now replaced with /api/v4/systems/{system_id}/telemetry/production_micro
  • /api/v2/systems/{system_id}/consumption_stats is now replaced with /api/v4/systems/{system_id}/telemetry/consumption_meter
  • /api/v2/systems/{system_id}/inventory is now replaced with /api/v4/systems/{system_id}/devices
  • /api/v2/systems/{system_id}/summary is now replaced with /api/v4/systems/{system_id}/summary
  • /api/v2/systems/search_system_id is now replaced with /api/v2/systems/retrieve_system_id
  • /api/v2/systems/{system_id}/envoys, /api/v2/systems/{system_id}/monthly_production are now deprecated
  • Following endpoints are the same in API v4 as in API v2:
    • /systems/{system_id}/consumption_lifetime
    • /systems/{system_id}/energy_lifetime
    • /systems/inverters_summary_by_envoy_or_site
    • /systems/production_meter_readings
    • /systems/{system_id}/rgm_stats
    • /systems/summary

Date range restrictions are imposed on telemetry APIs.

  • The requested start date must be within 2 years from current date for the following endpoints: /systems/{system_id}/rgm_stats, /systems/{system_id}/telemetry/production_micro, /systems/{system_id}/telemetry/production_meter, /systems/{system_id}/telemetry/battery, /systems/{system_id}/telemetry/consumption_meter, /systems/{system_id}/devices/micros/{serial_no}/telemetry, /systems/{system_id}/devices/acbs/{serial_no}/telemetry, /systems/{system_id}/devices/encharges/{serial_no}/telemetry
  • The total duration requested can not be more than one week, for the following endpoints: /systems/{system_id}/telemetry/production_micro, /systems/{system_id}/telemetry/production_meter, /systems/{system_id}/telemetry/battery, /systems/{system_id}/telemetry/consumption_meter, /systems/{system_id}/devices/micros/{serial_no}/telemetry, /systems/{system_id}/devices/acbs/{serial_no}/telemetry, /systems/{system_id}/devices/encharges/{serial_no}/telemetry