Quick Start

The following guide walks a user through the general process of establishing a home in the Pearl Certification software, adding high-performing asset information to the home, and subsequently requesting a Pearl Certification for the home. 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 a certification

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.
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.
Add asset data to the home record. Every asset has its own endpoint which is documented in detail below. For a certification request a home must have at least one asset. The same asset may have multiple instances, for example, you may create two solar inverter assets if you installed two inverters in the home. A successful response will include the asset_id which can be used to update the asset or retrieve the details for that particular asset.
[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.
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 CR.
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 certification report (CR).
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.
[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.
Identify the appropriate collateral_package
- Make an OPTIONS call to /homes/{home_id}/certification_requests/. The reply should consist of a number of POST variables including collateral_package which should look something like this:
```
  "collateral_package": {
       "type": "field",
      "required": false,
      "read_only": false,
      "label": "Collateral Package",
      "help_text": "The values for this field can be determined with an OPTIONS call to the corresponding endpoint.",
      "choices": [
          {
              "value": 22,
              "display_name": "Pearl Certification Report Issued to Homeowners"
          }
      ]
  },
```
You will need to select the “value” of the collateral package you wish to issue with the certification report. It is likely the same value for all of your certification reports unless you are issuing different types of collateral packages to different types of customer. As of API version 5.0.0, if your firm only issues a single type of collateral package, then this may be omitted, and the only available collateral package will be used. However, it’s still recommended that you provide collateral package value to prevent breakage in the future if your firm decides to offer additional collateral packages.
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.
The cert_email_recipents field should include all the email addresses that you would like to receive the certification report.
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.