Get a Job's Material List

Introduction

Hover's Material List feature generates material takeoffs for siding and roofing jobs automatically from Hover measurements. The Material List API provides the ability to access this data through your integration. Currently, the Material List API is read-only, and its contents are provided as JSON. Customers looking to receive material lists in other formats, such as CSV and PDF, can access these files on the HOVER website.

Creating a Material List in Hover

The creation of a Material List for a Hover job requires the use of the Hover web application. Material Lists will not appear in API results until a user has performed these actions on a job in Hover.

To produce a material list, a Hover user will access the Hover website and select the Material List option from a property's details page.

Within the Material List web application, a Hover user will select the Material List templates for their project.

Once a user has selected their templates, Hover will automatically generate a Material List that is available via API.

`ProductionList`

The projectManagementProductionList query can provide data on the material list generated, as well as other details on the Hover job. There are two similar requests that you can use to query Material List data that our outlined below. Both queries are able to extract the exact same data and it is completely up to you on how you would like to pull the data from Hover

Using the Org ID and Job ID

The first method involves passing in your organization's unique Hover ID and the ID of the specific job that a material list has been generated for:

Required Variables for Querying With Org ID and Job ID

Variable	Description	Type
`jobId`	The Hover Job ID of the desired material list	`int`
`orgId`	The ID of the Hover organization you are accessing the material list on behalf of	`int`

Using the Material List ID

In lieu of passing in your respective org and job IDs into the query, you can optionally simplify the request by passing in the projectManagementProductionListId value, also referred to as your material list ID.

Required Variables for Querying With Material List ID

Variable	Description	Type
`id`	The Hover ID of the material list (`projectManagementProductionListId`)	`int`

Obtaining the Material List PDF

This query allows you to retrieve a link to a Material List PDF generated by the Hover system. By including the orders.orderDocuments.pdf object in your projectManagementProductionList query, the redirectUrl value will provide a static link to the PDF associated with the specific material list.

orders {
      orderDocuments {
        id
        pdf {
          filename
          redirectUrl
        }
      }
    }

Query and Response Examples

Please note that all of the keys in the query examples are optional. If you do not want or need specific data points, you can remove them from your query.

{
  projectManagementProductionList(jobId: {job_id}, orgId: {org_id}) {
    contractLaborTotal
    contractMaterialSubtotal
    contractMaterialTax
    contractMaterialTotal
    contractOtherTotal
    contractPreDiscountPrice
    contractTotalCost
    contractTotalPrice
    createdAt
    id
    laborTotalCost
    materialPretaxCost
    materialSalesTax
    materialTotalCost
    name
    otherTotalCost
    profitAmount
    profitMargin
    totalCost
    totalDiscount
    totalPrice
    salesOpportunity {
      job {
        id
        name
      }
      orgId
    }
    
    orders {
      orderDocuments {
        id
        pdf {
          filename
          redirectUrl
        }
      }
    }
    
    listItems {
      calculatedQuantity
      color
      id
      isManualMeasurement
      listItemGroupName
      measurement
      measurementUnits
      name
      notes
      pretaxCost
      product {
        name
        manufacturerUrl
        productType
        displayName
      }
      quantity
      quantityUnits
      taxPercent
      totalCost
      totalPrice
      tradeType
      type
      unitCost
      wasteFactor
    }
  }
}

{
  projectManagementProductionListById(id: {projectManagementProductionListId}) { # The ID of the material list
    contractLaborTotal
    contractMaterialSubtotal
    contractMaterialTax
    contractMaterialTotal
    contractOtherTotal
    contractPreDiscountPrice
    contractTotalCost
    contractTotalPrice
    createdAt
    id
    laborTotalCost
    materialPretaxCost
    materialSalesTax
    materialTotalCost
    name
    otherTotalCost
    profitAmount
    profitMargin
    totalCost
    totalDiscount
    totalPrice
    salesOpportunity {
      job {
        id
        name
      }
      orgId
    }

    orders {
      orderDocuments {
        id
        pdf {
          filename
          redirectUrl
        }
      }
    }

    listItems {
      calculatedQuantity
      color
      id
      isManualMeasurement
      listItemGroupName
      measurement
      measurementUnits
      name
      notes
      pretaxCost
      product {
        name
        manufacturerUrl
        productType
        displayName
      }
      quantity
      quantityUnits
      taxPercent
      totalCost
      totalPrice
      tradeType
      type
      unitCost
      wasteFactor
    }
  }
}

