Client API

Introduction

This document provides information about using the HouseCanary Order Manager API to submit, track the status of and retrieve the results of orders.

API Versioning and Deprecation Policy

Versioning

The Order Manager API will adhere to the major.minor versioning format. The current API version is v1.

The major version number will rarely change as we reserve this for major changes, such as a complete redesign of the API.

The minor version number is incremented each time we introduce a breaking change. A breaking change is an update that may require you to make changes to your application to keep using the endpoint. Examples of breaking changes include changing the structure of the data returned from an endpoint, and changing the required inputs to an endpoint.

Note that when we add additional endpoints or optional parameters to endpoints, we do not update the version number because these simply add additional functionality, and should not break consuming apps.

Deprecation

When introducing a breaking change, we will support existing versions of the library for 6 months. We recommend moving to the latest version as soon as you can after a release.

We will notify customers of upcoming deprecations via email every month leading up to the deprecation.

REST API Documentation

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

REST API docs

A good example of how the REST API is used can be seen by using the HouseCanary Order Manager frontend available at https://order-demo.housecanary.com. This frontend uses the same API calls available in the REST API to accomplish all tasks, so viewing the calls made by this frontend can assist in developing an integration.

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

Basics

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

In order to use the HouseCanary Order Manager API, you must obtain a credentials pair (API Key, API Secret) from your settings page.

Authentication of API requests is made using HTTP Basic Authentication. Use your API Key as the user name and your API Secret as the password for Basic Authentication. HTTPS must be used for all API requests. See the full request examples below that show how to authenticate with the API in various programming languages.

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. Contact support-api@housecanary.com to request access.

The /client-api/v1/user/permissions API can be used to check whether the current user has permission to create orders.

Sandbox Environment

HouseCanary has a test set-up for the development of API integration. The sandbox environment needs to be provisioned. Please contact support-api@housecanary.com for access. Customer success will reach out to you with credentials, test details, and a path to the production steps.

Support

support-api@housecanary.com should be contacted for support for getting access as well as general questions.

Creating an order

To create an order, there are two APIs: /client-api/v1/orders/csv/ and /client-api/v1/orders/json/. Both endpoints require addresses to be split into their component parts. To split an address into its component parts, you may wish to use the /client-api/v1/address/parse/ endpoint (this endpoint uses a best effort algorithm to parse a given address, and commas can improve the quality of the parse).

Creating an order from CSV

The /client-api/v1/orders/csv/ endpoint accepts a multipart/formdata POST containing metadata about the order to execute and CSV file of addresses to create Order Items from.

Creating an order from JSON

The /client-api/v1/orders/json/ endpoint accepts a application/json POST containing metadata about the order to execute and order items to include in the order.

Order types

The following order types are currently supported. A list of order types supported can be fetched using the /client_api/v1/order_types endpoint. Depending on the permissions applied to your account, only a subset of the following order types may be available.

Broker Price Opinion - Exterior Inspection

This order type requests an exterior inspection performed by an inspection company followed by a review of valuations and analytics by a licensed broker to determine a property’s estimated value. To use this order type, set the order_type field to brokerPriceOpinionExterior when submitting an order. The following fields are required when using this order type:

order_type
name
client_name

Required item fields:

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.)

Agile Evaluation - Exterior Inspection

This order type requests an exterior inspection performed by an inspection company followed by an automated condition informed valuation report. To use this order type, set the order_type field to exteriorInspectionAndValueReport when submitting an order. The following fields are required when using this order type:

order_type
name
client_name

Required item fields:

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.)

Agile Evaluation - Interior Inspection

This order type requests an interior/exterior inspection performed by an inspection company followed by an automated condition informed valuation report. To use this order type, set the order_type field to interiorExteriorInspectionAndValueReport when submitting an order. The following fields are required when using this order type:

order_type
name
client_name
contact_name
contact_phone
contact_email

Required item fields:

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.)
inspection_contact_name
inspection_contact_phone
inspection_contact_email

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 when using this order type:

order_type
name

Required item fields:

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.)

Exterior Inspection

This order type requests an exterior inspection. To use this order type, set the order_type field to exteriorInspection when submitting an order. The following fields are required when using this order type:

order_type
name

Required item fields:

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.)
property_type Valid options: singlefamily, condo, multifamily, mobile

