Export a Project to Your Estimating Tool
This tutorial demonstrates how to retrieve a complete BuildingConnected project for export to an estimating tool. The steps include searching for a relevant project, using bid forms to list scope questions, retrieving bid packages, invites, and bids, and mapping objects.
For more details about the BuildingConnected API, see the BuildingConnected Field Guide.
Before You Begin
- Register an app (select either the Traditional Web App or the Desktop, Mobile, Single-Page App application type).
- Make sure to select the BuildingConnected API via the API Access dropdown after registering your app.
- Acquire a 3-legged OAuth token with
data:readscope.
Step 1: Identify and Retrieve the Relevant Project
You can find the right project by calling GET projects and including the searchText query parameter to search by the project’s name or number. The text must be URL encoded; for example, Chase Center Arena would be written Chase%20Center%20Arena. Examine the returned id field for the project ID.
Request
curl 'https://developer.api.autodesk.com/construction/buildingconnected/v2/projects \
?filter[searchText]=Chase%20Center%20Arena' \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT'
Response
{
"id": "59d2bd7440b36a0da258f24d",
"name": "Chase Center Arena",
"number": "12345",
"client": "Name of client",
"description": "Short description of the project",
"notes": "Any notes about the project",
"value": 1000000,
"projectSize": 2000,
"awarded": "WON",
"isBiddingSealed": false,
"state": "PUBLISHED",
"isNdaRequired": false,
"isPublic": false,
"createdAt": "2014-09-22T16:27:37.437Z",
"updatedAt": "2014-09-23T16:28:37.437Z",
"publishedAt": "2014-09-22T21:34:44.511Z",
"bidsDueAt": "2014-10-03T19:00:00.000Z",
"endsAt": "2015-03-31T07:00:00.000Z",
"rfisDueAt": "2014-09-25T19:00:00.000Z",
"startsAt": "2014-11-03T08:00:00.000Z",
"dueAt": "2014-09-03T08:00:00.000Z",
"location": {
"country": "US",
"state": "CA",
"streetName": "California St.",
"streetNumber": "600",
"suite": "6th Floor",
"city": "San Francisco",
"zip": "94108",
"complete": "600 California St., 6th Floor, San Francisco, CA 94108",
"coords": {
"lat": -122.4069826,
"lng": 37.7929546
}
},
"isTemplate": false,
"accountManager": "Name of account manager",
"fee": "15.55",
"marketSector": "Sports Stadium Construction",
"creatorId": "5a1dc3cf5b54e06ca307d7af",
"defaultCurrency": "USD",
"officeId": "5fcdcd0b3db0876c6692d5bb",
"architect": "Browning Day Mullins Dierdorf Architects",
"isForBudgeting": false,
"currentAccLinkedProjectId": "00f1b796-293a-4c1e-9474-f09711011426",
"currentAccLinkedHubId": "28b0d8b3-4730-4f4f-8bad-4a2a5d75ed26",
"relevantCertificates": [
{
"id": "5d1dcd5a4a7196ca208ed623",
"agencyId": "600dcf56ffa3d03ac170f967",
"certificationTypeId": "610d4fe28a3719ec41c02596"
}
]
}
Step 2: Use Bid Forms to List Scope Questions (Optional)
Bid forms represent the questions that bidders are asked to complete when submitted bids. You can recreate line items in your estimating tool by retrieving the line items from the two types of bid forms:
- Project bid forms (using GET project-bid-forms)
- Scope specific (bid package) bid forms (using GET scope-specific-bid-forms)
Note that project bid forms don’t have cost components.
To get scope specific bid forms, call GET scope-specific-bid-forms and use the query parameters relevant to your needs. You can do either of the following:
- Query for all bid forms on a given project using
filter[projectId]with the project ID that was returned in Step 1. - Query one bid form at a time using
filter[bidPackageId]. To get the bid package ID, call GET bid-packages and includefilter[projectId]with the project ID that was returned in Step 1.
Request
curl 'https://developer.api.autodesk.com/construction/buildingconnected/v2/scope-specific-bid-forms?filter[projectId]=59d2bd7440b36a0da258f24d' \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT'
Response
{
"pagination": {
"limit": 100,
"cursorState": "eyJsaW1pdCI6MjUsIm9mZnNldCI6MjV9",
"nextUrl": ""
},
"results": [
{
"id": "5af0892518d349f6d59e1bbb",
"projectId": "59d2bd7440b36a0da258f24d",
"bidPackageId": "590dd127b359f408f190b5a7",
"createdBy": "5542856b27aae240452fce62",
"updatedBy": "5542856b27aae240452fce62",
"createdAt": "2021-08-19T23:07:16.083Z",
"updatedAt": "2021-08-20T23:07:16.083Z",
"isTemplate": false,
"lineItems": {
"pagination": {
"limit": 100,
"cursorState": "eyJsaW1pdCI6MjUsIm9mZnNldCI6MjV9",
"nextUrl": ""
},
"results": [
{
"id": "53811754d3a604966df72247",
"type": "COST_BREAKDOWN",
"description": "Duct Insulation",
"section": "Furnish & Install",
"isRequired": true,
"unit": "HOURS",
"code": "D2",
"quantity": 1000,
"isQuantityFixed": true
}
]
}
}
]
}
Step 3: Retrieve Bid Packages
To get the project’s bid packages, call GET bid-packages and include the query parameter filter[projectId] using the project ID that was returned in Step 1.
Request
curl 'https://developer.api.autodesk.com/construction/buildingconnected/v2/bid-packages?filter[projectId]=59d2bd7440b36a0da258f24d' \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT'
Response
{
"pagination": {
"limit": 100,
"offset": 0
},
"results": [
{
"id": "590dd127b359f408f190b5a7",
"projectId": "59d2bd7440b36a0da258f24d",
"name": "Windows",
"number": "123",
"keywords": [
"Glass"
],
"estimatedCost": 100000,
"state": "PUBLISHED",
"createdAt": "2014-09-25T19:00:00.000Z",
"updatedAt": "2014-09-26T16:00:00.000Z",
"publishedAt": "2014-09-25T19:00:00.000Z",
"bidsDueAt": "2014-09-25T19:00:00.000Z",
"endsAt": "2014-09-25T19:00:00.000Z",
"rfisDueAt": "2014-09-25T19:00:00.000Z",
"startsAt": "2014-09-25T19:00:00.000Z",
"jobWalkAt": "2014-09-25T19:00:00.000Z"
}
]
}
Step 4: Retrieve Invites
To get the project’s invites, call GET invites and include the query parameter filter[projectId] using the project ID that was returned in Step 1.
Request
curl 'https://developer.api.autodesk.com/construction/buildingconnected/v2/invites?filter[projectId]=59d2bd7440b36a0da258f24d' \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT'
Response
{
"pagination": {
"limit": 100,
"cursorState": "eyJsaW1pdCI6MjUsIm9mZnNldCI6MjV9",
"nextUrl": ""
},
"results": [
{
"id": "590dd527b359f408f191b5b6",
"projectId": "59d2bd7440b36a0da258f24d",
"bidPackageId": "590dd127b359f408f190b5a7",
"bidderOfficeId": "57d2bd7450b37a0c52585d2a",
"bidderCompany": {
"id": "51bea397f5846f95994b1da7",
"name": "Gr8 Builders",
"businessType": [
"Subcontractor"
],
"website": "http://www.example.com",
"laborType": [
"Union"
],
"enterpriseType": [
"Disadvantaged Business Enterprise (DBE)"
],
"companyTags": [
"example_tag"
],
"certificates": [
{
"id": "627074db25c97830ad3ea8c8",
"type": {
"id": "59d2bd7440b36a0da258f24d",
"name": "Disadvantaged Business Enterprise (DBE)"
},
"agency": {
"id": "611d794f7f063800a7274d46",
"name": "United States Department of Transportation",
"website": "https://www.transportation.gov/civil-rights/disadvantaged-business-enterprise"
},
"number": "12345",
"expiresAt": "2014-10-03T19:00:00.000Z",
"fileName": "certificate.pdf"
}
]
},
"state": "UNDECIDED",
"createdAt": "2014-09-25T20:00:00.000Z",
"updatedAt": "2014-09-25T21:00:00.000Z",
"invitedAt": "2014-09-25T20:30:00.000Z",
"invitees": [
{
"id": "5cfe43c079b25e7dcafc104d",
"userId": "5bff41c079b25e7ccebc202e",
"firstName": "First",
"lastName": "Last",
"companyId": "51bea397f5846f95994b1da7",
"phoneNumber": "555-555-5555",
"title": "Estimator",
"email": "someone@gmail.com",
"inviterType": "HOST",
"state": "INVITED"
}
]
}
]
}
Step 5: Retrieve Bids
To get the project’s bids, call GET bids and include the query parameter filter[projectId] using the project ID that was returned in Step 1.
Each bid contains summary information expressing total bid value. The leveledTotal field returns the net value of the bid including any plugs made via Bid Leveling in BC Pro.
Note that the description of each line item (e.g. Duct Insulation) is unique within its type (e.g. COST_BREAKDOWN).
Request
curl 'https://developer.api.autodesk.com/construction/buildingconnected/v2/bids \
?filter[projectId]=59d2bd7440b36a0da258f24d' \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT'
Response
{
"pagination": {
"limit": 100,
"cursorState": "eyJsaW1pdCI6MjUsIm9mZnNldCI6MjV9",
"nextUrl": ""
},
"results": [
{
"id": "611ee35b3935e500a8b18c8a",
"projectId": "59d2bd7440b36a0da258f24d",
"bidPackageId": "590dd127b359f408f190b5a7",
"inviteId": "590dd527b359f408f191b5b6",
"bidderCompanyId": "51bea397f5846f95994b1da7",
"creatorType": "BIDDER",
"notes": "Notes about bid",
"total": 5000,
"leveledTotal": 10000,
"createdAt": "2021-08-19T23:07:16.083Z",
"updatedAt": "2021-08-19T23:07:16.083Z",
"submittedAt": "2021-08-19T23:08:32.075Z",
"attachments": [
"60cea42b3934f500a8b29c7b"
],
"revision": 0,
"createdBy": "5d8104b87e392d56e1e4b4ca",
"submittedBy": "5d8104b87e392d56e1e4b4ca",
"lineItems": {
"pagination": {
"limit": 100,
"cursorState": "eyJsaW1pdCI6MjUsIm9mZnNldCI6MjV9",
"nextUrl": ""
},
"results": [
{
"id": "53811754d3a604966df72247",
"type": "COST_BREAKDOWN",
"description": "Duct Insulation",
"section": "Furnish & Install",
"isRequired": true,
"isCustom": false,
"unit": "HOURS",
"code": "D2",
"quantity": 10,
"isQuantityFixed": true,
"unitCost": 500,
"value": 10000
}
]
},
"plugs": {
"pagination": {
"limit": 100,
"cursorState": "eyJsaW1pdCI6MjUsIm9mZnNldCI6MjV9",
"nextUrl": ""
},
"results": [
{
"id": "5f8104b87e392d56e1e4b4ad",
"quantity": 20,
"unitCost": 500,
"value": 10000,
"createdBy": "",
"updatedBy": "",
"createdAt": "",
"updatedAt": "",
"lineItemFingerprint": {
"type": "COST_BREAKDOWN",
"description": "duct insulation",
"section": "furnish & install",
"unit": "HOURS",
"code": "d2"
}
}
]
}
}
]
}
Step 6: Map Objects
Each project has a subset of bid packages; each bid package has a subset of invites; each invite has a subset of bids. Bids have all relevant ids: projectId, bidPackageId, and inviteId; invites have a bidPackageId and projectId field; and bid packages have a projectId field. Use these unique IDs to accurately map objects correctly according to the following wireframe.
