We are excited to announce the general availability of BuildingConnected (BC) write API! The BC write API is a large set with the total of 47 endpoints. With the read endpoints from the first release, the API covers most of BC entities and operations. It allows you to build more comprehensive integration applications. The companion API TradeTapp also released first set this time. So you will find they are now under the APS category: BuildingConnected & TradeTapp APIs. Another blog talks about TradeTapp API.
Below is the list of new capabilities added in this release:
- create/update/delete projects, project costs, and project members.
- Create/update/delete bidpackages, create bid, and create/delete bid attachments.
- Create project bid forms and scope specific bid forms, and create/update/delete form items
- Create/update/delete opportunities.
- Get Certification
- Get Office
- Create/update/read project & opportunity pair.
API Technical Notes
The new APIs are in same version (v2) as previous read API:
/construction/buildingconnected/v2.
For those who are just getting started with Building Connected API, all APIs currently supports 3-legged authentication only. (i.e., the API access right is the same as the user in the UI.) Different levels of subscription affect the API access level:
- Users, Offices, Certificates --- no subscription required
- Opportunities --- you will need Bid Board Pro subscription
- All others --- you will need BuildingConnected Pro subscription
- Opportunity-Project pair --- this is special. It requires both Bid Board Pro and Building Connected Pro
The new APIs include quite a few endpoints for batch operation. The payload schema of each verb is slightly different:
- batch-create is an array of new entity attributes.
- batch-delete is an array of existing entity id.
- batch-patch is a dictionary with key (entity id) and value (its attributes to update).
You can create new a project with/without template. You could also copy bid package data during the project creation. Creating a project with opportunity will generate an opportunity-project pair. The project can be linked with ACC project as long as this user is member to the ACC project. The project files could also be shared within ACC folder if this user has permission to upload file to the ACC folder. The project can be also unlinked to ACC project.
Creating a new bid with same invite will generate a new bid version. Steps to create a bid attachment is similar to when uploading file to Autodesk Platform Services (APS) (OSS and Autodesk Construction Cloud folder: i.e., get S3 signed url, upload file stream, and finally create bid (version) with the attachment to complete the uploading. Changing attachments or items of forms means you are creating a new revision of bid.
Create opportunities API is analogousto the steps to create an opportunity manually in bid board; when created using API, the source will be "API", while creating through the UI, "Manual". If an opportunity is from invite of bid package, the source type will be "BuildingConnected" which is categorized "domestic opportunity" v.s. all other types which are categorized "foreign opportunity". When creating opportunities from bid packages through the API, it will be processed by BuildingConnected when a bid package is published. This API release does not support publishing bid packages.
The group parent opportunities must be created directly (foreign) and cannot be converted to or from any other type of opportunity. An opportunity cannot be both a parent and a child.
Opportunity-project pair APIs provides the way to get all pairs or a single pair. However, the API to create a pair is only to relink a project from a child opportunity to a group parent. The modifying API is only to transfer the linked project of child opportunity to its group opportunity and remove the existing pair of group opportunity .
section+description+type uniquely identifies an item of project bid forms. section+description +code+type uniquely identifies an item of scope-specific bid forms. When creating/modifying the items, ensure these fields can identify the item you want to manipulate.
Certificate types and agencies are both for BC and TradeTapp (in enterprise business certifications). The new API only provides the endpoint to get available types or agencies. They are managed internally. To create new one, you need to follow this form to register. The goal is to provide a way for general contracts of sub contracts to let us know about an agency or types that we don't have on file.
Rate limit of most write API is 60 rpm. Batch endpoints are 10 rpm. If the application combines read and write endpoint, the global limit would be 1000 rpm, but the write endpoints will only have a limited contribution towards this limit since their rate limit is 60 rpm or 10 rpm.
Documentation
The Field Guide is updated with the new abilities, domestic v.s. foreign opportunities and other new notes.
A few more tutorials are provided. They demonstrate some basic workflows with the new APIs.
- Manage Projects, Bid Packages, Bid Forms
- Create and Manage Opportunities
- Manage Opportunity Projects and Pairs
- Create Bids and Attachments
- Manage Bidder and Proposal Files Using Docs
In addition, one more tutorial describes how to use the test environments and developer environment provided by BuildingConnected for non-customer partners. It also includes the tutorial working with 3-legged token for those customers who are new to authentication of APS.
To help you test, we added the new APIs to the Postman collection. Two use case samples may inspire you with the ideas how API could be used.
- Postman Collection
- aps-bidleveling-inspection-by-takeoff: inspect the quantities of scope specific form items by the quantities from the corresponding model takoff of Autodesk Construction Cloud
- aps-takeoff-to-bidform-items: create bid form items of BuildingConnected by takeoff of Autodesk Construction Cloud
If you have any question, feel free to contact us through our APS support channel, or reach out to senior product manager Cory Kintz at https://calendly.com/autodesk-platform-services .