--- updatedAt: 2026-08-04T21:55:47.000Z agentTools: projectIndex: https://developers.hover.to/llms.txt --- # Create a Capture Request ## Overview This endpoint initiates a Hover property capture by creating a draft job in your authenticated organization and sending an invitation (via email/SMS) to a designated user to perform the capture. When this endpoint is successfully called, a new draft job is immediately created within your Hover account. Simultaneously, an invitation is sent to the specified `capturing_user_email` (and optionally `capturing_user_phone`) prompting them to download the Hover app and capture the property. All parameters provided within the `job_attributes` object will be used to pre-populate the details of the newly created draft job, minimizing manual entry for the capturing user. ### Required Body Parameters The following parameters are **required** in the request body. Providing additional `job_attributes` is highly recommended to pre-populate the resulting job with more data. While the `capturing_user_phone` is not required, it is recommended so that the assigned person receives a SMS text message to prompt them to download the Hover app. **To see the *optional* params, expand the Capture Request Object in the Body Params section on this page** | Parameter | Type | Description | Required | | :------------------------------------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------- | | `capture_request[capturing_user_name]` | `string` | The full name of the user who will be prompted to capture the property. | Yes | | `capture_request[capturing_user_email]` | `string` | The email address of the user who will be prompted to capture the property. An invitation email will be sent to this address. | Yes | | `capture_request[job_attributes][location_line_1]` | `string` | The street address of the property to be captured. This is a minimum required attribute for the draft job's location. Additional `job_attributes` (e.g., `location_city`, `location_state`, etc.) can be included for more detailed pre-population. | Yes | | `current_user_email` | `string` | **One of `current_user_email` or `current_user_id` is required.** The email address of the user within the authenticated organization who is initiating this capture request. | Yes (or `current_user_id`) | | `current_user_id` | `string` | **One of `current_user_email` or `current_user_id` is required.** The ID of the user within the authenticated organization who is initiating this capture request. | Yes (or `current_user_email`) |
## Sample Request Body ```json Create Capture Request Sample Request Body { "capture_request": { "capturing_user_email": "homeowner@hoverinc.com", "capturing_user_phone": "5558675309", "capturing_user_name": "Lucille Bluth", "signup_type": "homeowner", "job_attributes": { "deliverable_id": 3, "external_identifer": "Claim1234", "name": "The Big House", "location_line_1": "1701 Bryant Street", "location_line_2": "", "location_city": "Denver", "location_region": "CO", "location_postal_code": "80204", "suppress_email": false, "wallet_id": "56988" } }, "current_user_id": {{current_user_id}} } ``` ## Sample Response Body When successful, this endpoint will return a `201 Created` HTTP code and a response body that looks similar to this: ```json Create Capture Request Sample Response { "id": 1521803, "capturing_user_name": "Lucille Bluth", "capturing_user_phone": "5558675309", "capturing_user_email": "homeowner@hoverinc.com", "capturing_user_id": null, "requesting_user_id": 1153372, "identifier": "XcUUtA", "claim_number": null, "state": "new", "signup_type": "homeowner", "inspection_workflow_id": 1072, "requires_reconstruction_capture": true, "job_attributes": { "name": "Vacation Home", "location_line_1": "123 Hover Way", "location_line_2": "Apartment 22", "location_city": "Los Angeles", "location_region": "CA", "location_postal_code": "90210", "external_identifier": "8675309", "deliverable_id": 3, "client_identifier": "0eb6edb9-b425-4797-8161-18aebf225707" }, "captured_user_id": null, "pending_job_id": 10168587, "requesting_user": { "name": "Integration user", "email": "integrations@bluthcompany.com", "org": { "id": 55342, "name": "Bluth Company", "preferences": { "external_identifier_label": "Lead Number", "external_identifier_required": false } } }, "org_id": 492855, "wallet": { "id": 492767, "org": { "customer_display_name": "Bluth Company" } } } ``` # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "hover-api-v3", "version": "3" }, "servers": [ { "url": "https://hover.to" } ], "components": { "securitySchemes": { "sec0": { "type": "oauth2", "flows": {} } } }, "security": [ { "sec0": [] } ], "paths": { "/api/v2/capture_requests": { "post": { "summary": "Create a Capture Request", "description": "", "operationId": "create-capture-request", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "capture_request": { "properties": { "capturing_user_email": { "type": "string", "description": "Required. The email address of the person this capture request will be sent to.", "default": "homeowner@bluthcompanies.com" }, "capturing_user_phone": { "type": "string", "description": "Optional. The phone number of the person this capture request will be sent to.", "default": "8058675309" }, "capturing_user_name": { "type": "string", "description": "Required. The name of the person that will be capturing the property. Most likely the homeowner's name.", "default": "Lucille Bluth" }, "signup_type": { "type": "string", "description": "Optional. Defaults to `homeowner`. Allowed values are `homeowner` and `pro`, designated by the type of user capturing the property.", "default": "homeowner" }, "job_attributes": { "properties": { "name": { "type": "string", "description": "A name for the job.", "default": "The Big House" }, "deliverable_id": { "type": "string", "description": "Supported deliverable_ids: 2(Roof Only), 3(Complete), 5(Total Living Area Plus), 6 (Total Living Area), 7 (Capture Only, Photos Only), 8 (Interior)", "default": "3" }, "external_identifier": { "type": "string", "description": "A unique identifier generated by the client. This can be anything you want and won't be changed. It can be used to reference an ID in the an external system database.", "default": "8675309" }, "location_city": { "type": "string", "description": "The city where this job is located.", "default": "Denver" }, "location_line_1": { "type": "string", "description": "First line of this job's address", "default": "1701 Bryant Street" }, "location_line_2": { "type": "string", "description": "Second line of this job's address", "default": "Apartment 22" }, "location_postal_code": { "type": "string", "description": "The postal code of this job's address", "default": "80204" }, "location_region": { "type": "string", "description": "The 2 character state code where this job resides.", "default": "CO" }, "suppress_email": { "type": "boolean", "description": "If a value other than false is given for this attribute then all emails related to this job will be suppressed. That includes capture request emails.", "default": false }, "wallet_id": { "type": "integer", "description": "Optional. By passing this parameter you can specify the billing information for the job.", "default": 67821, "format": "int32" } }, "required": [], "type": "object" }, "suppress_text_messages": { "type": "string", "description": "If a value other than false is given for this attribute then all SMS related to this job will be suppressed. That includes capture request SMS..", "default": "false" }, "inspection_workflow_id": { "type": "string", "default": "null", "description": "An inspection workflow ID to allow the capturing user to perform an inspection (in addition to a scan) upon receiving a Capture Request. " } }, "required": [], "type": "object" }, "current_user_email": { "type": "string", "description": "The internal user that you want to assign the job to. Alternatively, you can also use the `current_user_id` param.", "default": "michael@bluthcompanies.com" }, "current_user_id": { "type": "integer", "description": "The ID value of the user who you want to assign the job to. Alternatively, current_user_email can be used.", "default": 643197, "format": "int32" } } } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "capture_request": { "properties": { "capturing_user_email": { "type": "string", "description": "Required. The email address of the person this capture request will be sent to.", "default": "homeowner@bluthcompanies.com" }, "capturing_user_phone": { "type": "string", "description": "Optional. The phone number of the person this capture request will be sent to.", "default": "8058675309" }, "capturing_user_name": { "type": "string", "description": "Required. The name of the person that will be capturing the property. Most likely the homeowner's name.", "default": "Lucille Bluth" }, "signup_type": { "type": "string", "description": "Optional. Defaults to `homeowner`. Allowed values are `homeowner` and `pro`, designated by the type of user capturing the property.", "default": "homeowner" }, "job_attributes": { "properties": { "name": { "type": "string", "description": "A name for the job.", "default": "The Big House" }, "deliverable_id": { "type": "string", "description": "Supported deliverable_ids: 2(Roof Only), 3(Complete), 5(Total Living Area Plus), 6 (Total Living Area), 7 (Capture Only, Photos Only), 8 (Interior)", "default": "3" }, "external_identifier": { "type": "string", "description": "A unique identifier generated by the client. This can be anything you want and won't be changed. It can be used to reference an ID in the an external system database.", "default": "8675309" }, "location_city": { "type": "string", "description": "The city where this job is located.", "default": "Denver" }, "location_line_1": { "type": "string", "description": "First line of this job's address", "default": "1701 Bryant Street" }, "location_line_2": { "type": "string", "description": "Second line of this job's address", "default": "Apartment 22" }, "location_postal_code": { "type": "string", "description": "The postal code of this job's address", "default": "80204" }, "location_region": { "type": "string", "description": "The 2 character state code where this job resides.", "default": "CO" }, "suppress_email": { "type": "boolean", "description": "If a value other than false is given for this attribute then all emails related to this job will be suppressed. That includes capture request emails.", "default": false }, "wallet_id": { "type": "integer", "description": "Optional. By passing this parameter you can specify the billing information for the job.", "default": 67821, "format": "int32" } }, "required": [], "type": "object" }, "suppress_text_messages": { "type": "string", "description": "If a value other than false is given for this attribute then all SMS related to this job will be suppressed. That includes capture request SMS..", "default": "false" } }, "required": [], "type": "object" }, "current_user_email": { "type": "string", "description": "The internal user that you want to assign the job to. Alternatively, you can also use the `current_user_id` param.", "default": "michael@bluthcompanies.com" }, "current_user_id": { "type": "integer", "description": "The ID value of the user who you want to assign the job to. Alternatively, current_user_email can be used.", "default": 643197, "format": "int32" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{}" } }, "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{}" } }, "schema": { "type": "object", "properties": {} } } } } } } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ```