Partner API

Introduction

This document provides information about using the HouseCanary Order Manager API as an Integration Partner acting on behalf of clients.

Basics

HouseCanary Order Manager provides a REST API for Integration Partners, for which detailed API documentation can be found below:

REST API docs

The Integration Partner model allows Integration Partners to act on behalf of clients in creating orders. In addition, Integration Partners will need to accept messages from HouseCanary, specifically order status updates and final delivery of assets.

Unless otherwise noted, all API endpoints accept and produce data in JSON format.

Within Order Manager, there are two main entities: Order and Order Item. An Order is a request to execute a particular service for a set of addresses, while an Order Item is a single line item (address) within an order. If you wish to execute an order for a single address, you would simply create an Order with a single Order Item contained within it.

Status is tracked at the overall Order level, as well as at the Order Item level. This structure is intended to allow easy submission of batches of addresses that should all be tracked together.

Authentication

API Authentication is token based. A token will be issued to you as part of the Integration Partner onboarding process.

Your token should be passed in the Authorization header of all API requests in the following format:

Authorization: Token {YOUR_UNIQUE_TOKEN} note that the word “Token” must be present for successful authentication

Requests for which authentication fails will be rejected with status code 401 Unauthorized.

Permissions

To utilize the HouseCanary Order Manager API, your account must be provisioned for access. Provisioning will be handled as part of the Integration Partner onboarding process.

In addition to the API Token discussed above, you will also receive a pair of ids (owner_organization_id, owner_id) representing accounts for whom you are an authorized agent. You will only be able to create orders on behalf of accounts for which you are authorized.

Callouts

As part of the order fulfillment process HouseCanary will send status messages pertaining to active orders. Integration Partners will need to provide an endpoint to accept these messages.

Order Delivery

Completed orders can be delivered one of two ways:

HouseCanary will provide a url for retrieval
HouseCanary will send all final order assets to the callout endpoint referenced above.

Delivery preferences will be discussed as part of the onboarding process.

Test (Demo) Environment

HouseCanary has a test environment for the development of API integrations at https://order-manager-api-demo.housecanary.com/partner-api/v1/. Credentials can be acquired using the steps above.

Creating an order

To create an order you will use the orders endpoint: /partner-api/v1/orders/

The orders endpoint accepts an application/json POST containing metadata about the order to execute and order items to include in the order.

Order types

Currently only Agile Insights orders are supported. Thus order_type should always be set to valueReport.

Agile Insights

This order type requests an automated valuation report. To use this order type, set the order_type field to valueReport when submitting an order. The following fields are required for orders when using this order type:

order_type
name

In addition the following are required for each order item in the order:

address
zipcode (Either zipcode or city and state are required.)
city (Either zipcode or city and state are required.)
state (Either zipcode or city and state are required.)

Order validation and review

Once an order is submitted, HouseCanary will perform validation on the order to ensure that all items are acceptable for the given order type. This validation is asynchronous since a number of the checks are time consuming.

If an order_item passes validation, then it will be executed immediately. Otherwise, it will be canceled from the order and a callout message will be sent detailing the validation checks that failed.

Order status updates

Once an order has been submitted (and review has been accepted if necessary) as described above, execution of the order will begin.

HC Order Manager has the capability to trigger callouts with updates to the order status as such updates occur. If you would like to enable such callouts please provide the following information to HouseCanary for account provisioning:

Callout URL - The URL to send notifications to.
Callout Authentication Scheme - The mechanism that will be used to authenticate callout requests (see below).

Callout Authentication

The following authentication schemes are supported.

Basic

HTTP Basic authentication. Please provide a username/password.

API Token (Header)

Authentication token passed in a HTTP header. Please supply the header name and token to use.

API Token (Query String)

Authentication token passed in a HTTP header. Please supply the parameter name and token to use.

Signature

HouseCanary will generate a HMAC to authenticate the payload of the message, passed in a HTTP header. Supply a secret used to authenticate the name of the header to pass the result in.

In this mode, assuming the signature header is defined to be X-HC-Signature each request to the callout URL will have a header of the following format:

X-HC-Signature: sha1=xxxxxxxxxxxxxxxxxx

where xxxxxxxxxxxxxxxxxx is equal to the HMAC-SHA1 of the payload.

Callout messages

Each of the following messages will be transmitted to the callout URL as a HTTP POST, using the authentication method configured. The callout handler is expected to process the request within 30 seconds, and return a HTTP 2xx status code. If a timeout occurs, or another status code is received, redelivery will be attempted up to 10 times, no less than 5 minutes apart.

Order status update

A message of format

{
    "message_type": "order_status_change",
    "message_id": "<unique message id>",
    "order_id": "<order id>",
    "customer_order_id": "<customer order id>",
    "new_status": "<status>",
    "external_integration_ids": ["id_0", "id_1", ...]  # List of order_item.external_integration_ids contained in this order
}

Order item status update

A message of format

{
    "message_type": "order_item_status_change",
    "message_id": "<unique message id>",
    "order_id": "<order id>",
    "customer_order_id": "<customer order id>",
    "order_item_id": "<order item id>",
    "customer_item_id": "<customerorder item id>",
    "new_status": "<status>",
    "external_integration_id": "<integration partner id>"
}

Order Complete Message

A message of format

{
    "message_type": "order_complete",
    "message_id": "<unique message id>",
    "order_id": "<order id>",
    "customer_order_id": "<customer order id>",
    "order_item_id": "<order item id>",
    "customer_item_id": "<customerorder item id>",
    "download_url": "<url>",
    "report": "encoded report blob",
    "external_integration_ids": ["id_0", "id_1", ...]  # List of order_item.external_integration_ids contained in this order
}

Export file format

The exported file name is based on the order name and when the order was completed. The exported file contents will depend on the order’s order_type. Below is the structure of each order type’s file.

order_download_name: HC_{sluggified_order_name}_{order_date}.{fmt} where sluggified_order_name is the order name converted to a slug. The order_date is completed date of the order, or if the order is not completed, today’s date (according to the ‘America/Los_Angeles’ timezone). The fmt will be the format passed to the create export endpoint.

order_item_file_prefix: {order_item_id}_{order_item_date} where order_item_id will be order item customer_item_id if available first, then the order item’s sluggified address (with -{unit} appended to it if the item has a unit). The order_item_date will be order item completion_date if available first, then the order’s actual_delivery_date if available next, and today’s date (according to the ‘America/Los_Angeles’ timezone) last.

valueReport order_type file structure

{order_download_name}
    |-- {order_item_file_prefix}_OrderItem.json (if exclude_json == false)
    |-- {order_item_file_prefix}_ValueReport.pdf