Tutorials

Introduction

Introduction

Create Projects and Plans

Create a Takeoff

Create a Takeoff

Create a New Estimate and Proposal
- Update an Existing Estimate and Proposal
- Add Default Tax Rate to Cost Types

Download or Print Takeoffs, Plans, and Proposals

Introduction

This section is intended as a resource to help you in the development of your integration, providing API tutorials for the most common integration features. (All API documentation is available in the API Reference.)

It will be helpful to have a general understanding of how the STACK Takeoff and Estimating application works before jumping into the individual tutorials and beginning development.

To that end, below is the basic workflow a user would follow when using the app and descriptions of the terminology used. You can also reference our online help center for more information on specific features and how they are used and sign up for a free account to experience the app for yourself.

Basic Takeoff and Estimating Workflow

Create a Project
Upload Files
Create Takeoff(s)
- a. Draw measurements/counts
- b. Add items and assemblies
Create Estimate and Proposal (when you create an estimate in the STACK application, a proposal is also created)
- a. Adjust final quantities and prices, add markup
- b. Add any non-measured costs – equipment, overhead, taxes, etc.
Customize and download Proposal

All takeoff and estimating work in STACK are performed within the context of a Project. A project is a grouping of plans and other documentation, along with relevant metadata like bid dates.

Files are uploaded into STACK and are either split into component pages for use in the STACK plan canvas area or are kept whole and available for download. The uploaded file is commonly referred as pages, plans or plan sets.

Plan pages are organized under Folders. You can use folders to separate some pages from others. For example, you can create a folder dedicated to the architectural set and another folder dedicated to the electrical set. You can also use folders to organize revisions or addendums sets as part of version control.

A Takeoff represents a building detail or system the contractor needs to estimate. For example, a takeoff could be metal trim around a window or represent the framing, insulation, and drywall in a wall system.

You draw measurements with each takeoff to show where the building detail occurs on a plan page. STACK will calculate all data for each measurement first, then sum those values on reports and estimates.

NOTE: Takeoffs are linked to a project and cannot be created on their own.

An Estimate represents the takeoff data – material, equipment, labor, and subcontracting quantities and costs – required to perform the job. A contractor or estimator can adjust the final quantities, prices, and markups on the estimate worksheet before downloading the Proposal, or final document, to send to the customer. They can also add project-specific costs or non-measured costs. You can create as many estimates and proposals per project as needed.

NOTE: Estimates and proposals are unique to a given project and cannot be created alone.

Create Projects and Plans

A project is a grouping of plans and other documentation, along with relevant metadata like bid dates. All takeoff and estimating work in STACK are performed within the context of a project.

Create a Project

To create a new project, use the Create a Project endpoint (see Projects section in the API Reference) and provide the following:

NOTE: Only bidDate and name are required fields, the rest are optional.

• bidDate (required)
• name (required)
• notes
• expirationDate
• sourceId
• source
• dateCreated
• addressLine1
• addressLine2
• city
• stateId *
• postalCode
• countryId *

The project will be created, and a new projectId will be returned.

* To update the address, include the stateId from the List States endpoint (see States section in the API Reference) and the countryId from the List Countries endpoint (see Countries section in the API Reference). Refer to Retrieve a List of State or Country IDs for more details.

Request Headers:

POST https://{server}/api/v2/Projects
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
content-type: application/json;charset=UTF-8
accept: application/json, text/plain, */*

Update Project Information

To update the project information, use the Update a Project endpoint (see Projects section in the API Reference) and provide the latest information.

You can update:

• Project Name
• Bid Date
• Notes
• Assigned to
• Status
• Address *

Create and Select Folders

Plan pages are organized under folders. You can use folders to separate some pages from others. For example, you can create a folder dedicated to the architectural set and another folder dedicated to the electrical set. You can also use folders to organize revisions or addendums sets as part of version control.

Create a New Folder

To create a new folder, call the Create a Folder in Project root endpoint (see Folders section in the API Reference) with:

projectId
folderName
parentFolderId

The new folder will be placed under the parent folder.

To create the folder at the top-level, set the parentFolderId equal to 0 (zero).

A new folderId will be returned in the response. It can be used when uploading a plan or creating additional subfolders, thus creating a folder hierarchy.

Request Headers:

POST https://{server}/api/v2/Projects/{projectId}/Folders
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
content-type: application/json;charset=UTF-8
accept: application/json, text/plain, */*

Select an Existing Folder

STACK automatically creates three folders by default:

Bookmarks – This folder is a list of favorited plan pages only. Files cannot be uploaded to this folder.
Plans – Files uploaded to this folder will be processed into individual pages and a thumbnail image, or preview, of the file will be created.