Interior Inspection

This order type requests an interior/exterior inspection. To use this order type, set the order_type field to interiorExteriorInspection when submitting an order. The following fields are required when using this order type:

order_type
contact_name
contact_phone
contact_email

Required item fields:

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.)
inspection_contact_name
inspection_contact_phone
inspection_contact_email
property_type Valid options: singlefamily, condo, multifamily, mobile

Order Statuses

After order creation, an order can be in one of the following statuses:

“New” - the order has just been created, inital processing is not yet complete
“ClientReview” - the order is paused pending client review. Certain customers have a custom configuration where their orders will enter this manual review state if the percentage of items with issues crosses a certain (customizable) threshold.
“Accepted” - inital processing and validation of addresses is complete
“CancelPending” - client has requested an order cancellation but that request has yet to be confirmed
“Cancelled” - client has requested an order cancellation and that request has been accepted/is complete
“Complete” - order is complete (all items selected for processing have been completed or cancelled)

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.

After validation runs, the order items within the order will have the following logic applied:

process_item will be set to true, false, or null.

If process_item is true, the item will be executed immediately if ClientReview is not triggered, or after the order is marked accepted if it is. This status indicates that all checks passed.
If process_item is false, the item will be marked as removed and will not be executed. This status indicates that some mandatory checks have failed.
If process_item is null, the item will be marked as needing review and will not be executed until further action is taken. This status indicates that overridable checks have failed.

In addition, a field called validation_results will be populated. This field contains results about the checks that failed. Each result will either be a warning or an error. Overridable results will have the can_override field set to true. Irrecoverable error results will have the can_override field set to false.

At this point, the /client-api/v1/orders/{order_id}/items/bulk/ endpoint can be used to toggle the process_item flag to true (if the item has no error validation results) or false (if the item should be removed from the order). If changes need to be made to the Order Item address parts, they can be made with the /client-api/v1/orders/{order_id}/items/{order_item_id}/update/ endpoint. Validation will re-run after any order item changes.

For Orders with ClientReview status, once all items are in the desired state, the /client-api/v1/orders/{order_id}/accept endpoint can be used to resume processing of the order. If for some reason order cancellation is desired at this point, the /client-api/v1/orders/{order_id}/reject endpoint can be used. If the order is cancelled in this manner, no fees will be charged.

Order status updates webhook

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>"
}

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>"
}

Comment notification

A message of format

{
    "message_type": "comment_received",
    "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>",
    "comment": "<comment message>"
}

Order Export

Since orders can be quite large in volume, we generate the completed order files asynchronously. To export (aka generate) and then download order files:

Create a new export job: The /client-api/v1/orders/{order_id}/export/{fmt} endpoint accepts a POST and returns (among other things) a check_status_url.
Poll the check_status_url url which accepts a GET.
When the status field of the check_status_url response has value: completed, the download is available at the url provided in the exported_data field.

If you want to re-download an order that has not changed, the list export jobs endpoint at /client-api/v1/orders/{order_id}/export-requests/ will display previous export requests. Use the exported_data url to download the files again.

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.

brokerPriceOpinionExterior order_type file structure

{order_download_name}
    |-- {order_item_file_prefix}_OrderItem.json (if exclude_json == false)
    |-- {order_item_file_prefix}_BPOReport.pdf
    |-- {order_item_file_prefix}_BPOReport.json
    |-- {order_item_file_prefix}_Inspection.json (if exclude_json == false)
    |-- {order_item_file_prefix}_Photos
        |-- {inspection_image_name}

exteriorInspectionAndValueReport order_type file structure

{order_download_name}
    |-- {order_item_file_prefix}_OrderItem.json (if exclude_json == false)
    |-- {order_item_file_prefix}_AgileEvaluationReport.pdf
    |-- {order_item_file_prefix}_AgileEvaluationReport.json
    |-- {order_item_file_prefix}_Inspection.json (if exclude_json == false)
    |-- {order_item_file_prefix}_Photos
        |-- {inspection_image_name}

interiorExteriorInspectionAndValueReport order_type file structure

{order_download_name}
    |-- {order_item_file_prefix}_OrderItem.json (if exclude_json == false)
    |-- {order_item_file_prefix}_AgileEvaluationReport.pdf
    |-- {order_item_file_prefix}_AgileEvaluationReport.json
    |-- {order_item_file_prefix}_Inspection.json (if exclude_json == false)
    |-- {order_item_file_prefix}_Photos
        |-- {inspection_image_name}

