BuildingConnected API Field Guide
This field guide is intended to cover basic product knowledge of the BuildingConnected API and describe key points of differentiation with other Autodesk Construction Cloud products.
Overview of BuildingConnected Pro and Bid Board
BuildingConnected functionally operates in two distinct workflows:
- Finding trade partners and bidding out work (BuildingConnected Pro)
- Consolidating opportunities to bid on work (Bid Board Pro)
Both BC Pro and Bid Board sit atop the Builders Network, which is a real-time, cloud-based network for construction companies. There are no separate instances of BuildingConnected.
BuildingConnected Pro (BC Pro) enables companies to find relevant contractors to bid on their construction projects. The workflow is ideal for owners looking to invite general contractors, for general contractors looking to invite subcontractors, and for subcontractors looking to find their own subcontractors and/or material suppliers.
All invites issued via BC Pro create corresponding opportunities on Bid Board. Bid Board Pro enables companies to effectively organize all the invites they receive from BC Pro as well as to consolidate invites received from other providers. For more information, see the BuildingConnected website.
BuildingConnected Projects Versus ACC Projects
BuildingConnected projects are functionally distinct from ACC and BIM 360 projects, and the BuildingConnected API’s 24-character project ID is also different from ACC project UUIDs.
However, BuildingConnected projects can be linked to ACC projects. We’ve designed project linking in BC Pro to enable you to map multiple BC projects to one ACC project.
To determine which ACC project (if any) is currently linked from a given BC Pro project, call GET projects and examine the returned currentAccLinkedProjectId
field to find the ACC project ID. You can confirm the ACC project ID by following the Retrieve ACC Account and Project ID tutorial.
Authentication
BuildingConnected accepts requests using only 3-legged authentication (3LO). Note that 3LO does not require users to manually authorize each request. APS provides refresh tokens that enable an application to remain persistently authenticated indefinitely. Refresh tokens only expire after 14 days. They can be exchanged for a new refresh token at any time during that period, giving your application the ability to refresh its authentication without requiring a user to log in.
Note that If you are creating a direct PowerBI application, follow the PKCE authentication tutorial. We recommend that you set up an Extract, Transform, and Load (ETL) process to maximize access to your data.
The Project Data Model
BC Pro’s data model cascades from a project. Each project should represent one phase of bidding for a construction project. Each project has many bid packages, each of which is meant to represent one scope of work.

