Documentation

Here’s all the info you need to get started with the STACK API.

Getting Started

Introduction

Welcome!

This document describes the open STACK API, which you can use to develop applications to connect your STACK account to other systems or software tools.

To successfully use this document, you will need a basic understanding of APIs and web development concepts.

Integration Types

Integration with your own account - a Custom Integration

A Custom Integration is a connection between your own STACK account, that you use and control, and another system. These are typically created by STACK customers to automate data movement and manual workflows. You’ll use a Custom Integration to make your team more efficient and effective by connecting STACK to other systems used within your business. Only you and your team will have access to your Custom Integration, so the approval process is lighter than for a Partner Integration.

Integration with the STACK user community - a Partner Integration

A Partner Integration is typically created by another technology company to connect their own application to STACK for the benefit of our mutual customers. These integrations may be listed on the STACK Marketplace so that they are available to the entire STACK community.

Getting API Access

The first step to creating any type of integration with the STACK API is to request access to our developer sandbox environment. To request access:
1. Just hit the Request API Access button at the top of the page or send an email to apiaccessrequest@stackct.com. In the body of the email, include the following information:
     * First and Last Name
     * STACK Username
     * The type of integration you are exploring (Custom Integration or Partner Integration)
     * A brief description of the purpose of your integration
2. Our API team will review your request and will respond within 2 business days to setup an API kick-off call
3. After a brief kick-off session, you will be granted API credentials for our Partner Acceptance Testing sandbox environment

Fundamentals

Partner Accounts and Credentials

If you’re building a Partner Integration you will need a Partner Account. This is a STACK account that will link to your API credentials. Although your integration may connect directly to a customer account and not put any data into the Partner Account, the Partner Account is required for logging purposes.

You will create your Partner Account by setting up an account first within the PAT environment and later within the STACK production environment. More information will be provided in the API kick-off session.

Companies and Projects

A Company is a grouping of Users and Projects within STACK. Users are linked to a Company and thereby granted access to resources within the Company (Projects, Items, Assemblies, etc.).

A Project is a grouping of plans and other documentation along with relevant metadata such as bid dates. All takeoff and estimating work done within STACK is done within the context of a Project.

Authentication

The first step in integrating with the STACK API is understanding the API’s authorization process. Any time a Partner makes a request to the STACK API, whether on behalf of the Partner or on behalf of a User affiliated with a Partner, they must be authorized through STACK’s Authorization Server.

OAuth 2.0 - Two-Legged Authorization

Two-Legged authorization is used when your integration is writing data into or reading from an account that you control. This is typically server-to-server communication where you may create Project, Plans, Files directly into your own account.

API Client Credentials

Obtaining Client Credentials

STACK will provide a Partner with their own clientId and client secret, together these are the API Credentials. The clientId and client secret are combined, separated by a colon and
base64 encoded as follows:

  1. Combine the clientId and client secret: ex. “5:11728663-C8DD-4B84-9B2B-4E3916631A54”
  2. Ensure that the “clientId:client-secret” are Base64 Encoded.

Add the encoded client credentials to the Authorization Header of the request:

Authorization: Basic
NToxMTcyODY2My1DOERELTRCODQtOUIyQi00RTM5MTY2MzFBNTQ=

Obtaining an Access Token on Behalf of the Partner

To obtain an access_token, a Partner must make a POST request to this endpoint: “https://{server}/OAuth/Token” and include the Client Credentials in the Authorization header of the request. Replace {server} with the sandbox server URL provided along with your API credentials. A Grant Type is also required in the body of the request; “grant_type=client_credentials”.

Request:

POST https://{server}/OAuth/Token
Authorization: Basic
VEhJUyBJUyBCQVNFNjQgU1RSSU5HIE9GIFlPVVIgUEFSVE5FUklEfFBBUlRORVIgU0VDUkVU
Cg==
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials

Note there must be no line endings after the form data, if an invalid grant_type will be returned. This includes carriage returns (0x0d) and or new lines characters (0x0a).

