Pearl Certification Developer Documentation

Pearl Solar Equity Calculator

Pearl’s Solar Equity Calculator can show your customers how much value a solar installation can add to their home when they refinance or sell.

Solar Equity Calculator

The following guide will walk you through how to integrate with Pearl’s equity calculator.

The resulting output will be the value the solar system could add to the value of the home. The data provided by this tool is intended for reference in the appraisal process; the indicated value range is an estimate, and is not a guarantee of any specific sale price or valuation for the home or its features. Bear in mind that this is just an overview. Complete information about the referenced endpoints can be found at https://api.pearlcertification.com/.

Create a home and request the equity value - average utility rate

  1. Create a home using the /homes endpoint. The only data required is the home address. Pearl will validate the address and create a new home record. The response will include a home id. This home id will be used throughout the certification process.
  2. Add solar panel data to the home using the /homes/{home_id}/solar_panels_and_arrays/ endpoint. A successful response will include the asset_id which can be used to update the asset or retrieve the details for that particular asset. The more data provided the more accurate our equity estimation, however we only require three solar panel fields for us to generate an equity value. We must receive the following fields:
    • system size
    • type of ownership
    • utility or utility rate
  3. Add solar inverter data to the home using the /homes/{home_id}/solar_inverters/ endpoint. At a minimum we must receive the solar inverter type to generate an equity value. For power optimizers we recommend setting up two inverters, one as a power optimizer and one as a string inverter.
  4. [Optional] Add power production information using the /homes/{home_id}/power_production_warranty/ endpoint. We do not require data on the power production warranty to generate an equity value, but it will provide a more accurate value.
  5. [Optional] Run QA checks. Pearl runs a series of quality checks prior to generating an equity value. Leverage the /homes/{home_id}/qa_results/ endpoint to run those checks prior to generating an equity value.
  6. Generate an equity value for the home by calling the /homes/{home_id}/solar_valuation/ endpoint. We will return an expected value as well as a low and high value.

Create a home and request the equity value - specific utility plan

The following guide will walk you through how to integrate with Pearl’s Solar Equity Calculator using a specific utility plan and the electric load of the home for the calculations.

When calculating an equity value using a specific utility plan energy storage for the home can be added into the calculation. An energy storage asset is optional, but the steps below the option to add an energy storage asset.

The resulting output will be the value the solar system could add to the value of the home. The data provided by this tool is intended for reference in the appraisal process; the indicated value range is an estimate, and is not a guarantee of any specific sale price or valuation for the home or its features. Bear in mind that this is just an overview. Complete information about the referenced endpoints can be found at https://api.pearlcertification.com/.

  1. Create a home using the /homes endpoint. The only data required is the home address. Pearl will validate the address and create a new home record. The response will include a home id.

  2. The specific utility plan ID will be necessary when creating the solar panel asset. To retrieve the specific utility name and plan name call the GET /homes/{home_id}/specific_utility_plan_providers endpoint. When the correct utility plan is identified the external_id of that plan will need to be passed as a value in the solar_panel_and_arrays endpoint.

  3. Add solar panel data to the home using the /homes/{home_id}/solar_panels_and_arrays/ endpoint. A successful response will include the asset_id which can be used to update the asset or retrieve the details for that particular asset. The more data provided the more accurate our equity estimation, however not all fields are required s to generate an equity value. For a calculation using a specific utility plan we must receive the following fields:

    • system size (system_size)
    • type of ownership (ownership)
    • Utility plan type (utility_plan_type = specific_utility_plan)
    • Specific utility plan external id (specific_utility_plan)
    • Energy bills (energy_bills)

  4. Add solar inverter data to the home using the /homes/{home_id}/solar_inverters/ endpoint. At a minimum we must receive the solar inverter type to generate an equity value.

    • For power optimizers we recommend setting up two inverters, one as a power optimizer and one as a string inverter.

  5. [Optional] Add power production information using the /homes/{home_id}/power_production_warranty/ endpoint. We do not require data on the power production warranty to generate an equity value, but it will provide a more accurate value.

  6. [Optional] Add one or multiple energy storage devices using the /homes/{home_id}/energy_storage/ endpoint. We do not require data on an energy storage device to generate an equity value, but if the home has energy storage including the asset will provide a more accurate value. At a minimum the type, capacity and power_rating are required fields.

  7. [Optional] Run QA checks. Pearl runs a series of quality checks prior to generating an equity value. Leverage the /homes/{home_id}/qa_results/ endpoint to run those checks prior to generating an equity value.

  8. Generate an equity value for the home by creating a POST to the /homes/{home_id}/solar_valuation/ . We will return an expected value as well as a low and high value. We will also include disclaimer language which should be displayed along with the equity value.

Updating a home record and requesting a certification

After The system installation is complete the home record should be updated and a certification request created. Since the home record was created to generate an initial equity value we will follow a series of steps to update that home record and request a certification.

  1. Add homeowner contact information. Add contact information via the /homes/{home_id}/contacts/ endpoint. A home should have at least one contact with a valid email address to send the certification request.
  2. To update an asset a post request should be made to the appropriate endpoint. For example, to update a solar panel a post request should be made to the /homes/{home_id}/solar_panels_and_arrays/{id}/ endpoint.
    1. Information provided during an initial equity calculation should be checked for accuracy post installation and updated as appropriate.
  3. [Optional] Add additional asset data to the home record. Every asset has its own endpoint which is documented in detail here. For example, to add information on an energy storage device you will use the /homes/{home_id}/energy_storage/ endpoint.
  4. [Optional] Add photos or supporting documents to the home record through the /homes/{home_id}/files/ endpoint. Photos can add additional customization to the certification report by showing the homeowner exactly what was installed in their home. Documentation is used to speed the QA process and provide homeowners more information on what assets are in their home.
  5. A “Front of Home” picture helps customize the certification report for your customers, and is highly recommended. To add a front of home picture you will set the category field to front of home and the tags field to the Certification Report (CR).
  6. To add a photo to a specific asset the category field needs to be set to the asset token and the tags field will be CR. The asset token is returned in the successful response when an asset is created or can be obtained through using the OPTIONS method in this endpoint. Only one photo per asset can be tagged to the CR.
  7. To add documents to a specific asset the category field should be set to the asset token and the tags field should be left blank.
  8. [Optional] Run QA checks. Pearl runs a series of quality checks prior to certifying a home, the /homes/{home_id}/qa_results/ endpoint lets us run those checks before submitting a request and resolve any potential issues. If you decide to skip this step a Pearl representative will reach out during the certification review process if there are any questions on the home record.
  9. Submit the certification request using the /homes/{home_id}/certification_requests/ endpoint. . The customers_on_report` field should be set to the contact ID of the individual(s) whose name(s) you want to appear on the report as the homeowners. The contact ID is provided in the response for the contacts endpoint or can be found using the OPTIONS method in this endpoint.
  10. The cert_email_recipents field should include all the email addresses that you would like to receive the certification report.
  11. The collateral_package, notes_for_pearl, low_income_job and retro_cert fields can all be left blank.

That’s it! Once the certification has gone through Pearl’s QA/QC process we will email the certification to the certification recipient. To check on the status of a request you can use the /homes/{home_id}/certification_requests/{request_id} endpoint.