Bid packages are the primary container for invites, and for the bids on those invites. You might invite the same company on multiple bid packages (a common example is when electrical subs are invited to the “electrical” package and “fire alarms” package).
You direct an invite to a single company; it’s a container for that company’s bid for a specific scope of work. Within an invite there may be many invitees, which represent employees at that bidder’s company.
Note that the invite holder may forward the invite to their own subcontractors or vendors and those invited parties may be listed as invitees, but the invite is still held by the original invited company.
Invites
There are three ways to add bidders to bid packages in BuildingConnected:
- By adding bidders using BuildingConnected’s native search & recommended bidder features (not supported over API)
- By creating a bid package from a template and including a pre-fixed list of bidders
- By manually entering the email addresses
As described above, users are aggregated as invitees on a single invite belonging to a single company. You can add bidders to a bid package without knowing the companyId they belong to. BuildingConnected will handle the logic of assigning the invitee to the correct invite/company pair.
An invitee can be a “ghost”, meaning they have not yet logged into BuildingConnected. If the invited bidder is a ghost, the invite may be created with name “Unknown Company”. A temporary name can provided using the placeholderCompanyName
field.
Ghosts can subsequently log into BuildingConnected, claim their account, and configure their company profile. When this happens, the value provided in placeholderCompanyName
is replaced with the new, correct company name and the user’s companyId is updated on the invite object.
Some customers have duplicate companies. Autodesk’s support staff sometimes merge these companies, which will result in existing invites being updated so the correct bidder company information is updated on all existing invites. This could result in two invites being consolidated into a single invite on an existing bid package.
Bid packages only support 500 total invites.
Project Templates
While any project, bid package, bid form, or bidder list can be duplicated, the BuildingConnected template functionality makes it easy to centralize information for reduplication as needed.
A project template is a project with its isTemplate
flag set to true
. From the template you can clone selected content and avoid manually reentering information for a new project. There are two ways to use template information in a project:
- Clone a project template entirely.
- Import only bid packages and bid forms from a project template.
A project template cannot be published but can be cloned into a new project. BuildingConnected supports two types of template content:
- Bidder list content corresponding to the list of invites on a bid package
- Bid form content, including bid packages, project bid forms, and scope-specific bid forms
Bid Forms
There can be only one project bid form per project, and only one scope-specific bid form per bid package. When editing bid forms using the API, the workflow described below provides a failsafe way to add or edit bid forms.
Note that this example is provided for project bid forms but the same workflow applies to scope-specific bid forms.
- Use GET project-bid-forms with the
projectId
query parameter to find a bid form for the project. - If no project bid form is found, create one using POST project-bid-forms and include all required line-items.
- If the project bid form exists for the project, get additional bid form line items using GET project-bid-forms/{formId}/line-items until all line-items have been read.
- Compare against the line items to update:
- For line items to add, use POST project-bid-forms/{formId}/line-items:batch-create.
- For line items to update, use PATCH project-bid-forms/{formId}/line-items:batch-patch.
- For line items to remove, use POST project-bid-forms/{formId}/line-items:batch-delete.
The Opportunity Data Model
BC Pro invites correspond one-to-one with Bid Board opportunities. When a BC Pro bid package is published and invites are created, Bid Board creates a corresponding opportunity for the invited party.
Opportunities are not nested in the same way as projects. The following graphic articulates the Bid Board representation of separate invites from two bid packages from the same GC on the same project to the same subcontractor. The opportunities are separate on Bid Board.

Bid Board Pro has a feature called grouping which enables users to combine opportunities into a single tracking unit called a “group of opportunities”. This functionality makes it easy to track many invites from multiple GCs on a single project. In the following graphic, a subcontractor can receive an invitation to bid on two separate electrical packages from two different GCs competing for the same project. Each invite creates an independent opportunity but the subcontractor can link them by creating a separate opportunity that serves as a group parent.

Each opportunity has its own ID, including the parent opportunity. In the following graphic, all three original opportunities that are nested under the group parent “Salesforce Tower” have the following properties:
isParent=false
to indicate that they aren’t parentsparentId=
opportunityId of Salesforce Tower
Meanwhile, group parent “Salesforce Tower” is differentiated by the following properties:
isParent=true
to indicate that it’s a parentgroupChildren
(an array of the IDs for the three nested opportunities)

