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

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 a current_user_id or current_user_emailquery 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.

The allowed deliverable upgrades are below:

Deliverable typeCan 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-changedevents:

StateDescription
draftWaiting for a model's photos to be captured and sent to Hover.
requestedA capture request for a job has been sent to a user.
uploadingThe uploaded data is being submitted to our processing pipeline.
workingReconstructing the 2D images uploaded into a photo-realistic 3D model and measurements.
waiting_approvalThe user that uploaded this job must get approval from their organization's administrator before the job will progress.
processingFinalizing the reconstruction process.
payingCollecting payment for the property.
completedThe property was successfully processed by Hover. All deliverables are available.
failedThis job could not be processed.