{
  "data": {
    "projectManagementProductionList": {
      "contractLaborTotal": 1428.3275,
      "contractMaterialSubtotal": 3193.44,
      "contractMaterialTax": 0,
      "contractMaterialTotal": 3193.44,
      "contractOtherTotal": 0,
      "contractPreDiscountPrice": 4621.7675,
      "contractTotalCost": 4621.7675,
      "contractTotalPrice": 4621.7675,
      "createdAt": "2024-08-20T19:15:05Z",
      "id": 343355,
      "laborTotalCost": 1428.3275,
      "materialPretaxCost": 3193.44,
      "materialSalesTax": 0,
      "materialTotalCost": 3193.44,
      "name": "Roof",
      "otherTotalCost": 0,
      "profitAmount": 0,
      "profitMargin": 0,
      "totalCost": 4621.7675,
      "totalDiscount": 0,
      "totalPrice": 4621.7675,
      "salesOpportunity": {
        "job": {
          "id": 13278801,
          "name": null
        },
        "orgId": 634962
      },
      "orders": [
        {
          "orderDocuments": [
            {
              "id": "8156c02a-ada8-4290-a379-d2d300a52282",
              "pdf": {
                "filename": "Material_Order.pdf",
                "redirectUrl": "https://ehi.hover.to/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBL2xZRmc9PSIsIiYmxvYl9pZCJ9fQ==--ad84786fed0e41be65e97052acc57ff1cc2e756b/Material_Order.pdf"
              }
            }
          ]
        }
      ],
      "listItems": [
        {
          "calculatedQuantity": 0.5775,
          "color": null,
          "id": 8329390,
          "isManualMeasurement": false,
          "listItemGroupName": "GAF Timberline HDZ",
          "measurement": 11.55,
          "measurementUnits": "squares",
          "name": "Coil Nails",
          "notes": "",
          "pretaxCost": 44.32,
          "product": null,
          "quantity": 1,
          "quantityUnits": "BOXES",
          "taxPercent": 0,
          "totalCost": 44.32,
          "totalPrice": 44.32,
          "tradeType": "ROOF",
          "type": "MATERIAL",
          "unitCost": 44.32,
          "wasteFactor": 0
        },
        {
          "calculatedQuantity": 2,
          "color": null,
          "id": 8329389,
          "isManualMeasurement": true,
          "listItemGroupName": "GAF Timberline HDZ",
          "measurement": 0,
          "measurementUnits": null,
          "name": "Roof Accessory Paint",
          "notes": "",
          "pretaxCost": 10,
          "product": null,
          "quantity": 2,
          "quantityUnits": "EACH",
          "taxPercent": 0,
          "totalCost": 10,
          "totalPrice": 10,
          "tradeType": "ROOF",
          "type": "MATERIAL",
          "unitCost": 5,
          "wasteFactor": 0
        },
        {
          "calculatedQuantity": 2,
          "color": null,
          "id": 8329388,
          "isManualMeasurement": true,
          "listItemGroupName": "GAF Timberline HDZ",
          "measurement": 0,
          "measurementUnits": null,
          "name": "Caulk",
          "notes": "",
          "pretaxCost": 14,
          "product": null,
          "quantity": 2,
          "quantityUnits": "TUBES",
          "taxPercent": 0,
          "totalCost": 14,
          "totalPrice": 14,
          "tradeType": "ROOF",
          "type": "MATERIAL",
          "unitCost": 7,
          "wasteFactor": 0
        },
        {
          "calculatedQuantity": 0.09856,
          "color": null,
          "id": 8329387,
          "isManualMeasurement": false,
          "listItemGroupName": "GAF Timberline HDZ",
          "measurement": 2.24,
          "measurementUnits": "linear_feet",
          "name": "Step Flashing",
          "notes": "",
          "pretaxCost": 25,
          "product": null,
          "quantity": 1,
          "quantityUnits": "BUNDLES",
          "taxPercent": 0,
          "totalCost": 25,
          "totalPrice": 25,
          "tradeType": "ROOF",
          "type": "MATERIAL",
          "unitCost": 25,
          "wasteFactor": 0.1
        },
        {
          "calculatedQuantity": 19.3127,
          "color": null,
          "id": 8329386,
          "isManualMeasurement": false,
          "listItemGroupName": "GAF Timberline HDZ",
          "measurement": 175.57,
          "measurementUnits": "linear_feet",
          "name": "Drip Edge",
          "notes": "",
          "pretaxCost": 110,
          "product": {
            "name": "Drip Edge F5",
            "manufacturerUrl": null,
            "productType": "MATERIAL",
            "displayName": null
          },
          "quantity": 20,
          "quantityUnits": "PIECES",
          "taxPercent": 0,
          "totalCost": 110,
          "totalPrice": 110,
          "tradeType": "ROOF",
          "type": "MATERIAL",
          "unitCost": 5.5,
          "wasteFactor": 0.1
        },
        {
          "calculatedQuantity": 12.705,
          "color": null,
          "id": 8329385,
          "isManualMeasurement": false,
          "listItemGroupName": "GAF Timberline HDZ",
          "measurement": 11.55,
          "measurementUnits": "squares",
          "name": "Install (Walkable 6/12 or less)",
          "notes": "",
          "pretaxCost": 1143.9,
          "product": null,
          "quantity": 12.71,
          "quantityUnits": "SQUARES",
          "taxPercent": 0,
          "totalCost": 1143.9,
          "totalPrice": 1143.9,
          "tradeType": "ROOF",
          "type": "LABOR",
          "unitCost": 90,
          "wasteFactor": 0.1
        },
        {
          "calculatedQuantity": 59.823,
          "color": null,
          "id": 8329384,
          "isManualMeasurement": false,
          "listItemGroupName": "GAF Timberline HDZ",
          "measurement": 52.02,
          "measurementUnits": "linear_feet",
          "name": "Hip and Ridge Labor",
          "notes": "",
          "pretaxCost": 74.7875,
          "product": null,
          "quantity": 59.83,
          "quantityUnits": "LINEAR_FEET",
          "taxPercent": 0,
          "totalCost": 74.7875,
          "totalPrice": 74.7875,
          "tradeType": "ROOF",
          "type": "LABOR",
          "unitCost": 1.25,
          "wasteFactor": 0.15
        },
        {
          "calculatedQuantity": 2.464,
          "color": null,
          "id": 8329383,
          "isManualMeasurement": false,
          "listItemGroupName": "GAF Timberline HDZ",
          "measurement": 2.24,
          "measurementUnits": "linear_feet",
          "name": "Step Flashing Labor",
          "notes": "",
          "pretaxCost": 12.35,
          "product": null,
          "quantity": 2.47,
          "quantityUnits": "LINEAR_FEET",
          "taxPercent": 0,
          "totalCost": 12.35,
          "totalPrice": 12.35,
          "tradeType": "ROOF",
          "type": "LABOR",
          "unitCost": 5,
          "wasteFactor": 0.1
        },
        {
          "calculatedQuantity": 18.645,
          "color": null,
          "id": 8329382,
          "isManualMeasurement": false,
          "listItemGroupName": "GAF Timberline HDZ",
          "measurement": 16.95,
          "measurementUnits": "linear_feet",
          "name": "Apron Flashing Labor",
          "notes": "",
          "pretaxCost": 93.25,
          "product": null,
          "quantity": 18.65,
          "quantityUnits": "LINEAR_FEET",
          "taxPercent": 0,
          "totalCost": 93.25,
          "totalPrice": 93.25,
          "tradeType": "ROOF",
          "type": "LABOR",
          "unitCost": 5,
          "wasteFactor": 0.1
        },
        {
          "calculatedQuantity": 2,
          "color": null,
          "id": 8329381,
          "isManualMeasurement": true,
          "listItemGroupName": "GAF Timberline HDZ",
          "measurement": 0.64,
          "measurementUnits": "squares",
          "name": "OSB 7/16\"",
          "notes": "",
          "pretaxCost": 36,
          "product": null,
          "quantity": 2,
          "quantityUnits": "EACH",
          "taxPercent": 0,
          "totalCost": 36,
          "totalPrice": 36,
          "tradeType": "ROOF",
          "type": "MATERIAL",
          "unitCost": 18,
          "wasteFactor": 0
        },
        {
          "calculatedQuantity": 2.99115,
          "color": null,
          "id": 8329380,
          "isManualMeasurement": false,
          "listItemGroupName": "GAF Timberline HDZ",
          "measurement": 52.02,
          "measurementUnits": "linear_feet",
          "name": "GAF - Timbertex Hip & Ridge ",
          "notes": "",
          "pretaxCost": 178.5,
          "product": {
            "name": "GAF TIMBERTEX 20' LF/BD",
            "manufacturerUrl": null,
            "productType": "MATERIAL",
            "displayName": null
          },
          "quantity": 3,
          "quantityUnits": "BUNDLES",
          "taxPercent": 0,
          "totalCost": 178.5,
          "totalPrice": 178.5,
          "tradeType": "ROOF",
          "type": "MATERIAL",
          "unitCost": 59.5,
          "wasteFactor": 0.15
        },
        {
          "calculatedQuantity": 1.5362375,
          "color": null,
          "id": 8329379,
          "isManualMeasurement": false,
          "listItemGroupName": "GAF Timberline HDZ",
          "measurement": 175.57,
          "measurementUnits": "linear_feet",
          "name": "WeatherBlocker Premium Starter",
          "notes": "",
          "pretaxCost": 116.72,
          "product": null,
          "quantity": 2,
          "quantityUnits": "BUNDLES",
          "taxPercent": 0,
          "totalCost": 116.72,
          "totalPrice": 116.72,
          "tradeType": "ROOF",
          "type": "MATERIAL",
          "unitCost": 58.36,
          "wasteFactor": 0.05
        },
        {
          "calculatedQuantity": 7.033098835197785,
          "color": null,
          "id": 8329378,
          "isManualMeasurement": false,
          "listItemGroupName": "GAF Timberline HDZ",
          "measurement": 426.4615384615385,
          "measurementUnits": null,
          "name": "GAF - StormGuard",
          "notes": "",
          "pretaxCost": 746.32,
          "product": null,
          "quantity": 8,
          "quantityUnits": "ROLLS",
          "taxPercent": 0,
          "totalCost": 746.32,
          "totalPrice": 746.32,
          "tradeType": "ROOF",
          "type": "MATERIAL",
          "unitCost": 93.29,
          "wasteFactor": 0.1
        },
        {
          "calculatedQuantity": 0.6339482137681159,
          "color": null,
          "id": 8329377,
          "isManualMeasurement": false,
          "listItemGroupName": "GAF Timberline HDZ",
          "measurement": 5.763165579710145,
          "measurementUnits": "squares",
          "name": "GAF Deck Armor",
          "notes": "",
          "pretaxCost": 217,
          "product": null,
          "quantity": 1,
          "quantityUnits": "ROLLS",
          "taxPercent": 0,
          "totalCost": 217,
          "totalPrice": 217,
          "tradeType": "ROOF",
          "type": "MATERIAL",
          "unitCost": 217,
          "wasteFactor": 0.1
        },
        {
          "calculatedQuantity": 1.09242,
          "color": "Default",
          "id": 8329376,
          "isManualMeasurement": false,
          "listItemGroupName": "GAF Timberline HDZ",
          "measurement": 52.02,
          "measurementUnits": "linear_feet",
          "name": "GAF Cobra Ridge Vent 50ft x 10.5IN",
          "notes": "",
          "pretaxCost": 229.96,
          "product": {
            "name": "Cobra® Snow Country Advanced",
            "manufacturerUrl": null,
            "productType": "MATERIAL",
            "displayName": null
          },
          "quantity": 2,
          "quantityUnits": "PIECES",
          "taxPercent": 0,
          "totalCost": 229.96,
          "totalPrice": 229.96,
          "tradeType": "ROOF",
          "type": "MATERIAL",
          "unitCost": 114.98,
          "wasteFactor": 0.05
        },
        {
          "calculatedQuantity": 38.11881188118812,
          "color": null,
          "id": 8329375,
          "isManualMeasurement": false,
          "listItemGroupName": "GAF Timberline HDZ",
          "measurement": 11.55,
          "measurementUnits": "squares",
          "name": "GAF - Timberline HDZ",
          "notes": "",
          "pretaxCost": 1465.62,
          "product": {
            "name": "Timberline HDZ® Shingles",
            "manufacturerUrl": null,
            "productType": "MATERIAL",
            "displayName": null
          },
          "quantity": 39,
          "quantityUnits": "BUNDLES",
          "taxPercent": 0,
          "totalCost": 1465.62,
          "totalPrice": 1465.62,
          "tradeType": "ROOF",
          "type": "MATERIAL",
          "unitCost": 37.58,
          "wasteFactor": 0.1
        },
        {
          "calculatedQuantity": 52.02,
          "color": null,
          "id": 8329374,
          "isManualMeasurement": false,
          "listItemGroupName": "GAF Timberline HDZ",
          "measurement": 52.02,
          "measurementUnits": "linear_feet",
          "name": "Install Ridge Vent ",
          "notes": "",
          "pretaxCost": 104.04,
          "product": null,
          "quantity": 52.02,
          "quantityUnits": "LINEAR_FEET",
          "taxPercent": 0,
          "totalCost": 104.04,
          "totalPrice": 104.04,
          "tradeType": "ROOF",
          "type": "LABOR",
          "unitCost": 2,
          "wasteFactor": 0
        }
      ]
    }
  }
}