Domestic Versus Foreign Opportunities
In BuildingConnected, we primarily categorize opportunities into two types: “domestic opportunities” and “foreign opportunities”. The domestic opportunities refer to those generated by BuildingConnected Pro, while the foreign opportunities are created by Bid Board users. These categories are identified through the source
value, which signifies the origin of an opportunity.
Domestic Opportunities
Domestic opportunities represent a bidder’s version of an invitation (see GET invites/:id for more information). They share partial ownership with the project owner, also referred to as the “client”. Neither the project host nor the bidder can delete domestic opportunities. If deletion is necessary, project hosts can contact Autodesk support for assistance in removing an invite/opportunity pair. Bid Board offers an augmentation layer, allowing bidders to modify field values on domestic opportunities. However, these changes only affect the opportunity itself and do not change data on the corresponding invitation, bid package, or project. Any discrepancies in field values are clarified with a disclaimer in the application.
Foreign Opportunities
Foreign opportunities are solely owned by bidders. They can be established through seven distinct methods. Each of these methods has an associated source
field value. The table below outlines the different methods along with their corresponding values, and provides tutorials for further information.
Method | Source Field Value | Tutorials |
---|---|---|
Email forwarding | EMAIL |
How to forward invites from your inbox to BuildingConnected |
Manually adding new bids | MANUAL |
How to manually add new bids to your Bid Board |
Importing bids history | IMPORTED |
How to import your bids history |
Client suggestions | DISCOVERED |
How to find additional bid opportunities on competitive projects |
Duplicating bids | DUPLICATE_x where x is BUILDINGCONNECTED , EMAIL or MANUAL . |
How subcontractors can create copies of bids |
Grouping | MANUAL |
How to create opportunity groups |
Using the API | API |
Creating and Managing Opportunities |
Bids
A bid is an immutable collection of line items, each with its own bid amount. Individual line items are broken out and correspond to both the project’s bid form and the bid package’s scope-specific bid form. Each bid has summary information to represent the bid total. Bidders will typically include PDF attachments of their formal business proposal in their bids.
In lieu of edits, bids have an ascending revision value, each number corresponding to a distinct bid submitted by a bidder over the course of a project. If there are two bids from a bidder, the bid with a revision
number of 2
will be the most recent bid.
Bid package objects, invite objects, and bid objects contain all of the relevant IDs required for mapping the cascading set of relationships between them:
- Bid packages:
projectId
- Invites:
projectId
andbidPackageId
- Bids:
projectId
,bidPackageId
, andinviteId
Use these unique IDs to map objects accurately.
A bid submitted by a bidder directly through BuildingConnected will have a creatorType
value of BIDDER
. Any bid submitted by a member of the project (i.e. the team who sent the invite) on behalf of a bidder will have a creatorType
value of HOST
. The HOST
value is also applied to all bids created with the BuildingConnected API.
All bids on a given BuildingConnected bid package can be viewed by the bidder, even if the creatorType
is HOST
. Say a host submits a bid on behalf of a bidder before that same bidder had logged into BuildingConnected to view their invitation, that bidder could still subsequently log in and view the bid submitted on their behalf.
Note that the current version of the BuildingConnected API does not support adding plugs to bids. Plugs modify a bid line item’s apparent value and are used by the BuildingConnected application to perform bid levelling. However, you can create bids in BuildingConnected through the API and then level the bid in the BuildingConnected UI. The plugs created are exposed in the API’s GET endpoints.
Managing BC Files Over API
The BuildingConnected API provides file management using Autodesk Docs. When a BC project is linked to an ACC project, BuildingConnected swaps to use Autodesk Docs as the primary file provider for projects and bid packages.
To learn more about file management in Autodesk Construction Cloud, use the BIM 360 API reference for Document Management.
BuildingConnected leverages Docs by choosing a specific folder to be shared with bidders. This is done in two places:
- On the project level (so that all bidders on the project see all content under this folder).
- At the bid package level (so only bidders invited specifically to that package see a given folder’s contents).
You can find the IDs of these folders in the GET projects and GET bid-packages endpoint responses in the field currentAccDocsFolderId
.
Note that BuildingConnnected will keep track of this folder if it is moved around, and its sharing functionality overrides any permissions set on the folder in Docs (disabling sharing on Docs will not stop BuildingConnected from sharing folder content with bidders).
BuildingConnected Webhooks
Many BuildingConnected endpoints trigger a webhook event when, for example, a bid revision is created or an opportunity comment is updated.
You can use the Webhooks API to create a webhook that will notify your BuildingConnected application when a particular event is triggered in a specified account or project, so your application can respond appropriately. The Webhooks service sends the notification to a callback URL that you provided when creating the webhook.
For a full list of the available events for which you can configure a webhook, see the BuildingConnected Events page.
For more information, see the Webhooks API.
Limitations
The BuildingConnected API is intended to expose all key data points that users normally have access to within a BuildingConnected product, with several important limitations:
- No ability to search the Builders Network (this is always exclusive to the BuildingConnected application)
- No file management except through Docs (see Managing BC files over API)
- No user management (not planned to change)
- No ability to search for bidders
- No ability to create new BuildingConnected companies, as they can only be created in the BuildingConnected UI.
- Bids cannot be submitted on opportunities
- Plugs cannot be added to bids
- No ability to manage opportunity files