Why would I use this?
Some use cases for the List Jobs endpoint might be to see all the jobs associated with your organization, or to list all the jobs with a particular parameter, like Deliverable Type, to learn what kinds of jobs your business uses most.
How does it work?
This endpoint lists all of your Hover Jobs, with optional parameters to refine your search.
There are several ways you might have access to a job:
- Standard jobs created within your organization
- Job Sharing, a mechanism used to share jobs via email, sms, social media, and links.
- OrgJobAccess joins that associates jobs with orgs.
You can see which method gave you access to this job by looking at the "via_job_share" and "via_org_job_accesses" attributes in the JSON. You can revoke access to a job using the OrgJobAccess's "id" attribute.
URL Parameters
When using parameters, passing multiple values returns jobs that match any of those values. It is not required that the returned jobs match all values, just one.
For example:
Providing "['processing', 'needs_photos', 'needs_approval']" for the states parameter would result in jobs that are in any of those states, but are not in any of the other supported states "['complete', 'failed']".
For each supported value that isn't given in the array, jobs matching that value are excluded unless they match another value for the same parameter.
If no values are given, the filter is not applied.
Response Code Snippet
See an example 200 response here, then follow below to learn more about the request and what makes up the responses.
{
"pagination": {
"current_page": 1,
"total_pages": 5,
"total": 10
},
"results": [
{
"archived": false,
"name": "Hover Lane",
"customer_notes": null,
"deliverable_id": 3,
"location_line_1": "789 Hover Lane",
"location_line_2": null,
"location_city": "Fishers",
"location_region": "IN",
"location_postal_code": "46037",
"location_country": null,
"location_lat": null,
"location_lon": null,
"id": 9822524,
"client_identifier": "f90c780b-1854-4b4b-ad1a-7eec83b4a90e",
"roof_estimate_access_level": "instant",
"estimated_hours_to_completion": 0,
"approved": true,
"example": true,
"property_type": "single_family_residential",
"updated_at": "2023-07-25T20:20:52.877Z",
"completed_at": null,
"approved_at": null,
"created_at": "2023-07-25T20:20:51.133Z",
"captured_user_id": 457075,
"external_identifier": null,
"blueprint": false,
"org_id": null,
"user_id": null,
"search_rank": null,
"has_hero_image": true,
"state": "complete",
"partner_account_identifier": null,
"via_org_job_accesses": [
{
"id": 12561980,
"org_id": 600530,
"kind": "example",
"lead_state": "unassigned",
"ordering_state": "lead"
}
],
"deliverable_change_requests": []
},
{
"archived": false,
"name": "Hover Drive",
"customer_notes": null,
"deliverable_id": 3,
"location_line_1": "123 Hover Drive",
"location_line_2": null,
"location_city": "Carmel",
"location_region": "IN",
"location_postal_code": "46033",
"location_country": null,
"location_lat": null,
"location_lon": null,
"id": 9822523,
"client_identifier": "75c62ce7-5720-4b05-898a-6cca1bde3806",
"roof_estimate_access_level": "instant",
"estimated_hours_to_completion": 3.86916882531757,
"approved": true,
"example": true,
"property_type": "single_family_residential",
"updated_at": "2023-07-25T20:20:52.937Z",
"completed_at": null,
"approved_at": null,
"created_at": "2023-07-25T20:20:51.038Z",
"captured_user_id": 135318,
"external_identifier": null,
"blueprint": false,
"org_id": null,
"user_id": null,
"search_rank": null,
"has_hero_image": true,
"state": "complete",
"partner_account_identifier": null,
"via_org_job_accesses": [
{
"id": 12561979,
"org_id": 600530,
"kind": "example",
"lead_state": "unassigned",
"ordering_state": "lead"
}
],
"deliverable_change_requests": []
}
],
"meta": {
"request_received_at": 1690326462
}
}