Guides

Testing your Integration

Using the Hover Test Jobs endpoint to test your integration without physically capturing a property.

Suggest Edits

Overview

The ability to test an integration is a vital step before deploying to production, which is why Hover provides an endpoint specifically for simulating Hover's 3D reconstruction pipeline. Processing 2D pictures and reconstructing them into 3D measurements and deliverables can take a significant amount of time, depending on the complexity and size of the structure, which could significantly slow down the ability to create and test an integration.

For these reasons, Hover has two endpoints that allow you to simulate this reconstruction process without physically having to capture a property. The goal of using these endpoints are to speed up your ability to test your integration and provide sample deliverables and measurements for you to use as you build your integration.

Note: Processing a job through the Test Jobs endpoints does not incur a cost. You will not be billed for these jobs.

These endpoints can be used in both the Hover production environment (https://hover.to/) and the Hover sandbox environment (https://sandbox.hover.to). For the sandbox environment, utilizing the Test Jobs endpoints are the only way to generate sample data for your integration.

Based on your integration's use case, it's recommended to test out both multi-structure and single-structure scenarios. There are differences between the endpoint functionality and the sample data that's returned, but it's best practice to use both endpoints to test single structure and multi-structure use cases.

Before You Start

Webhooks

These endpoints are used to test end-to-end integration workflows between Hover and other systems. If you plan on an events-based architecture using webhooks, make sure you have a webhook listener registered and verified before using this endpoint. When using these endpoints, Hover will fire webhook events to your registered endpoint as if it were a job going through Hover's 3D reconstruction pipeline.

Multi-Structure Test Jobs Endpoint

To validate that your integration can ingest multiple models have been associated with one job, the multi-structure test jobs endpoint can create such scenarios. While only exterior data is returned, the endpoint can be used to simulate interior captures that have multiple levels or floors within a property.

Opposed to our single-structure test jobs endpoint, this is a one-step process where you make a POST request to an endpoint and Hover's system creates a sample job within your authenticated org. Please refer to the multi-structure test jobs reference page for more information on how to make this request.

Available Test States

The final state of the test job can be set to either complete or failed by using the state body parameter when making a request to the Multi-Structure Test jobs endpoint. This state is associated with a job's reconstruction state and is independent from the state of each model that is associated with a job.

Each individual model can have complete or failed status. By using the failed_models_count parameter, you can dictate if the test job has 0, 1, or 2 failed models associated with the job.

Returned Sample Data for Complete Jobs

This multi-structure test jobs endpoint generates the following data when used:

Single Structure Test Jobs Endpoint

Using the Single-Structure Test Jobs endpoint

To test this endpoint, you will need to create a job or a capture request. This endpoint will not function successfully on all jobs; they must be in an uploading or processing_upload state when submitting to this endpoint. Once the job has progressed beyond that point, it it too far along in the reconstruction process to be submitted to the Test Jobs endpoint.

Available Test States

You can set the state parameter to failed to simulate/handle instances where a job fails in the Hover pipeline; or you can set the state parameter to complete to simulate/handle instances where a job is successful and measurement and deliverable data are available.

Complete

Passing in the complete state as a part of the request path will return all job-state-changed webhooks and sample property data]. Here's an example of a request URL to the test jobs endpoint for the complete state:

PATCH https://hover.to/api/v2/jobs/{job_id}/set_test_state.json?state=complete&current_user_id={current_user_id}

Failed

In the case where Hover cannot reconstruct a property, our system will send out a failed webhook event. If you would like to develop error handling or failure cases that occur when a job fails in Hover's pipeline, you can change the state parameter to failed:

PATCH https://hover.to/api/v2/jobs/{job_id}/set_test_state.json?state=failed&current_user_id={current_user_id}

There is no sample data returned for this particular parameter, but Hover will simulate a failed job webhook event.

Returned Sample Data for Complete Jobs

This endpoint generates sample data to the job that was submitted usingstate=completequery parameter. The following data is available to pull once the job is completed:

The single-structure test jobs endpoint has two available states jobs can be set to complete and failed.

Limitations

The following data does not generate and return with either testing endpoint:

  • Hover 3d model
  • ESX file
  • XML 3D report
  • Material Lists
  • Estimations
  • Inspection Checklists

Updated 2 days ago