Supporting Documents – Files uploaded to this folder will be stored like a file storage repository, similar to Google Drive or OneDrive. The files will not generate a preview/thumbnail image.

When adding a file to a project, a folderId is required.

To select an existing folder:

Call the List Folders in Project Root endpoint (see Folders section in the API Reference) to retrieve the list of top-level folders.
The folderId returned in the response can be used for subsequent calls to the List Folders in a Folder endpoint (see Folders section in the API Reference) to navigate the hierarchy of folders until the desired folder is located.

Request Headers – List Folders in Project Root:

GET https://{server}/api/v2/Projects/{projectId}/Folders
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
content-type: application/json;charset=UTF-8
accept: application/json, text/plain, */*

Request Headers – List Folders in a Folder:

GET https://{server}/api/v2/Folders/{folderId}/Folders
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
content-type: application/json;charset=UTF-8
accept: application/json, text/plain, */*

Get a Folder

To retrieve a folder, call the Get a Folder endpoint (see Folders section in the API Reference).

See the Folders API documentation for additional details.

Request Headers – Get a Folder:

GET https://{server}/api/v2/Folders/{folderId}
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
content-type: application/json;charset=UTF-8
accept: application/json, text/plain, */*

Update an Existing Folder

You can update the properties of a folder by calling the Update an existing Folder endpoint (see Folders section in the API Reference) with the folderId.

You can update:

• folderName
• parentFolderId
• projectId

Upload and Update the Details of a File

Files are uploaded into STACK and are either split into component pages for use in the STACK plan canvas area or are kept whole and available for download. The uploaded file is commonly referred as plans or plan sets.

STACK supports the following file types:

• PDF
• ZIP
• JPG
• TIFF

NOTE: If you are working with PNG, CAD, or BIM files (e.g., DWF, DWG, DXF) you will need to convert them into one of the formats above.

Upload a New Plan (File)

To upload a new plan:

Use the Upload a plan, supporting document, or zip to a folder endpoint (see Files section in the API Reference) to upload a file or a compressed zip file containing the plan(s).
A folderId is required for this request.

• To select the default top-level folder as the location, set the folderId to 0 (zero)
• To select a different location for the plan, reference Create a New Folder or Select an Existing Folder.

See the API documentation for a sample request.

Request Headers – Files Upload a Plan:

POST https://{server}/api/v2/Folders/{folderId}/Files HTTP/1.1
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
Content-Type: multipart/form-data; boundary=—-WebKitFormBoundaryhBGJZvGSuQiPwHsU
——WebKitFormBoundaryhBGJZvGSuQiPwHsU
Content-Disposition: form-data; name=”body”
{ “fileName”:”file.png”, “fileVersion”:”1.0″, “folderId”:149, “isPlan”:true, “projectId”:157}
——WebKitFormBoundaryhBGJZvGSuQiPwHsU
Content-Disposition: form-data; name=”file”; filename=”file.png”
Content-Type: application/pdf

To determine when the plan has completed the upload process:

Use the List Pages on a Takeoff endpoint (see Pages section in the API Reference).
A list of pages for the takeoffId will be returned.
Select the page with the fileId returned from the file upload response and inspect the ocrStatus field.

• If the status is set to “Completed,” the file upload processing is complete.
• If the status is “Pending” or “Running,” retry the call until the file has completed processing.

Request Headers – List Pages on a Takeoff:

GET https://{server}/api/v2/Takeoffs/{takeoffId}/Pages
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
content-type: application/json;charset=UTF-8
accept: application/json, text/plain, */*

Get the Details of a File

To retrieve the details of a file, use the Get the details of a File endpoint (see Files section in the API Reference) and provide the fileId.

Update the File Properties

To update the properties of a file, use the Update the properties of a File endpoint (see Files section in the API Reference) and provide the fileId.

You can update:

• FileName
• FolderId *
• isPlan
• fileVersion

*To move the file, list the new folderId. See Select an Existing Folder for more details.

Set a Custom Scale

A scaled drawing shows a real object with accurate size reduced or enlarged by a certain amount (called the scale).

Architectural sets tend to reference 1’-0”, such as ¼” = 1’-0” or 1/8” = 1’-0”.

Engineering sets tend to reference 1”, such as 1” = 10’ or 1” = 20’.

Metric scales are available.

To set a scale for a plan:

Call the Set the Scale on a page endpoint (see Pages section in the API Reference).
Provide the takeoffId and fileId for the plan with a Set Page Scale Request object.
The request object allows the Numerator and Denominator for the scale to be set along with a Boolean identifying if the scale is metric.

