Try our GraphQL Playground
We've included some static documentation below, however GraphQL APIs are traditionally represented through interactive playgrounds. HOVER GraphQL Playground
Introduction
Orders can be either work or material related, where some of its material orders can be placed directly with third-party vendors. Each Material Order (PDF or Provider Order) is directly associated with a Production List. Each Production List can contain multiple material orders from multiple vendors, this is because the contractor can order materials for a specific trade (i.e. roof) or all trades (i.e. roof, ice and water, gutters, siding, fascia). Every order must be tied to a vendor in order to be created. The PDF’s redirect URL is a stable, non-expiring URL for the actual file location. To get the file, the endpoint requires user authentication.
Order list items data can be accessed once an order is created. HOVER makes available the Material and/or Work Order PDF in an API endpoint where a webhook is sent with the event, its state, and order document ID. An order document webhook for a state changed event can be leveraged to get job financials updates through the production list associated with the order.
Webhook Events
project-management-order-document-state-changed Event
project-management-order-document-state-changed EventWhen a project management order document has been created, you will receive a webhook with the following post body. This webhook is sent for both Material & Labor Orders.
{
"project_management_order_document_id": "cab84a4c-0e20-48d5-9096-54358fd9bc062",
"state": "complete",
"project_management_production_list_id": 28358,
"job_id": 4045349,
"event": "project-management-order-document-state-changed",
"webhook_id": 423
}
This webhook will only send events for a complete state.
distribution-order-state-changed Event
distribution-order-state-changed EventWhen a product catalog provider order has been created, you will receive a webhook with the following post body. Please note that this event should only be consumed when the product-catalog-provider-order-state-changed state is submitted to reflect that the order has been submitted to the provider's system.
{
"event": "distribution-order-state-changed",
"distribution_order_id": "a2d65078-b111-44d5-b556-1c197a54096c",
"state": "submitted"
}
GraphQL Queries
projectManagementOrderDocuments
projectManagementOrderDocumentsThis query will return documents and information associated with a specific document ID.
Arguments
projectManagementOrderDocuments requires one or more of the following arguments:
| Argument | Description |
|---|---|
order_document_id | The id of an order document. |
productionListId | The id of a production list document. |
Production List Example
Below is an example of a query to projectManagementOrderDocuments made with a productionListId.
{
projectManagementOrderDocuments(productionListId: "#{productionListId}") {
id
createdAt
updatedAt
userId
pdf {
redirectUrl
}
order {
id
externalIdentifier
createdAt
updatedAt
orderListItems {
id
name
quantity
sku
listItem {
color
unitCost
totalCost
taxPercent
tradeType
type
vendor {
id
vendorName
provider {
identifier
}
}
}
}
}
}
}
{
"data": {
"projectManagementOrderDocuments": [
{
"id": "08ca6c2e-8793-4129-a751-3952d32a3f95",
"createdAt": "2020-06-27T05:19:30Z",
"updatedAt": "2020-06-27T05:19:33Z",
"userId": 549941,
"pdf": {
"redirectUrl": "redirectUrl"
},
"order": {
"id": "669229c6-84f3-45c5-a420-6cda8ed42c35",
"externalIdentifier": "123456",
"createdAt": "2020-06-27T05:19:30Z",
"updatedAt": "2020-06-27T05:19:30Z",
"orderListItems": [
{
"id": "66109",
"name": "Snow Country Advanced 11.5\" X 4'",
"quantity": 22,
"sku": "556503",
"listItem": {
"color": "11.5\" x 4'",
"unitCost": 10,
"totalCost": 220,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": null
}
},
{
"id": "66110",
"name": "GAF ProStart Starter Shingles",
"quantity": 3,
"sku": "353731",
"listItem": {
"color": "120.33'/BD",
"unitCost": 40,
"totalCost": 120,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": null
}
},
{
"id": "66111",
"name": "Rapid A 11 Staples -3/8\"",
"quantity": 3,
"sku": "351682",
"listItem": {
"color": "3/8\"",
"unitCost": 5,
"totalCost": 15,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": null
}
},
{
"id": "66112",
"name": "GAF WeatherWatch",
"quantity": 2,
"sku": "10643",
"listItem": {
"color": "2 SQ. Roll",
"unitCost": 80,
"totalCost": 160,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": null
}
},
{
"id": "66113",
"name": "GAF Tiger Paw",
"quantity": 2,
"sku": "401173",
"listItem": {
"color": "10 SQ. Roll",
"unitCost": 150,
"totalCost": 300,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": {
"id": 670,
"vendorName": "Beacon",
"provider": {
"identifier": "BEACON"
}
}
}
},
{
"id": "66114",
"name": "8' X 4' Plywood",
"quantity": 1,
"sku": "276548",
"listItem": {
"color": "4' x 8'",
"unitCost": 17,
"totalCost": 17,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": {
"id": 670,
"vendorName": "Beacon",
"provider": {
"identifier": "BEACON"
}
}
}
},
{
"id": "66115",
"name": "Fanaco Coil Nails",
"quantity": 2,
"sku": "12099",
"listItem": {
"color": "1-1/4\"",
"unitCost": 30,
"totalCost": 60,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": {
"id": 670,
"vendorName": "Beacon",
"provider": {
"identifier": "BEACON"
}
}
}
},
{
"id": "66116",
"name": "Caulk",
"quantity": 2,
"sku": "11590",
"listItem": {
"color": "Black",
"unitCost": 7,
"totalCost": 14,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": {
"id": 670,
"vendorName": "Beacon",
"provider": {
"identifier": "BEACON"
}
}
}
},
{
"id": "66117",
"name": "1.5\" Lead Cap",
"quantity": 1,
"sku": "560193",
"listItem": {
"color": "Black",
"unitCost": 11,
"totalCost": 11,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": {
"id": 670,
"vendorName": "Beacon",
"provider": {
"identifier": "BEACON"
}
}
}
},
{
"id": "66118",
"name": "24\" W Valley Flashing",
"quantity": 9,
"sku": "404527",
"listItem": {
"color": "Black",
"unitCost": 21,
"totalCost": 189,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": {
"id": 670,
"vendorName": "Beacon",
"provider": {
"identifier": "BEACON"
}
}
}
},
{
"id": "66119",
"name": "GAF Cobra Intake Pro\t",
"quantity": 6,
"sku": "486824",
"listItem": {
"color": "11\" x 20'",
"unitCost": 50,
"totalCost": 300,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": null
}
},
{
"id": "66120",
"name": "Ultimate Pipe Flashing",
"quantity": 1,
"sku": "361353",
"listItem": {
"color": "White",
"unitCost": 50,
"totalCost": 50,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": null
}
},
{
"id": "66121",
"name": "Big T Metal Flashing",
"quantity": 20,
"sku": "480581",
"listItem": {
"color": "Mill",
"unitCost": 0,
"totalCost": 0,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": null
}
},
{
"id": "66122",
"name": "GAF - Timberline HD Shingles",
"quantity": 91,
"sku": null,
"listItem": {
"color": "Slate",
"unitCost": 30,
"totalCost": 2730,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": {
"id": 670,
"vendorName": "Beacon",
"provider": {
"identifier": "BEACON"
}
}
}
},
{
"id": "66123",
"name": "GAF Ridglass Hip And Ridge Shingles",
"quantity": 4,
"sku": null,
"listItem": {
"color": "Charcoal",
"unitCost": 60,
"totalCost": 240,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": {
"id": 670,
"vendorName": "Beacon",
"provider": {
"identifier": "BEACON"
}
}
}
}
]
}
}
]
}
}
curl -X POST "https://graph.hover.to/graphql" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{"query": "{ projectManagementOrderDocuments(productionListId: \"productionListId\") { id createdAt updatedAt userId pdf { redirectUrl } order { id externalIdentifier createdAt updatedAt orderListItems { id name quantity sku listItem { color unitCost totalCost taxPercent tradeType type vendor { id vendorName provider { identifier } } } } } } }"}'
Request:
Method: POST
URL: https://graph.hover.to/graphql
Headers:
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
Body:
Type: Raw (JSON)
Content:
{
"query": "{ projectManagementOrderDocuments(productionListId: \"productionListId\") { id createdAt updatedAt userId pdf { redirectUrl } order { id externalIdentifier createdAt updatedAt orderListItems { id name quantity sku listItem { color unitCost totalCost taxPercent tradeType type vendor { id vendorName provider { identifier } } } } } } }"
}
Order Fields Index
| Field | Description |
|---|---|
externalIdentifier | A user specified identifier for an order document (e.g. PDF). This is usually the order’s Purchase Order number. |
name | Name of the ordered item |
quantity | Quantity of the ordered item |
color | Specific variation of color, or any other variation (size, variant) |
unitCost | Unit cost of the ordered item |
totalCost | The calculated total cost (before sales taxes), calculated as quantity x unitCost |
tradeType | The respective estimation group trade type (roof, gutters, siding, fascia) |
vendors | The accounts payable for the vendor where the order is being placed. This is typically the branch of a supplier. |
Order Document Example
The projectManagementOrderDocuments() query will return the order document associated with a particular Material Order when provided the order_document_id.
{
projectManagementOrderDocuments(
orderDocumentIds: $order_document_id
) {
id
createdAt
updatedAt
userId
pdf {
redirectUrl
}
order {
id
externalIdentifier
createdAt
updatedAt
orderListItems {
id
name
quantity
sku
listItem {
color
unitCost
totalCost
taxPercent
tradeType
type
vendor {
id
vendorName
provider{
identifier
}
}
}
}
}
}
}
{
"data": {
"projectManagementOrderDocuments": [
{
"id": "08ca6c2e-8793-4129-a751-3952d32a3f95",
"createdAt": "2020-06-27T05:19:30Z",
"updatedAt": "2020-06-27T05:19:33Z",
"userId": 549941,
"pdf": {
"redirectUrl": "redirectUrl"
},
"order": {
"id": "669229c6-84f3-45c5-a420-6cda8ed42c35",
"externalIdentifier": "123456",
"createdAt": "2020-06-27T05:19:30Z",
"updatedAt": "2020-06-27T05:19:30Z",
"orderListItems": [
{
"id": "66109",
"name": "Snow Country Advanced 11.5\" X 4'",
"quantity": 22,
"sku": "556503",
"listItem": {
"color": "11.5\" x 4'",
"unitCost": 10,
"totalCost": 220,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": null
}
},
{
"id": "66110",
"name": "GAF ProStart Starter Shingles",
"quantity": 3,
"sku": "353731",
"listItem": {
"color": "120.33'/BD",
"unitCost": 40,
"totalCost": 120,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": null
}
},
{
"id": "66111",
"name": "Rapid A 11 Staples -3/8\"",
"quantity": 3,
"sku": "351682",
"listItem": {
"color": "3/8\"",
"unitCost": 5,
"totalCost": 15,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": null
}
},
{
"id": "66112",
"name": "GAF WeatherWatch",
"quantity": 2,
"sku": "10643",
"listItem": {
"color": "2 SQ. Roll",
"unitCost": 80,
"totalCost": 160,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": null
}
},
{
"id": "66113",
"name": "GAF Tiger Paw",
"quantity": 2,
"sku": "401173",
"listItem": {
"color": "10 SQ. Roll",
"unitCost": 150,
"totalCost": 300,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": {
"id": 670,
"vendorName": "Beacon",
"provider": {
"identifier": "BEACON"
}
}
}
},
{
"id": "66114",
"name": "8' X 4' Plywood",
"quantity": 1,
"sku": "276548",
"listItem": {
"color": "4' x 8'",
"unitCost": 17,
"totalCost": 17,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": {
"id": 670,
"vendorName": "Beacon",
"provider": {
"identifier": "BEACON"
}
}
}
},
{
"id": "66115",
"name": "Fanaco Coil Nails",
"quantity": 2,
"sku": "12099",
"listItem": {
"color": "1-1/4\"",
"unitCost": 30,
"totalCost": 60,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": {
"id": 670,
"vendorName": "Beacon",
"provider": {
"identifier": "BEACON"
}
}
}
},
{
"id": "66116",
"name": "Caulk",
"quantity": 2,
"sku": "11590",
"listItem": {
"color": "Black",
"unitCost": 7,
"totalCost": 14,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": {
"id": 670,
"vendorName": "Beacon",
"provider": {
"identifier": "BEACON"
}
}
}
},
{
"id": "66117",
"name": "1.5\" Lead Cap",
"quantity": 1,
"sku": "560193",
"listItem": {
"color": "Black",
"unitCost": 11,
"totalCost": 11,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": {
"id": 670,
"vendorName": "Beacon",
"provider": {
"identifier": "BEACON"
}
}
}
},
{
"id": "66118",
"name": "24\" W Valley Flashing",
"quantity": 9,
"sku": "404527",
"listItem": {
"color": "Black",
"unitCost": 21,
"totalCost": 189,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": {
"id": 670,
"vendorName": "Beacon",
"provider": {
"identifier": "BEACON"
}
}
}
},
{
"id": "66119",
"name": "GAF Cobra Intake Pro\t",
"quantity": 6,
"sku": "486824",
"listItem": {
"color": "11\" x 20'",
"unitCost": 50,
"totalCost": 300,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": null
}
},
{
"id": "66120",
"name": "Ultimate Pipe Flashing",
"quantity": 1,
"sku": "361353",
"listItem": {
"color": "White",
"unitCost": 50,
"totalCost": 50,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": null
}
},
{
"id": "66121",
"name": "Big T Metal Flashing",
"quantity": 20,
"sku": "480581",
"listItem": {
"color": "Mill",
"unitCost": 0,
"totalCost": 0,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": null
}
},
{
"id": "66122",
"name": "GAF - Timberline HD Shingles",
"quantity": 91,
"sku": null,
"listItem": {
"color": "Slate",
"unitCost": 30,
"totalCost": 2730,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": {
"id": 670,
"vendorName": "Beacon",
"provider": {
"identifier": "BEACON"
}
}
}
},
{
"id": "66123",
"name": "GAF Ridglass Hip And Ridge Shingles",
"quantity": 4,
"sku": null,
"listItem": {
"color": "Charcoal",
"unitCost": 60,
"totalCost": 240,
"taxPercent": 0,
"tradeType": "ROOF",
"type": "MATERIAL",
"vendor": {
"id": 670,
"vendorName": "Beacon",
"provider": {
"identifier": "BEACON"
}
}
}
}
]
}
}
]
}
}
curl -X POST "https://graph.hover.to/graphql" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{"query": "{ projectManagementOrderDocuments(orderDocumentIds: \"$order_document_id\") { id createdAt updatedAt userId pdf { redirectUrl } order { id externalIdentifier createdAt updatedAt orderListItems { id name quantity sku listItem { color unitCost totalCost taxPercent tradeType type vendor { id vendorName provider { identifier } } } } } } }"}'
Request:
Method: POST
URL: https://graph.hover.to/graphql
Headers:
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
Body:
Type: Raw (JSON)
Content:
{
"query": "{ projectManagementOrderDocuments(orderDocumentIds: \"$order_document_id\") { id createdAt updatedAt userId pdf { redirectUrl } order { id externalIdentifier createdAt updatedAt orderListItems { id name quantity sku listItem { color unitCost totalCost taxPercent tradeType type vendor { id vendorName provider { identifier } } } } } } }"
}