This intro to Order Manager API covers everything you need to know to start making calls for Agile Suite tools. By the end of this guide you’ll be able to test your API integration, create new orders, and troubleshoot common issues.
To access Order Manager via API, the user account tied to your authentication credentials must have permissions enabled for all API components you are trying to call. See which components are enabled for your user account in the “Analytics API” section of the Developer Center, your HouseCanary API settings page.
Follow these steps to create an API Key.
You can get there using the link at the bottom of the page at platform.housecanary.com.
Click the “New API Key” button to generate API credentials: an API Key and API Secret. Copy and paste them into a secure location or take a screenshot and store it safely. The API Secret cannot be retrieved again, and you will need both strings for every API call.
Please note that the Test API Keys shown are not available for the Order Manager API. You can conduct Order Manager integration tests using your API Key and Secret in the OM API demo environment, as we will explain later.
To access the API with Basic Authentication through your browser, use your API Key as the user name and your API Secret as the password. HTTPS must be used for all API requests.
Authentication failure results in requests rejected with status code 401 Unauthorized. Double-check that your user account has necessary API permissions for the request made.
Each user can have up to three API Keys and three Test API Keys at any given time. Usage limits are set at the organization level, not per user or per API Key. It’s up to you whether you would like to create one, two, or three API Keys and which API Key you would like to use for which requests. To remove an API Key, click the trashcan icon to its right, then confirm to delete. Once a Key and Secret have been deleted, they are no longer valid and cannot be retrieved.
For a deeper dive into the API for HouseCanary’s Agile Suite, refer to the Order Manager API documentation link provided beneath the API Keys box in Developer Center. (The Data & Analytics API link won’t be relevant unless you are also using Data Explorer via API.)
Once you have an API Key and Secret, you can start making API requests.
HouseCanary provides a test environment for developing an API integration at https://order-manager-api-demo.housecanary.com. Use the same production credentials acquired in the steps above. The demo environment has a service that automatically fills out and completes inspections for the following order types and addresses:
Using the above addresses, you can test orders with inspection in the demo environment. These addresses will return inspection portions automatically at no cost. For more information, refer to the documentation for Order Manager’s API demo environment.
There are two main entities within Order Manager: 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. To execute an order for a single address, send an Order with a single Order Item.
Status is tracked at the overall Order level, as well as at the Order Item level. This structure makes it easy for you to submit and track batches of addresses that we will process together.
To create an order from a CSV file, the endpoint /client-api/v1/orders/csv/ accepts a multipart/formdata POST. The POST must contain metadata about the order to execute, and a CSV file of addresses to use as Order Items.
Agile Evaluation is an exterior inspection performed by an inspection company followed by an automated condition informed valuation report. To use this order type, submit an order with the order_type field set to exteriorInspectionAndValueReport. The following fields are required when using this order type:
{
"address_string": "string",
"address_id": "string"
}
order_type
name
client_name
Required item fields:
addresszipcode or city and stateFor best results, download our Agile Evaluation sample CSV as a template for formatting your order information.
You can also create orders using JSON. The /client-api/v1/orders/json/ endpoint accepts an application/json POST. This post must contain metadata about the order to execute and the list of order items to include in the order.
If an error occurs, the response will contain the appropriate HTTP status code as described below. We do not charge for requests that result in the following status codes.
To check the status of any of the HouseCanary servers, visit the HouseCanary Status Page. You can also subscribe to RSS feed, email, or SMS updates from this page.
After successfully submitting an order request, you will get a response that repeats your information, and appends a HouseCanary ID for the order. Our system will perform automated checks to ensure that all items in your order are acceptable for the given order type. This may take some time.
After validation runs, the order items within the order will have process_item applied. Item by item status will be set to true, false, or null indicating whether they have passed or failed checks. Items that fail checks will not be processed until you review them.
true – all checks passedClientReview is triggered, in which case it will be executed after the reviewed order is marked accepted. false – some mandatory checks have failednull – overridable checks have failedIf fewer than 30% of addresses return errors, we will process the executable parts of the order and send you an email to inform you that you have items to review. If more than 30% of addresses return errors, we’ll pause the order until you review and make decisions.
Please note, client review emails for API requests using your Key and Secret go to the email address associated with your HouseCanary user account. Make sure to whitelist noreply@housecanary.com and check your email for order notifications.
If checks fail for an order item, or if ClientReview is triggered because more than 30% of the order items fail checks, a field called validation_results will be populated with warnings or errors for the checks that failed.
can_override is true – overridable error resultcan_override is false – irrecoverable error resultTo proceed you must approve the order items (if results are overridable); go line by line to approve or remove specific order items; or cancel the entire order. Use the following endpoints to proceed with order review:
/client-api/v1/orders/{order_id}/items/bulk/ process_item flag to true if the item has no error validation results.process_item flag to false to remove the item from the order/client-api/v1/orders/{order_id}/items/{order_item_id}/update/ to make changes to the Order Item address elements. Validation will run again after any order item changes/client-api/v1/orders/{order_id}/accept to resume order processing once all items are in the desired state/client-api/v1/orders/{order_id}/reject to cancel the order (reject processing) for any reason without a feeNote that once an order with inspection is in process, cancellation will result in a cancellation fee. Agile Insights cannot be cancelled once the order is processed.
The Agile Suite is at your command. Integrate our valuation and inspection tools into your systems to streamline your valuation workflow or offer a new toolkit to delight your customers.
For a software development kit (SDK) with further context and additional examples, visit our HouseCanary Order Manager SDK. If you have additional questions or need assistance, our support team will also be happy to help you.
Back to blog home
We build groundbreaking technologies to improve and accelerate residential real estate operations.
