Understanding Jobs
Jobs are the core aspect of HOVER's API. In their simplest form, jobs are individual structures or floors within a structure that you are requesting measurements for.
Jobs can be created through the HOVER API, the HOVER mobile app (available on iOS and Android), or on the HOVER website. 🛑 Please note, Job creation does not kick off any kind of event that can be captured via webhook. If you're workflow will rely on sending webhook events for Job creation please use Capture requests, which also create jobs. Learn more here. 🛑
Consider this simplified representation of a HOVER job object:
{
"name": "Hover Drive", //a user-facing name to identify the job
"deliverable_id": 3, //the type of measurement being ordered
"location_line_1": "123 Hover Drive", //the street address of the job
"location_city": "Carmel", //the city of the job
"location_region": "IN", //the state or region of the job
"location_postal_code": "46033", //the zipcode of the job
"id": 12345678, //the job's unique identifier, set by HOVER
"captured_user_id": 135318, //the id of the user who captured the job
"external_identifier": "EXAMPLE-ID-123", //a custom identifier users can attach to a job
"org_id": 100, //the id of the organization who created the job
}
Jobs represent the request and creation of a deliverable (type of measurement being ordered) and provide information such as the User who captured the job, the location of the job, and the Org (organization) that created the job. There are several types of deliverables that HOVER offers for various use cases, such as our Roof-Only reports for users who only need to obtain detailed measurements and information about the roof of a structure.
Scope of Jobs
For exterior-based captures, a HOVER job will be an individual structure on a property: common examples are a main structure (house), a detached garage, or a shed. Each of these structures will be represented as an individual HOVER job.
For interior-based captures, a HOVER job will be an individual floor of the structure. Each room on a single floor can be contained within a single job, but individual stories within a structure are represented as unique jobs.
You may want to associate multiple jobs together for the purposes of your integration. For example, you may want to bring back the individual jobs for the main structure, garage, and shed associated with one customer back into your application. Please reference the Job Association Guide for various methods to accomplish this workflow.
Deliverable Types
All deliverables are ultimately represented as a unique Job in HOVER, each with their own unique job_id
. The type of deliverable associated with this job is represented as a deliverable_id
.
Here is a breakdown of the various types of deliverables offered at HOVER.
Note: Some deliverables can be upgraded or changed to another deliverable type. Supported deliverable changes are listed below, but more documentation about Deliverable Change Requests is available here.
Chart of Hover Deliverable Types
Deliverable Name | Deliverable ID | Description | Supported Upgrades |
---|---|---|---|
Roof Only | 2 | An exterior capture that produces a 3D model and measurements of the roof of a structure. | Complete |
Complete | 3 | An exterior capture that produces a 3D model and measurements of the roof and walls of a structure. | None |
Total Living Area Plus | 5 | An exterior capture that produces a 3D model and measurements of the total living area of a structure. | Complete |
Total Living Area | 6 | An exterior capture that produces measurements of the total living area of a structure. | Complete |
Capture Only | 7 | An exterior capture that produces a 3D model of the structure without measurements. | Roof Only, Complete |
Interior | 8 | An interior capture that produces measurements and a sketch of the interior floor plan. | None |
Note: A Capture Request or Connect Request (interchangeable) is a type of job that also sends notifications the the intended capturer to capture in the Hover App.
Job States or Status
Jobs can have different states depending on where they are in Hovers process. For example if a job is missing images it can fail, and be in a failed state.
State | Labels from API | Description |
---|---|---|
Draft | PHOTOS NEEDED (web) DRAFT (mobile) | This capture has not been completed. |
Upload 0% | UPLOADING | The capture has been queued to Upload. |
No Network | no internet connection detected | Device is not connected to data network. |
Uploading | UPLOADING X% | The capture has begun uploading, and is X% uploaded. |
Uploaded | UPLOADED | The capture has been fully uploaded. |
Processing Upload | PROCESSING UPLOAD | The capture has begun processing to begin model creation. |
Upload Failed | UPLOAD FAILED | The upload was not successful. |
Archived | ARCHIVED | The job has been archived. |
Failed | FAILED | The job could not be built. More on why here. |
Needs Approval | APPROVAL NEEDED (web) NEEDS APPROVAL or AWAITING APPROVAL (mobile) | An Admin or Job Manager needs to approve the job. |
Processing | EVALUATING | The job (capture) has begun the processing for the first part of model creation. |
Working | PROCESSING (web+mobile) BUILDING (mobile) | The job's model creation has begun. |
Complete | DONE | This job is done and available to the user. Note, .esx fils is not immediately available upon job complete, see here. |
Capture Only Deliverable | READY TO ORDER | The capture is not Failed or Cancelled and a deliverable type can be ordered. |
Cancelled | CANCELLED | The job was cancelled. |
Paying | PAYING (web) FINALIZING (mobile) | This job is complete but we were unable to charge the user for it, and payment needs to be made for the job to be released. |
Payment Failed | PAYMENT FAILED (web)PENDING (mobile) | The payment has failed, and the user should contact support. |
Limited Access | LIMITED_ACCESS | Your organization's plan has lapsed. Your plan administrator should contact your Hover representative. |