How to Get a List of Estimates, Biditems, Activities, or Resources

Prerequisites

Before starting, ensure you have the following:

Access to HeavyBid APIs.
An API Client (Client ID and Secret) used to generate an authentication token for API utilization.
API Client must possess necessary scopes: heavybid:read heavybid:write heavybid:system:read heavybid:system:write on token generation.

📘
Refer to the Getting Started with Request Tokens guide for details on how to authenticate.

Get Business Units

🔄
Use the HeavyBid GET All Business Units endpoint to acquire the critical businessUnitid field.

Purpose: Get the list of business units within your organization. The returned id is required for pulling data.

Response: The response will provide one or more business units with an id field, this id is your businessUnitId. This businessUnitId is needed to utilize the endpoints listed in this guide.

Get Estimates

🔄
Use the HeavyBid GET All Estimates endpoint to retrieve your estimates.

Purpose: To get estimates. You may filter what is returned by the response by using the $top, $skip, $filter, and $orderby parameters. Use of the $filter parameter is detailed in the Filtering Section.

Response: The response will provide the data for one or more of the estimates in your chosen business unit.

Filtering

Filtering for estimate, bidtem, activity, and resource endpoints is handled through the $filter parameter.

ℹ️
You can return a subset of data by writing filtering functions into the $filter parameter.
When filtering on string fields: enclose values in single quotes.
When filtering on guid, datetime, and numbers: do not enclose values in quotes.

ℹ️
Example Estimate Filter Functions
Function to retrieve estimates that include earth in the name
$filter=contains(name,'earth')
Function to retrieve estimates modified since Jan 1 2022
$filter=lastModified gt 2022-01-01T00:00:00.000Z
Function to retrieve estimates with a bid total greater than 20,000,000
$filter=totals/bidTotal_Bid gt 20000000

This is the full list of operators available for use in $filter parameter function strings:

eq - Equals
gt - Greater Than
lt - Less Than
contains
in - Includes

Pagination

By default, responses for these endpoints are limited to 100 results. You can adjust this with the $top parameter. You can request a set of results beyond the limit by using the $skip parameter.

ℹ️
For example, if you want to get the results 11-20 after setting $top to 10 results, you would set $top=10 $skip=10.
The endpoint would skip results #1-10 and then deliver you results #11-20.

⚠️
It is important that all integrations are written in a way to take advantage of paging by utilizing the currentTopValue, currentSkipValue, and nextSkipValue fields returned by these endpoints.

🛑
While we don't currently limit the maximum value of the $top parameter, your integration may run into issues when a significant amount of records are pulled at once.
Additionally, HCSS may decide to enforce strict pagination by setting a maximum $top value in the future. This would not be considered a breaking change.

Get Bid Items

🔄
Use the HeavyBid GET All Bidtems endpoint to retrieve bid items.

Purpose: To get bid items. You may filter what is returned by the response by using the $top, $skip, $filter, and $orderby parameters. Use of the $filter parameter is detailed in the Filtering Section.

Response: The response will provide the data of one or more Bid Items in your chosen business unit.

Get Activities

🔄
Use the HeavyBid GET All Activities endpoint to retrieve activities.

Purpose: To get activities. You may filter what is returned by the response by using the $top, $skip, $filter, and $orderby parameters. Use of the $filter parameter is detailed in the Filtering Section.

Response: The response will provide the data of one or more Activities in your chosen business unit.

Get Resources

🔄
Use the HeavyBid GET All Resources endpoint to retrieve resources.

Purpose: To get resources. You may filter what is returned by the response by using the $top, $skip, $filter, and $orderby parameters. Use of the $filter parameter is detailed in the Filtering Section.

Response: The response will provide the data of one or more Resources in your chosen business unit.