Request Headers:

POST https://{server}/api/v2/Takeoffs/{takeoffId}/Pages/{pageId}/Scale
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
content-type: application/json;charset=UTF-8
accept: application/json, text/plain, */*

Create a Takeoff

A takeoff represents a building detail or system the contractor needs to estimate.
For example, a takeoff could be metal trim around a window or represent the framing, insulation, and drywall in a wall system.

You choose the measurement type for the takeoff:

Measurement Type	Description
Area	Measure the flat area by clicking on each corner
Linear	Measure the distance by clicking each point
Count	Count objects by clicking on the plan to place a symbol
Linear with Drop	Measure a distance and count drops
Pitched Area	Enter the rise and run to measure a pitched or sloping area
Pitched Linear	Enter the rise and run to measure a pitched or sloping distance
Surface Area	Enter the wall height and measure area by clicking on the endpoints of each wall
Volume 2D	Enter the depth and measure volume by clicking on each corner
Volume 3D	Enter the width and height and measure volume by clicking on each point

You draw measurements with each takeoff to show where the building condition occurs on a plan page. STACK will calculate all data for each measurement first, then sum those values on reports and estimates.

NOTE: Takeoffs are linked to a project and cannot be created on their own.

Refer to the following sections prior to creating a takeoff:

Create Projects and Plans

Upload and Update the Details of a File

Set a Custom Scale

To create a new takeoff:

Use the projectId returned in the Create Project response to call the Create a Takeoff on a Project endpoint (see Projects section in the API Reference).
A takeoffId will be assigned during the creation and returned in the response.

You may want to manually draw a measurement or two if you plan to use this takeoff for other features, like reports and estimates.

Request Headers:

POST https://{server}/api/v2/Projects/{projectId}/CreateTakeoff
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
content-type: application/json;charset=UTF-8
accept: application/json, text/plain, */*

Create a New Estimate and Proposal (EstimateProposal)

When you create an estimate in the STACK application, a proposal is also created. An estimate represents the takeoff data – material, equipment, labor, and subcontracting quantities and costs – required to perform the job. A contractor or estimator can adjust the final quantities, prices, and markups on the estimate worksheet before downloading the proposal, or final document, to send to the customer. They can also add project-specific costs or non-measured costs. You can create as many estimates and proposals per project as needed.

NOTE: Estimates and proposals are unique to a given project and cannot be created alone.

Refer to the following sections prior to creating an estimate and proposal:

Create Projects and Plans

Upload and Update the Details of a File

Set a Custom Scale

Create a Takeoff

To create a new EstimateProposal:

Use the takeoffId returned in the Create a Takeoff response.
Provide an estimate type (Material or Unit).
Call the Create an EstimateProposal endpoint (see EstimateProposals section in the API Reference) to create a new EstimateProposal.
If available, the default tax percent for specified cost types can be included in the request.

If successful, a new EstimateProposal will be created with a unique proposalId that can be used for subsequent calls.

See Add Default Tax Rate to Cost Types for additional data that can be added during the creation of the EstimateProposal.

Request Headers:

POST https://{server}/api/v2/EstimateProposals
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
content-type: application/json;charset=UTF-8
accept: application/json, text/plain, */*

Update an Existing Estimate and Proposal (EstimateProposal)

You can update the details of an existing EstimateProposal by sending the following information to the Update an existing EstimateProposal endpoint (see EstimateProposals section in the API Reference):

• proposalId
• name
• preparedFor
• scopeOfWork
• termsAndConditions
• roundingEnabled
• includedMeasurements
• overheadMarkupPercent
• additionalMarkupPercent
• taxes
• nonMeasuredCosts

Add Default Tax Rate to Cost Types (CostTypes)

Cost types are designations – equipment, labor, material, subcontractor and/or custom cost type(s) – that can be applied to individual items. You can apply multiple cost types to an item and assign a different unit cost and accounting code to the item for each cost type. The data for each cost type applied will appear on Item Reports and the Material and Labor Estimate.

You can add default tax rates to cost types. This will automatically apply the assigned tax rate to items with the designated cost type. For items with multiple cost types, the item will appear as a line item under each cost type.

When creating a new estimate (EstimateProposal), a list of Tax Request objects can be included in the Taxes field of the Create an EstimateProposal Request object. This list represents the default tax percent that will be applied to an item added to the takeoff for the associated cost type.

To retrieve a list of all available CostTypes:

Use the List CostTypes endpoint (see CostTypes section in the API Reference).
When making the call, set the inferred query parameter and the catalog query parameter to true.

See the CostTypes API Documentation for additional details.

Request Headers:

GET https://{server}/api/v2/CostTypes
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
content-type: application/json;charset=UTF-8
accept: application/json, text/plain, */*