Response:

{
“access_token”:
“tG05IRnPA3hBINzKmIU28zR60xqoachJzI5av5RMTeCRE8uNzeYt95w9XOmNon-4lF3KXQj
gakNfMT9nHgtRxItobmdkZ4xi849LlMhS6SKyCQvHI….”,
“token_type”: “Bearer”,
“expires_in”: 28799,
“refresh_token”:
“898c0a5d1a5c42a9898caf23de67467847db7c42e53f4aa8b599eadc495c55e4”
}

Note the access_token in the response. The access_token will be used in the Bearer Authorization Header of any future requests to the API. access_tokens will expire as shown in the expires_in field of the response and will need to be refreshed using the refresh_token.

Field Details:

Field NameTypeLengthPurpose
access_tokenstring2048The access_token will be used in the Bearer Authorization Header of any future requests to the API. access_tokens will expire as shown in the expires_in field of the response and will need to be refreshed using the refresh_token. The length of the field may vary over time so you will experience strings around 1030 bytes but be sure to reserve 2048 bytes in any table column you store it in.
token_typestringAlways "Bearer" indicating that this is how you are to use this token.
expires_inintThe number of seconds that this token is valid for.
refresh_tokenstringAfter expires_in seconds this refresh_token can be used in another API call to retrieve another access_token.

Authenticating Requests to the API

Below is a sample POST to create a Project using STACK’s API:

Request Headers:

POST https://api.ct-test.net/api/v1/Projects HTTP/1.1
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)

See API Reference doc for request detail.

Refreshing Access Tokens

As mentioned above, access_tokens will need to be refreshed. The process is similar to initially obtaining an access_token. Use your Client Credentials in the Authorization header and format your refresh_token as shown in the example below.

Request Header:

POST https://c3.ct-test.net/OAuth/Token HTTP/1.1
Authorization: Basic (your Client Credentials)
Content-Type: application/x-www-form-urlencoded
refresh_token=d826c4204c847bf63a16d271adea23e…&grant_type=refresh_token

Note there must be no line endings after the form data, if an invalid grant_type will be returned. This includes carriage returns (0x0d) and or new lines characters (0x0a).

Response:

{
     “access_token”:”qKDJ5M7LPX-Do3aPCsaIrRzJ1_wsVt_6Whm2dMAkeMYTs1S5uQe…..”,
     “token_type”:”Bearer”,
     “expires_in”:28799,
     “refresh_token”:”b368fd873df3406cb5b35482f68eb1597111ed851cf243df9edeb5e7e52ee4dc”
}

OAuth 2.0 - Three-Legged Authorization

Three-Legged authorization is used when your integration is writing data into or reading from an account on behalf of a user. This requires the user to grant your integration permission to control his or her data. Your application will request to control a user’s account and he must click a button to grant your application the appropriate permissions.

Obtaining Authentication on Behalf of the User

The following will describe how to authorize accessing the API on behalf of a User. The idea is that one of your customers is interacting with your product and you wish to transfer them to STACK. You will already have an access token from the 2 legged workflow above so now you have to gain access for your user.

Sequence Diagram

First, the user must be redirected to STACK’s Authorization Page. This can be accomplished by a redirect url applied to an action the User initiates such as clicking a link on the Partner’s page to view a Project in the STACK Application. The redirect will contain the redirect_uri provided by the Partner and the ClientID provided by STACK:

Request:

https://{server}/OAuth/Authorize?client_id=(your
ClientId)&redirect_uri=(your redirect_uri
encoded)&state=partner-created-value&response_type=code

The ClientID is the ID that STACK provided for you for your Client Credentials.

The redirect_uri is the uri you provided to STACK and is saved in STACK’s database as part of your Partner information. When sent in the query string, the uri must be encoded.

Example:

http%3A%2F%2Fyour%2Fredirect_uri.com

The state parameter is generated by the Partner for the Partner’s use.

The response_type=code part of the query string tells the STACK Authorization Server that you are requesting a one-time-use code (GUID generated by the Authorization Server) to be used to obtain an access_token for your User.