valueReport order_type file structure

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

exteriorInspection order_type file structure

{order_download_name}
    |-- {order_item_file_prefix}_OrderItem.json (if exclude_json == false)
    |-- {order_item_file_prefix}_Analytics.pdf
    |-- {order_item_file_prefix}_InspectionReport.pdf
    |-- {order_item_file_prefix}_Photos
        |-- {inspection_image_name}

interiorExteriorInspection order_type file structure

{order_download_name}
    |-- {order_item_file_prefix}_OrderItem.json (if exclude_json == false)
    |-- {order_item_file_prefix}_Analytics.pdf
    |-- {order_item_file_prefix}_InspectionReport.pdf
    |-- {order_item_file_prefix}_Photos
        |-- {inspection_image_name}

Export Order Item

Order item downloads are synchronous. The download from endpoint /client-api/v1/orders/{order_id}/items/{order_item_id}/download will be a zip file. The format of the file name will be as follows:

{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.

The contents and naming of the files within the zip will be specific to the order’s order_type, and will be the same as mentioned in the “Order Export - Export file format” section above.

Order Item Report Download

We provide an endpoint for downloading just the pdf report generated for an order item (without the additional json, photos, etc.) at /client-api/v1/orders/{order_id}/items/{order_item_id}/pdfdownload/{pdf_type}. To know which reports are available for download, there’s an attribute on the order item called available_downloadables (a list of order items can be retrieved from /client-api/v1/orders/{order_id}/items/). available_downloadables will be an array of objects. Each object will include a key attribute whose value is a unique id that can be used for the pdf_type param in the pdfdownload endpoint.

Errors

Order manager uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error with Order manager’s servers.

Order Item Level Error Codes

In addition to HTTP response codes, Order Manager API provides error codes at the Order Item level when an Order Item does not pass address validation. These are enumerated here.

Error level codes require corrective action before the Order Item can progress through the system whereas Warnings can be bypassed.

Code	Error/Warning	Description
1	Error	We could not locate the address specified
2	Error	Missing both the zip code and the city/state
3	Error	Unsupported Property Type
4	Error	Report unavailable due to sparse data
5	Error	HCCV for this property is not available
6	Error	Not a test address
7	Error	Home value is below threshold
8	Error	Loan amount exceeds threshold
9	Error	LTV exceeds threshold
10	Error	MLS data is not available for this property
11	Error	Report unavailable due to lack of data related to gross living area for this property
12	Error	Report unavailable due to lack of AVM coverage for this property
13	Error	FSD exceeds threshold
14	Error	Order type is not permitted in the locale
101	Warning	Duplicate address with another order
102	Warning	Duplicate address in the same order
103	Warning	Review address to ensure it is correct
104	Warning	Review Corrected Address
105	Warning	Property type does not match with HouseCanary data.
108	Warning	Duplicate Customer ID
111	Warning	Sparse data : MLS/public record lacking property info

Changelog

September 13, 2024: Create a capability to block specific locales from allowing BPO orders

Create a capability to block specific locales from allowing BPO orders

August 13, 2024: Add BPO order type

Add the Broker Price Opinion order type

June 3, 2024: Obsolete order type cleanup

Removed information related to obsolete order types (Agile Appraisals, Agile Evaluation Certified).

May 29, 2024: Added FSD threshold validation option for new orders

Added FSD threshold validation option for new orders with the range (0.00-1.00]

March 7, 2022: Removed obsolete order types

Removed order types that no longer exist (Agile Appraisals, Agile Evaluation Certified).

June 15, 2021: Increased detail for certain sparse data errors

Sparse data due to missing GLA or AVM has new error codes above.

November 19, 2020: MLS data availability check

Added new error code for order types that check MLS data availability

June 18, 2019: Remove default automatic order pausing

Once an order is submitted, HouseCanary will perform validation on the order to ensure that all items are acceptable for the given order type. Previously, if the validation check found a certain percentage (at or above 30%) of items to have warnings or errors, the whole order was automatically paused pending further review from the customer. On June 18th, we removed this automatic pausing by default. This feature is still available by request, and the warning/error threshold is customizable.