HouseRater allows 3rd party apps to integrate scheduling and invoicing software at your organization with HouseRater API services. This means houses can be enrolled automatically when external systems discover a house, or invoices can be generated immediately upon an inspection being completed in HouseRater.

Note: 3rd party apps and the HouseRater API is currently being tested with a limited number of rating companies, so you may need to contact us to enable the functionality described below.

Getting Started with HouseRater API

The HouseRater API uses a Client ID and Secret Key for authenticating requests, but you can exchange these keys to a time-limited Bearer token for added security.

Generating API Keys

You need to be an administrator of your company to generate API Keys. When signed into HouseRater, follow the steps below to generate or view your Client ID and Secret Key.

Open your "Account" page from the profile dropdown, or select your company from the Rating Companies page.
Select the "Edit Rating Company" button from the Account page.
In the menu to the side of the Save button, select "Manage API Keys" to generate or view your company's API Keys.

Once generated, your company will be able to interact with the HRT API in two different ways. Using the Client ID and Client Secret you will be able to generate OAuth Tokens to make HTTP requests from your internal tools, and you will gain access to GraphiQL which will allow you to test queries and mutations before putting them in to code.

GraphQL & GraphiQL

GraphQL is an API Architecture System developed by Facebook to allow smooth and customizable API Systems. HRT uses GraphQL to expose endpoints into the HRT Ecosystem.

GraphiQL is a visual web interface for writing and testing API queries before moving them into your application. The UI and architecture to GraphQL is open source, and integrated independently into HouseRater.

Before diving too deep in to this tool, we recommend reading through the documentation GraphQL provides. Reading the Introduction, and the information in "Queries & Mutations" will provide you with a good basis to get started with GraphiQL.

To access GraphiQL:

Navigate to your company's API Keys page using the steps above.
Click the "Launch GraphiQL" link from this page. You can also navigate to https://api.app.houserater.com/graphql to automatically be signed in.

All of the available mutations and queries we currently support are accesible through the docs section of GraphiQL on the right of the screen. Feel free to dive in to whats available, and let us know if there is anything you need that seems to be missing.

Integrating API Queries into your Software

After using GraphiQL to test queries, you can integrate them into your app using an application-specific access token and specific GraphQL network requests.

First, you'll need to retrieve a temporary Application Access Token using your Client ID and Secret Key. These access tokens last approximately 3 hours. To do so you will make a post request to https://auth.app.houserater.com/oauth/token.

POST https://auth.app.houserater.com/oauth/token HTTP/1.1

Headers:
    Content-Type: application/json

Body:
    {
        "client_id": YOUR_CLIENT_ID,
        "client_secret": "YOUR_CLIENT_SECRET",
        "grant_type": "client_credentials",
        "scope": "houserater"
    }

Return
    {
        "token_type": "Bearer",
        "token": "YOUR_OAUTH_TOKEN"
    }

Then with the access token you receive, you can make GraphQL queries as a 3rd party application, instead of a personal user.

POST https://api.app.houserater.com/graphql HTTP/1.1

Headers:
    Content-Type: application/json
    Authorization: "Bearer YOUR_OAUTH_TOKEN"

Body:
{
    "query": "query GetHouse($homeID:ID!){ houseByHomeId(homeId:$homeId) { address { line1 } } }",
    "variables": { "homeID": 100103 }
}

When a token expires, you will get a 401 Unauthorized error. When this happens all you need to do is regenerate an OAuth Token, and then send the request again with the token.

Creating Webhook Endpoints

Navigate to your company's API Keys page using the steps above.
Press the + button under Webhooks to open the create dialog box.
Enter the URL that you want to be triggered when events occur.
Select one or many of the supported HouseRater triggers, described below.

Supported Triggers

Site Inspection Status Change

Trigger: 
Any time a Site Inspection changes its status (Pending, Ready, Complete, etc.. This typically happens when the form is saved using the web or mobile app.

Data Sent: 
{
    "_id": DatabaseId,
    "origin": {
        "home": DatabaseId, // ref: house
        "createdBy": DatabaseId, // ref: user
    },
    "name": String, // type of inspection
    "status" String/Enum, // Pending, Ready, Complete, Dry Run, Missed
    "data": {
      "siteVisitDate": Date
      "orientation": {
        "selectedFiles": []
      },
      "insulation": {
        "foundation": {
          "exterior": {
            "selectedFiles": []
          },
          "interior": {
            "selectedFiles": []
          }
        },
        "slab": {
          "exterior": {
            "selectedFiles": []
          },
          "interior": {
            "selectedFiles": []
          }
        },
        "aboveGradeWalls": {
          "ambient": {
            "selectedFiles": []
          },
          "garage": {
            "selectedFiles": []
          },
          "knee": {
            "selectedFiles": []
          },
          "common": {
            "selectedFiles": []
          }
        },
        "cantileveredFloors": [],
        "attic": []
      },
      "nonVisibleInsulation": {
        "sections": []
      },
      "ductwork": {
        "attic": {
          "selectedFiles": []
        },
        "garage": {
          "selectedFiles": []
        },
        "basement": {
          "selectedFiles": []
        }
      },
      "buildingPlan": {
        "selectedFiles": []
      },
      "buildingPermit": {
        "selectedFiles": []
      },
      "meters": {
        "gas": {
          "selectedFiles": []
        },
        "electric": {
          "selectedFiles": []
        }
      },
      "mechanical": {
        "ceilingFans": {
          "selectedFiles": []
        }
      },
      "selectedFiles": [],
      "raters": [
        DatabaseId // ref user
      ],
      "backupData": [],
      "evaluatedItems": [],
      "pastEvaluatedItems": [],
      "radonSystems": [],
      "vaults": [],
      "rimBandJoists": [],
      "ranges": [],
      "spaceHeating": [],
      "waterHeating": [],
      "spaceCooling": [],
      "thermostat": [],
      "ventilation": [],
      "makeUpAir": [],
      "clothesWashers": [],
      "dryers": [],
      "dishWashers": [],
      "fridges": [],
      "fireplaces": [],
      "windows": [],
      "totalLeakageTests": [],
      "blowerDoorTests": [],
      "leakageToOutsideTests": [],
     }
}

Note: Inspection data template is more complicated than what is above. GraphQL will contain more data on inspection once CreateInspection is expanded
2. House Create

Trigger: 
Any time a house is created inside of HRT.

Data Sent: 
{
  "_id": DatabaseId,
  "homeId": Int, // Human readable id
  "ratingCompany": DatabaseId,
  "builder": DatabaseId,
  "createdBy": {
    "userId": DatabaseId,
    "name": {
      "first": String,
      "last": String
    }
  },
  "archived": Bool,
  "active": Bool,
  "locked": Bool,
  "complete": Bool,
  "requiresVerification": Bool,
  "address": {
    "line1": String,
    "city": "String,
    "state": String,
    "postal": String
  },
  "updatedAt": Date,
  "createdAt": Date
}

3. House Program Status Change

Trigger: 
Any time a house's status in a program changes inside of HRT.

Data Sent: 
{
  "id": DatabaseId, // ref HouseProgram
  "workflow": String,
  "status": {
    "name": String/Enum, // Pending, Enrolled, Submitted, Complete, Flawed, Disqualified
    "setOn": Date,
    "setBy": DatabaseId // ref user
  },
  "active": Bool,
  "program": DatabaseId, // ref program
  "house": DatabaseId // ref house
}