STACK Developers Logo
REQUEST API ACCESS
REQUEST API ACCESS

Tutorials

Introduction

Introduction

Create Projects & Plans

Create a Takeoff

Create a Takeoff

Create a New Estimate

Update an Existing Estimate
Add Default Tax Rate to Cost Types

Create a New Estimate

Download Pages for a Takeoff
Retrieve Pages for a Takeoff
Retrieve an Estimate
Retrieve an Estimate Report
Retrieve Estimates for a Takeoff
Retrieve a List of State or Country IDs

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

  1. Create a Project
  2. Upload Files
  3. Create Takeoff(s)
    • a.   Draw measurements/counts
    • b.   Add items and assemblies
  4. Create Estimate 
    • a.   Adjust final quantities and prices, add markup
    • b.   Add any non-measured costs – equipment, overhead, taxes, etc.

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 per project as needed.

NOTE: Estimates 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 (this defaults to one year after the bidDate)
  • • 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 *

* 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.

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:

  1. projectId
  2. folderName
  3. 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:

  1. Call the List Folders in Project Root endpoint (see Folders section in the API Reference) to retrieve the list of top-level folders.
  2. 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
  • • PNG

NOTE: If you are working with 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:

  1. 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).
  2. A folderId is required for this request.

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:

  1. Use the List Pages on a Takeoff endpoint (see Pages section in the API Reference).
  2. A list of pages for the takeoffId will be returned.
  3. 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:

  1. Call the Set the Scale on a page endpoint (see Pages section in the API Reference).
  2. 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:

  1. 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).
  2. 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 (Estimate)

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 per project as needed.

NOTE: Estimates 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:

  1. Use the takeoffId returned in the Create a Takeoff response.
  2. Provide an estimate type (Material or Unit).
  3. Call the Create an EstimateProposal endpoint (see Estimate 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/Estimate
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 Estimate endpoint (see Estimate 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:

  1. Use the List CostTypes endpoint (see CostTypes section in the API Reference).
  2. 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 and Plans

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:

  1. Create a Print Job using the Create a Print job endpoint (see Print section in the API Reference) to return a jobId.
  2. 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:

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, */*

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 per project.

To retrieve an EstimateProposal including all line-item details:

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

See the Estimate API documentation for more details.

Request Headers:

GET https://{server}/api/v2/Estimate/{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 Estimate report for a given proposalId:

  1. Use the Get an EstimateProposal Report endpoint (see Reports section in the API Reference).
  2. Provide a proposalId in the call.
  3. An Estimate Report will be returned in the response.
    By default, the line-item details are rolled up by item CostType.
  4. 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/Estimate/{proposalId}
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
content-type: application/json;charset=UTF-8
accept: application/json, text/plain, */*

Retrieve Estimates (Estimate) for a Takeoff

To retrieve the list of Estimates for a given Takeoff:

  1. Use the List Estimates on a Takeoff endpoint (see Takeoffs section in the API Reference).
  2. Provide a takeoffId in the URL.
  3. A list of partially hydrated Estimates will be returned in the response.
  4. To retrieve the completely hydrated Estimate, 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:

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

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, */*




Facebook-f Twitter Linkedin-in Instagram Youtube

© STACK Construction Technologies. All Rights Reserved
9999 Carver Road | Suite 300 | Cincinnati, OH 45242

Privacy Policy Terms of Use Security & Reliability

Shopping Basket

Want to get more info on STACK's API connection?

Complete the form below and we will be in touch soon.