Guides

Capture Requests and the Hover API

Suggest Edits

Why would I use this guide?

The aim of this guide is to clarify how to send Capture Requests via the API. Capture Requests simultaneously create a draft Job in your Hover account and send a text / email to users to prompt and guide them to download the Hover app and capture their structure. In this guide we will cover

  • How to trigger a Capture Request via the API
  • Which endpoints to use, and their required data
  • When in common workflow sending Capture Requests is recommended
  • How to leverage Hover webhooks
  • How to get the resultant data back into your systems.

After reading through this document, please feel free to work with our Solutions Engineering team for help tailoring this integration to your specific system, and for support answering any questions you may have.

Common Workflow Flow

Many of our customers follow similar workflows that can roughly be outlined with the diagram below. In this diagram you'll see the intervention points to hit Hover's API; read on to learn the details of how and why this integration flow is recommended.

Most Hover customers looking to leverage the API for Capture Requests use a (a) Claims Management System or a Customer Relationship Management tool, as well as (b) one or many lead capture tools. We recommend having all your lead capture tools' data flow into your CMS/CRM and then using a trigger event from your CMS/CRM to trigger a request to Hover's Capture Request endpoint. This flow allows your business to leverage many lead capture tools, with out the need to integrate all of them into both your CMS/CRM and Hover. The diagram below outlines where this Capture Request flow may fit into your larger process.

Sending the Capture Request API Request

Once the data from your lead capture tools are input to your CMS/CRM you can leverage the trigger point to initiate logic that sends a request to Hover's Capture Request endpoint. The Capture Request endpoint https://hover.to/api/v2/capture_requests has a set of parameters that must be included for the request to succeed. These are:

  • capture_request[capturing_user_name]
  • capture_request[capturing_user_email]
  • capture_request[job_attributes][location_line_1]
  • current_user_email or current_user_id (only one of these parameters is required)

While capturing_user_phone is not required, it must be included if you want users to receive mobile phone text messages with a link to capture the Hover. All Hover's must be captured on a mobile device.

The above required parameters are the bare minimum data, but the more data you provide the more pre-populated data will exist in the resulting job, that a user then does not need to enter later. We reccomend the data you capture in your lead capture process be informed by the data that the Capture Request endpoint can ingest. To learn more about what data this endpoint can ingest, see here.

Once the Capture Request endpoint is hit

Once the Capture Request Endpoint is hit a draft job will be created in your Hover Properties page, and a text/email will be sent to the capturing user. When the user captures the Hover Job you will receive an alert via email and a webhook will fire with a Capture Request Completed event. Once the now captured job is processed by Hover, all generated data like measurements, 3D model, etc will be ready, meaning the Job was captured and completed.

Getting data from Hover into your Business Systems

Depending on how your business uses Hover data, you may find value in getting data from Hover back into your business systems, often a CMS/CRM. To do this we recommend setting up a Job State webhook following this guide listening for Job State complete events.

When you receive a Jobcomplete event you can grab the Job ID from the webhook payload (click here to see example payload) and use it to send an API request for the data you need. For example, if your business leverages the Measurement PDF you would send a request, using the relevant Job ID to the Measurement PDF endpoint to get the Measurement PDF related to this specific Job back and into your system for further use.

This is one example using Measurement PDFs, but Hover also offers endpoints for XLSX data, JSON data, images, Checklists data, Material List data, and more. To see more potential endpoints for data, and to learn how to use them check out our API reference documentation.

Conclusion

The above documentation should get you started leveraging Hover's Capture Request endpoint to send Capture requests to users, and get data back. If you have more questions feel free to reach out to your Hover representative to be put in contact with a Solution Engineer that can help support you.

FAQ

  • Can I customize the message sent with a Hover Capture Request text/email via the API?
    • No; however, you can opt to get back only the Capture Request /Link/ and then send the link via your own communication with custom messaging. Learn more here [To Do link] Functionality to allow custom messaging on capture requests is on our roadmap but not currently available.

Updated 3 months ago