curl -X POST "https://graph.hover.to/graphql" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{"query": "query { projectManagementProductionList(jobId: {job_id}, orgId: {org_id}) { listItems { type unitCost tradeType quantity color totalCost product { name provider { name } } SKU sortOrder } } }"}'

Method: POST
URL: https://graph.hover.to/graphql
Headers: 
  Content-Type: application/json
  Authorization: Bearer YOUR_ACCESS_TOKEN

Body:
{
  "query": "query { projectManagementProductionList(jobId: {job_id}, orgId: {org_id}) { listItems { type unitCost tradeType quantity color totalCost product { name provider { name } } SKU sortOrder } } }"
}

Using Webhooks for Material List events

When a material list is created or updated in Hover, our system will fire notifications that you can subscribe to through a webhooks connection. Hover sends notifications when a Material List is created (project-management-production-list-created) and when a Material List is updated (project-management-production-list-created). The corresponding events

Material List Created

{
      project_management_production_list_id: 55643,
      sales_opportunity_id: 347615,
      job_id: 8675309,
      event: 'project-management-production-list-created',
      webhook_id: 13002,
    }

Material List Updated

{
      project_management_production_list_id: 55643,
      sales_opportunity_id: 347615,
      job_id: 8675309,
      event: 'project-management-production-list-updated',
      webhook_id: 13002,
    }

In terms of utilizing this data against the queries referenced above, the webhook payload includes the specific job_id where a material list was created or updated. If you plan on querying this data using the Org ID and your Job ID, you'll need to hardcode your orgId value and use the jobId from the webhook event.

If you decide to use the projectManagementProductionListID to query for this data, you can use the corresponding value for the project_management_production_list_id key within the webhook event.