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.
Creating and managing API Keys
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.
Step 1: Go to Developer Center
You can get there using the link at the bottom of the page at platform.housecanary.com.
Step 2: Generate API credentials
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.
Step 3: Authenticate your credentials
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.
Conducting tests in the Order Manager Demo Environment
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:
- Agile Evaluation + Exterior Inspection: 14242 Clarissa Ln, Santa Ana, CA 92705
- Agile Evaluation + Interior Inspection: 513 E Ventura Ave, Clewiston, FL 33440
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.
Making API requests
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.
Example: Order Agile Evaluation with Exterior Inspection
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:
address- Either
zipcodeorcityandstate
For 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.
Troubleshooting submission errors
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.
- 400 – Missing required fields or incorrect request structure
A 400 Bad Request status code means that one or more required fields are missing in the request. Make sure that your data is formatted correctly by using our provided CSV template. - 401 – Authentication failure
In the case of an authentication failure, the system will return a 401 without any explanation or description. Please contact HouseCanary technical support if you have questions.
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.
Understanding the response
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 passed
The item will be executed immediately unlessClientReviewis triggered, in which case it will be executed after the reviewed order is marked accepted.
false– some mandatory checks have failed
The item will be marked as removed and will not be executed.
null– overridable checks have failed
The item will be marked as needing review and will not be executed until further action is taken.
If 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.
Resolving issues when items or orders fail checks
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_overrideistrue– overridable error result
can_overrideisfalse– irrecoverable error result
To 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/- toggle the
process_itemflag totrueif the item has no error validation results. - toggle the
process_itemflag tofalseto remove the item from the order
/client-api/v1/orders/{order_id}/items/{order_item_id}/update/to make changes to theOrder Itemaddress elements. Validation will run again after any order item changes
/client-api/v1/orders/{order_id}/acceptto resume order processing once all items are in the desired state
/client-api/v1/orders/{order_id}/rejectto cancel the order (reject processing) for any reason without a fee
Note 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.
Take your process to the next level with HouseCanary
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.
