Multi-Structure Workflow for Integrations
Overview
Hover has recently enhanced its platform to support the capture of multiple structures (models) within a single property (job), as well as multiple levels of a single structure. Previously, each structure or level required a separate job, but with these architectural improvements, users can now capture comprehensive property data more efficiently.
Exterior Captures: Users can capture multiple structures (e.g., a house, detached garage, barn, shed) at a single address within one Hover job.
Interior Captures: Users can capture multiple levels of a house within one Hover job.
These enhancements necessitate updates to existing integrations to fully support the new multi-structure and multi-level workflows. Hover has introduced new versions of existing endpoints, new webhook events, and updated workflows to facilitate this initiative.
Before you get started, there are a couple of things to keep in mind:
- This workflow is optimized for capturing multiple structures or levels at a single property address.
- The endpoints described in this guide are required for processing jobs that include multiple structures or multiple interior levels. While not required for single-structure or single-level captures, these endpoints remain fully compatible with those use cases.
Limited Release Functionality
Enabling this new workflow requires special configuration on your Hover account. Please work with your main Hover point of contact to enable this functionality.
Existing Job Workflow
Historically, Hover integrations have operated on a one-to-one ratio between jobs and structures. This means that each physical structure on a property—whether it be a house, a detached garage, a barn, or a shed—required a separate Hover job. For example, if a property included both a house and a detached garage, the integration would need to create and manage two separate Hover jobs. Each job would have its own capture request, unique job ID, processing status, and deliverables.
Challenges with the Previous Workflow
While this approach ensured that each structure was processed individually, it has also introduced several inefficiencies:
- Managing Multiple Capture Requests or Jobs– Integrations have needed to create multiple jobs for a single property.
- Data Fragmentation – Each job generated its own independent data set, requiring additional effort to consolidate reports, measurements, and deliverables across multiple jobs.
- Potential Breakpoints – Since each structure relied on separate API request(s) and response cycle, failures in job creation, processing, or retrieval could disrupt workflows and introduce inconsistencies.
- User Experience Challenges – End users, such as field teams or insurance adjusters, had to manage multiple jobs per property, adding extra steps to their workflow and increasing the risk of errors.
These limitations have made it difficult for organizations to efficiently capture and manage properties with multiple structures. To address these challenges, Hover has introduced a multi-structure and multi-level capture system, which significantly streamlines the integration process.
New Multi-Structure/Multi-Level Workflow
Key Changes and Concepts
Hover Models
With the introduction of multi-structure and multi-level captures, Hover has redefined how jobs and their data are structured. A key concept in this new workflow is the model. Instead of a one-job-per-structure approach, a single job can now contain multiple models, each representing an individual structure (e.g., house, detached garage, shed) or level (e.g., first floor, second floor).
Hover App Mobile Experience
The user interface within the Hover mobile application has been upgraded to accommodate capturing multiple structures or levels in one capture session. At the end of capturing the first structure or level, a user will be prompted to continue the capture process.

Add a room or level
button offers users the ability to continue a multi-level capture for an Interior job.

Add another structure
offers users the ability to continue a multi-structure capture for an exterior job.
New Endpoints Available
Show Job Details
We have introduced a new version of the Show Job Details endpoint. The response body for this endpoint is designed to provide an integration the data and resources it needs, including general property information, data on the capture session, and model-level deliverables, exports, and images. The new endpoint path is:
GET https://hover.to/api/v3/job/{job_id}
This endpoint's response body contains all job and model information, including:
- General property information
- Address, External Identifier, and other high-level job details
- Capture Session Information
- The user who captured the model(s).
- The deliverable and capture type of the specific model(s) that were captured.
- Model data for each structure (exterior) or level (interior) that was captured during the capture session
- Model name, deliverable, and model state.
- Link to the Hover 3d Model
- Link to deliverables and artifacts
- Links to images taken during the capture process for that model
"Current User" Parameter Required
This endpoint, along with the URLs returned for each of the deliverables in the
artifacts
array requires either acurrent_user_id
orcurrent_user_email
query parameter appended to your API request. The value of this parameter must match a Hover user with access to this job and the associated models.
Deliverable Change Requests
Additionally, there are new endpoints for managing Deliverable Change Requests. Previously, upgrading a job's deliverable was done on a per-job basis. With these changes, deliverable changes are done at the model level, using the desired model_id
within a job.
- Get Upgrade Price -- Allows an integration to view the price to upgrade a model's deliverable.
- List Deliverable Change Requests -- View all deliverable change requests for a given
model_id
. - Create a Deliverable Change Request -- Upgrade a model's deliverable.
- Delete a Pending Deliverable Change Request -- Delete a model's pending Deliverable Change Request.
The allowed deliverable upgrades are below:
Deliverable type | Can be upgraded to |
---|---|
Capture Only (7) | Roof only (2) or Complete (3) |
Roof Only (2) | Complete (3) |
Complete (3) | Cannot be upgraded |
TLA (6) or TLA+ (5) | Roof only (2) or Complete (3) |
Interior (8) | Cannot be upgraded |
New Webhook Events
job-state-changed-v2
These new webhook events reflect the reconstruction state of a parent-level job. The available states have been simplified from the previous job-state-changed
events:
State | Description |
---|---|
draft | Waiting for a model's photos to be captured and sent to Hover. |
requested | A capture request for a job has been sent to a user. |
uploading | The uploaded data is being submitted to our processing pipeline. |
working | Reconstructing the 2D images uploaded into a photo-realistic 3D model and measurements. |
waiting_approval | The user that uploaded this job must get approval from their organization's administrator before the job will progress. |
processing | Finalizing the reconstruction process. |
paying | Collecting payment for the property. |
completed | The property was successfully processed by Hover. All deliverables are available. |
failed | This job could not be processed. |
Updated about 1 month ago