Guides

Capture Requests and the Hover API

Suggest Edits

Overview

This guide provides comprehensive information on utilizing Hover's API for Capture Requests, a powerful feature that streamlines the process of initiating property captures and integrating the resulting data into your business systems.Capture Requests are a key mechanism in Hover's workflow. They simultaneously:

  • Create a Draft Job: A preliminary job entry is automatically generated in your Hover account.
  • Prompt User Action: A text message or email is sent to designated users, guiding them to download the Hover app and capture the specified structure. All Hover captures must be performed on a mobile device.

This process simplifies the initiation of property measurements and data collection, allowing for efficient management of your projects within the Hover ecosystem.

Common Workflows

Many Hover customers leverage Capture Requests within existing business processes, often involving a Claims Management System (CMS) or a Customer Relationship Management (CRM) tool, alongside various lead capture tools.


We generally recommend directing all data from your lead capture tools into your central CMS/CRM. From there, a specific trigger event within your CMS/CRM can initiate a request to Hover's Capture Request endpoint.


Sending Capture Requests using Hover's API

To trigger a Capture Request, send a POST request to the Capture Request endpoint. This will create the draft job and send the notification to the capturing user:

POST https://hover.to/api/v2/capture_requests

Required Parameters

The following parameters must be included in your request body for it to succeed:

  • capture_request[capturing_user_name]
  • capture_request[capturing_user_email]
  • capture_request[job_attributes][location_line_1]
  • current_user_email or current_user_id

Optional Parameters

While not explicitly required to create the Capture Request object, the more information you include in your Capture Request, the less manual entry the user will need to perform later. We recommend passing in as much data as you have that aligns with the data that the Capture Request endpoint can ingest.

Important Note on Phone Numbers: If you wish for users to receive SMS text messages with the link to capture the Hover, you must include capturing_user_phone in your request.

Customizing User Communication

By default, it is not possible to customize the message content sent directly with the Hover Capture Request text or email using the API. However, you have the option to receive only the Capture Request link in the API response. You can then use this link within your own communication channels (e.g., your own SMS or email system) to send custom messages to the user.

Understanding Capture Request States

Once a Capture Request endpoint is successfully created, a draft job is generated in your Hover Properties page, and a notification is sent to the designated capturing user. As the user interacts with the request, its state within Hover's system changes:

new: The capture request has been sent and the assigned user has not signed up for a Hover account.

connected: The user assigned to the capture request has signed up for Hover or an active Hover account associated with their email address.

complete: The capturing user has captured the assigned property.

deleted: The capture request was deleted before the property was captured.

Integrating Hover Data into Your Business Systems

After a job is captured and subsequently processed by Hover (meaning all generated data like measurements, 3D model, etc., are ready), you can retrieve this valuable information and integrate it into your business systems, such as your CMS/CRM.

We almost always recommend an events-based architecture when building an integration with Hover. With this in mind, Hover has the capability to send your integration events when various actions take place in the platform through webhooks. Specific to Capture Requests, there are three different event types that are important to ingest:

Capture Request State Changed -- notifies your integration when a capturing user has signed up for Hover or completed the property capture.

Job State Changed -- this event notifies your integration when passes through a specific state in Hover's reconstruction pipeline. Specifically, the completed event type notifies

Model State Changed -- this event provides model-specific webhook events, allowing your integration to be notified when one specific model has completed or failed while being processed by Hover. You can use the model_id in the webhook payload to make subsequent API requests for different data types in Hover.

Hover offers a wide array of endpoints to access various types of job/model data, including:

  • Measurement PDFs
  • XLSX Data
  • JSON Data
  • Images
  • Checklists Data
  • Material List Data

By leveraging these endpoints in conjunction with webhooks, you can ensure your business systems are always up-to-date with the 3d property data being generated by Hover.

Updated 2 days ago