Getting Started with the BuildingConnected API
This tutorial demonstrates how to use the Postman API platform to make your first successful API request, and how to use the developer environments provided by BuildingConnected for non-customer partners.
Before You Begin
- Verify that you have a BuildingConnected account.
- Verify that you have an appropriate subscription for the BuildingConnected API group you want to use:
- Users, Certification, Offices (GET endpoints) — no subscription required
- Opportunities — Bid Board Pro
- Opportunity Project Pairs — both Bid Board Pro and BuildingConnected Pro
- All others — BuildingConnected Pro
- Ensure that your BuildingConnected user is linked with an Autodesk ID. See How to connect your Autodesk ID to BuildingConnected.
- Register an app, and select the BuildingConnected API. For more information, see the Create an App tutorial.
- Acquire a 3-legged OAuth token with
data:create,data:read, anddata:writescopes.
Use Postman to Make Your First API Call
You can use Autodesk’s BuildingConnected Postman collection to work with the BuildingConnected API:
- Download the Postman Collection for BuildingConnected API.
- Go to the Postman website and create a free account. You can use the Postman webapp, or download a local client app.
- In your Postman workspace, click the Import button to upload the BuildingConnected collection:
- In your new collection, select the Variables tab, enter your values for
clientIdandclientSecret, and save:
- Select the Authorization tab and click the Get New Access Token button at the very bottom of the tab content. You should be prompted to sign in with your Autodesk ID.
- Once you are signed in, click Use Token.
- Open any API call from the left bar
- If accessing the test developer environment (if you don’t currently have a BuildingConnected paid subscription), go to Pre-request Script and add
pm.request.headers.add("x-bc-mode: test")and save:
You may continue using this BuildingConnected API collection. We will keep the Git Repo up to date as we add new endpoints.
Non-Customer Developer Environments
If you are a developer partner but not a BuildingConnected customer, you can use one of the developer environments to test API calls.
There are two relevant non-production environments for developers:
- test — An environment for developers who expect to use only GET endpoints. See Test Environment.
- alpha — An environment for partners who want to use GET, POST, PATCH, and DELETE endpoints. See Alpha Environment.
Test Environment
The test environment provides predefined data to reflect what BuildingConnected customers would typically provide in the application.
Note that this environment allows you to use only read (GET) endpoints. To test the write (POST, PATCH and DELETE) endpoints, see the Alpha Environment section.
The test environment supports all query parameters that are described in the API reference for the GET endpoints.
The following example demonstrates the use of the GET opportunities endpoint Include the header x-bc-mode: test with your request.
Request
curl -X GET 'https://developer.api.autodesk.com/construction/buildingconnected/v2/opportunities' \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT'
-H `x-bc-mode: test`
Response
{
"results": [
{
"id": "646e3f2cf03239f2cd095b51",
"name": "Epoxy Flooring",
"number": "7112",
"client": {
"company": {
"id": "644a7f48f03239042f7d60fd",
"name": "Zemlak-Braun"
},
"lead": {
"id": "644a7f6af0323900a4d19287",
"email": "atidcombe1@java.com",
"firstName": "Alfie",
"lastName": "Gingle",
"phoneNumber": "478-976-9999"
},
"office": {
"id": "644a7f5af0323900449b6415",
"location": {
"country": "USA",
"state": "DC",
"streetName": "Schurz",
"streetNumber": "98",
"suite": "15",
"city": "Bridgeport",
"zip": "77085",
"complete": "220 Jackson, Bridgeport, CT 06673 USA",
"coords": {
"lat": 29.6218,
"lng": -73.3637
}
},
"name": "Texas"
}
},
"competitors": [
{
"bidAmount": 189802,
"companyId": "644a7f47f03239020137c02d",
"isWinner": false,
"name": "Tremblay, Hauck and Koch"
},
{
"bidAmount": 79900,
"companyId": "644a7f47f0323900a4d19282",
"isWinner": true,
"name": "Lakin-Grant"
}
],
"customTags": [
"tag2",
"tag3"
],
"createdAt": "2022-10-06T15:18:21.000Z",
"updatedAt": "2023-12-07T15:18:23.000Z",
"defaultCurrency": "USD",
"source": "BUILDINGCONNECTED",
"isNdaRequired": true,
"isPublic": false,
"outcome": {
"state": "WON",
"otherReason": null,
"updatedAt": "2024-02-28T15:18:51.000Z",
"updatedBy": "644a7e29f032390779646a9e"
},
"requestType": "PROPOSAL",
"submissionState": "SUBMITTED",
"workflowBucket": "UNDECIDED_ACTIVE_PARENT",
"isParent": true,
"parentId": null,
"groupChildren": [
"646e3f32f03239f2cd095b53",
"646e3f32f03239f2cd095b55"
],
"bid": {
"id": "646e3f30f03239f2cd095b52",
"submittedAt": "2022-05-02T03:01:00.000Z",
"total": 1837,
"revision": 0,
"type": "SEND"
},
"members": [
{
"viewedAt": "2022-04-25T20:06:50.000Z",
"userId": "644a7e27f0323900449b6412",
"type": "ASSIGNEE"
},
{
"viewedAt": "2021-01-23T20:20:16.000Z",
"userId": "644a7e27f03239056f6bb624",
"type": "ASSIGNEE"
}
],
"dueAt": "2024-01-30T15:19:11.000Z",
"jobWalkAt": "2022-02-04T15:18:22.000Z",
"rfisDueAt": "2022-10-23T15:18:44.000Z",
"expectedStartAt": "2022-09-07T15:18:57.000Z",
"expectedFinishAt": "2023-10-09T15:19:43.000Z",
"invitedAt": "2022-01-26T15:18:57.000Z",
"tradeName": "Laborer",
"projectSize": 1740,
"projectInformation": "<div> Info2 </div>",
"location": {
"country": "USA",
"state": "CT",
"streetName": "Stang",
"streetNumber": "960",
"suite": "6",
"city": "Bridgeport",
"zip": "06606",
"complete": "960 Stang, Bridgeport, CT 06606 USA",
"coords": {
"lat": 41.2091,
"lng": -73.2086
}
},
"tradeSpecificInstructions": "Instruction",
"architect": "Ingrim Clarkson",
"engineer": "Derrik McDavitt",
"propertyOwner": "Leslie Maddox",
"propertyTenant": "Noland Leynton",
"declineReasons": [
"OTHER",
"TOO_BUSY"
],
"additionalInfo": "Information",
"priority": "LOW",
"marketSector": "HIGHWAY_STREET",
"rom": 96,
"winProbability": 55,
"followUpAt": "2021-06-08T17:56:58.000Z",
"contractStartAt": "2021-01-11T12:53:49.000Z",
"contractDuration": 64,
"averageCrewSize": 84,
"estimatingHours": 393,
"feePercentage": 96,
"profitMargin": 4,
"finalValue": 565018,
"isArchived": false,
"owningOfficeId": "644a7e17f03239056f6bb623",
"isSealedBidding": false,
"clientValues": {
"name": "Epoxy Flooring",
"dueAt": "2024-01-30T15:19:11.000Z",
"jobWalkAt": "2022-02-04T15:18:22.000Z",
"rfisDueAt": "2022-10-23T15:18:44.000Z",
"expectedStartAt": "2022-09-07T15:18:57.000Z",
"expectedFinishAt": "2023-10-09T15:19:43.000Z",
"tradeName": "Laborer",
"projectSize": 1740,
"projectInformation": "<div> Info2 </div>",
"location": {
"country": "USA",
"state": "CT",
"streetName": "Stang",
"streetNumber": "960",
"suite": "6",
"city": "Bridgeport",
"zip": "06606",
"complete": "960 Stang, Bridgeport, CT 06606 USA",
"coords": {
"lat": 41.2091,
"lng": -73.2086
}
"tradeSpecificInstructions": "Instruction",
"architect": "Ingrim Clarkson"
}
}
],
"pagination": {
"limit": 1,
"cursorState": "646e3f2cf03239f2cd095b51",
"nextUrl": "/construction/buildingconnected/v2/opportunities?limit=1&cursorState=646e3f2cf03239f2cd095b51"
}
}
Alpha Environment
To access the alpha environment and use all available BuildingConnected API endpoints, sign up for a partner account in the ACC partner portal. Note that there are additional benefits to becoming an Autodesk Construction Cloud integration partner beyond just integration support.
To make an API call in the alpha environment, include the header x-ads-target-server: alpha.