Download or Print Takeoffs, Plans, and Proposals

Download Pages for a Takeoff

Once a plan has been marked-up with measurements and markups, you can export and download a local PDF file.

The download process consists of two steps:

Create a Print Job using the Create a Print job endpoint (see Print section in the API Reference) to return a jobId.
Use jobId to retrieve the document via the Download document for job endpoint (see DocumentJob section in the API Reference).
- a. If the Print Job is complete and the file is ready for download, the document stream is returned.
- b. If the Print Job is still processing, status code 102 is returned. (Wait a moment and retry the retrieval.)

See the Print and DocumentJob API documentation for additional details.

Request Headers – Create a Print Job:

POST https://{server}/api/v2/Print/Takeoff/{takeoffId}
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
content-type: application/json;charset=UTF-8
accept: application/json, text/plain, */*

Request Headers – Download Document for Job:

GET https://{server}/api/v2/DocumentJob/{jobId}
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
content-type: application/json;charset=UTF-8
accept: application/json, text/plain, */*

Retrieve Pages for a Takeoff

To retrieve all available pages for a given takeoff, use the List Pages on a Takeoff endpoint (see Pages section in the API Reference).

This endpoint will return a list of page objects in the response.

See the Pages API documentation for more details.

Request Headers:

Retrieve an Estimate and Proposal (EstimateProposal)

When an estimate is created in the STACK application, a proposal is also created. They display the takeoff data – material, equipment, labor, and subcontracting quantities and costs – required to perform the job. The estimate worksheet is where the estimator adds any project-specific or non-measured costs and adjusts the final quantities, prices, and markups. The proposal is the final document that can be downloaded and sent to the customer.

There can be multiple estimates and proposals per project.

To retrieve an EstimateProposal including all line-item details:

Use the Get an EstimateProposal endpoint (see EstimateProposals section in the API Reference).
Provide a proposalId in the URL address.
The proposalId can be retrieved from the list of EstimateProposals returned from Retrieve Estimates and Proposals (EstimateProposals) for a Takeoff or from the response returned after Create a New EstimateProposal.
A fully hydrated EstimateProposal is returned in the response.

See the EstimateProposals API documentation for more details.

Request Headers:

GET https://{server}/api/v2/EstimateProposals/{proposalId}
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
content-type: application/json;charset=UTF-8
accept: application/json, text/plain, */*

Retrieve an Estimate (EstimateProposal) Report

The EstimateProposal report provides detailed information for a given EstimateProposal. The details are similar to the estimate information available in the STACK Application – reports view.

To retrieve an EstimateProposals report for a given proposalId:

Use the Get an EstimateProposal Report endpoint (see Reports section in the API Reference).
Provide a proposalId in the call.
An EstimateProposals Report will be returned in the response.
By default, the line-item details are rolled up by item CostType.
To retrieve additional detail, set the expand query string parameter to true.

This view is the same information presented in the STACK application Estimate Reports with Groupings set to None.
See the Reports API documentation for additional details.

Request Headers:

POST https://{server}/api/v2/Reports/EstimateProposals/{proposalId}
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
content-type: application/json;charset=UTF-8
accept: application/json, text/plain, */*

Retrieve Estimates and Proposals (EstimateProposals) for a Takeoff

To retrieve the list of EstimateProposals for a given Takeoff:

Use the List EstimateProposals on a Takeoff endpoint (see Takeoffs section in the API Reference).
Provide a takeoffId in the URL.
A list of partially hydrated EstimateProposals will be returned in the response.
To retrieve the completely hydrated EstimateProposal, use the proposalId returned in the response and see Retrieve an Estimate and Proposal (EstimateProposal).

See the Takeoffs API documentation for additional details.

Request Headers:

Retrieve a List of State or Country IDs

The STACK API has unique state and country IDs. For domain objects (e.g., EstimateProposalPreparedFor), where you want to include the state and/or country in an address, you will need to retrieve and include stateId and/or countryId.

To retrieve a list of states and their IDs, use the List States endpoint (see States section in the API Reference).

Request Headers:

GET https://{server}/api/v2/States
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
content-type: application/json;charset=UTF-8
accept: application/json, text/plain, */*
accept-encoding: gzip, deflate, br

For a list of country IDs, use the List Countries endpoint (see Countries section in the API Reference).

Request Headers:

GET https://{server}/api/v2/Countries
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
content-type: application/json;charset=UTF-8
accept: application/json, text/plain, */*