# 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](/partner-api/v1/apidocs/)

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:
1. HouseCanary will provide a url for retrieval
2. 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](https://en.wikipedia.org/wiki/Clean_URL#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](https://en.wikipedia.org/wiki/Clean_URL#Slug) `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
```