This is an example of what the user will see generated by the STACK Authorization Server

STACK Authorization Server

Once the User grants the Partner access by clicking the “Grant” button, the User will be redirected to the Partner’s redirect_uri and the one-time-use code will be specified in the query string. The query string returned should look like the example below:

Example:

http://your/redirect_uri/?code=7d07711d50c14cfeb0759d262878b03b37c50b063
5614ee8893a166e526da90b&state=partner-created-value

Note the state parameter returned is the same value that was passed to STACK in the original request. The code provided is a short lived and configured to expire in 5 minutes. If the user chooses to click the Cancel button, then a similar redirect will occur back to the Partner redirect_uri with error query string argument indicating the access denied.

http://your/redirect_uri/?error=access_denied&state=partners-unique-value

The customer expectation would be to be presented with the same Partner page that they used to launch STACK. The request for obtaining an access_token for a specific User can be made from the server and requires no additional action on behalf of the User. The request for obtaining an access_token for the User is similar to the request for obtaining an access_token for a Partner.

Request:

POST https://{server}/OAuth/Token HTTP/1.1
Authorization: Basic
VEhJUyBJUyBCQVNFNjQgU1RSSU5HIE9GIFlPVVIgUEFSVE5FUklEfFBBUlRORVIgU0VDUkVU
Cg==
Content-Type: application/x-www-form-urlencoded
code=7d07711d50c14cfeb0759d262878b03b37c5&state=partner-created-value&re
direct_uri=(your redirect_uri)&grant_type=authorization_code

Note there must be no line endings after the form data, or an invalid grant_type will be returned. This includes carriage returns (0x0d) and or new lines characters (0x0a).

Response:

{
“access_token”:”dfsahjaAsdYza1Rp6VSYwJ5M7LPX-Do3aPCsaIrRzJ1_wsVt_6Whm2d
MAkeMYTs1S5uQe…..”,
“token_type”:”Bearer”,
“expires_in”:28799,
“refresh_token”:”jfdkshfjdhs73df3406cb5b35482f68eb1597111e
d851cf243df9e deb5e7e52ee4dc”
}

Note the access_token in the response. The access_token will be used in the Bearer Authorization Header of any future requests to the API. access_tokens will expire as shown in the expires_in field of the response and will need to be refreshed using the refresh_token.

Token Expiry

The authorization code, access token and refresh token all expire at different times. The table below explains the settings you should manage to:

Token TypeExpiry TimeReason
Authorization code5 minutesThis is a short-lived value, transmitted to the partner for immediate use to retrieve an access token
Access token8 hoursAn access token, for 2 legged or 3 legged authentication, represents a logged in session only, and refreshed regularly to ensure the credential status hasn't changed.
Refresh token90 daysThis long period of time represents that the users granted permission is verified at a consistent frequency.

Security

Coming soon!

Partner Sandbox

Regardless of the type of integration you’re building, you will need access to our Partner Acceptance Testing (PAT) environment, commonly known as a “sandbox”, in order to build and test your integration. The PAT environment will allow you to populate it with test data and verify that all of your API calls are working as intended before connecting to the production STACK environment. All integrations must be verified in PAT by the STACK team before obtaining production access.

To request PAT access, follow the instructions in the Getting API Access section of this document.

Tutorials

All API documentation is available in the API Reference.

Creating Projects and Plans

Coming soon!

Creating a List of Takeoffs

Coming soon!

Managing Items and Assemblies

Coming soon!

Retrieving Quantities and Costs

Coming soon!

Downloading Plans and Proposals

Coming soon!

Getting Help

Support Requests

We’re happy to help make your connection to the STACK API as seamless as possible. Please send an email to apihelp@stackct.com with any questions. Be sure to include your name and STACK username in the email.

Shopping Basket

Before You Go...

Get The Contractor’s Ultimate Guide to Bidding and Winning More Profitable Work.
 
You’ll discover 9 actionable steps to increase your bottom line.