Create Bids and Attachments
This tutorial demonstrates how to log proposals (bids) from your bidders in BuildingConnected. The steps include creating a bid attachment, uploading the bid attachment, and creating a bid with the attachment, and creating a bid revision with line items.
Logging proposals is useful when bidders decline to submit bids through BuildingConnected and instead provide bid details on paper, over the phone, or by email, or if the bid information is tracked in a separate estimating or accounting solution.
A bid is a collection of line item responses and attachments that are submitted against a given bid form on a given bid package. The line items on a bid are the bidder’s responses to all of the line items on both the bid package’s scope specific bid form and the project’s bid form.
Note that when you create a bid on a given bid package on behalf of a given user, it is unique for that bid package and user. You cannot directly modify or delete the bid; instead, you create a new revision of the bid that replaces the existing one and increments the value of the new bid’s revision
field by one. In BuildingConnected, the highest value of revision
indicates the active bid.
To familiarize yourself with making BuildingConnected API requests, see Getting Started with the BuildingConnected API.
To learn about managing a project, see Manage Projects, Bid Packages, Bid Forms, and Bidders.
For more information about the BuildingConnected data model, see the BuildingConnected API Field Guide.
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:read
anddata:write
scopes.
Step 1. Create a Bid Attachment
Before you add an attachment to a bid, you must first create and upload the attachment to AWS. The attachments can be reused in bid revisions.
To create the attachment, call POST attachments with the name
of the file to attach along with its size
in bytes.
Request
curl -X POST -v 'https://developer.api.autodesk.com/construction/buildingconnected/v2/bids/attachments' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT' \
-d '{
"name": "doc1.pdf",
"size": 245231
}'
Response
{
"id": "64c7d2549923da545191cd14",
"name": "doc1.pdf",
"size": 245231,
"method": "POST",
"url": "https://s3.amazonaws.com/files.buildingconnected.com/",
"headers": {},
"formData": {
"policy": "dGhlX2VuY29kZWRfcG9saWN5X2RhdGE=",
"signature": "c2lnbmF0dXJlIGRhdGE=",
"key": "/attachments/58ed681b195f9a0b00708c4b/6ce2b88f-95a8-4964-9030-f72cc206d786",
"Content-Type": "application/pdf",
"AWSAccessKeyId": "ACCESS_KEY_ID",
"acl": "private",
"Content-Disposition": "attachment;filename*=UTF-8''doc1.pdf;filename=\"doc1.pdf\"",
"success_action_status": 201
},
"expiresAt": "2023-07-31T16:25:08.510Z"
}
Find and note the values of url
and formData
to use in the next step.
Step 2. Upload the Bid Attachment
Upload the attachment using the URL and signed formData
information from the previous response.
Request
curl -X POST -v 'https://s3.amazonaws.com/files.buildingconnected.com/' \
--form 'policy="dGhlX2VuY29kZWRfcG9saWN5X2RhdGE="' \
--form 'signature="c2lnbmF0dXJlIGRhdGE="' \
--form 'Content-Type="application/pdf"' \
--form 'AWSAccessKeyId="ACCESS_KEY_ID"' \
--form 'acl="private"' \
--form 'Content-Disposition="attachment;filename*=UTF-8'\'''\''doc1.pdf;filename=\"doc1.pdf\""' \
--form 'success_action_status="201"' \
--form 'key="/attachments/58ed681b195f9a0b00708c4b/6ce2b88f-95a8-4964-9030-f72cc206d786"' \
--form 'file=@"C:\path\to\doc1.pdf"'
Response
<?xml version="1.0" encoding="UTF-8"?>
<PostResponse>
<Location>https://s3.amazonaws.com/files.buildingconnected.com/%2Fattachments%2F58ed681b195f9a0b00708c4b%2F6ce2b88f-95a8-4964-9030-f72cc206d786</Location>
<Bucket>files.buildingconnected.com</Bucket>
<Key>/attachments/58ed681b195f9a0b00708c4b/6ce2b88f-95a8-4964-9030-f72cc206d786</Key>
<ETag>"f9922cba864b4d7b759edd516f6f9f14"</ETag>
</PostResponse>
Step 3: Create a Bid with the Attachment
To create a bid, Call POST bids and provide the inviteId
of the bidder. You can add one or more uploaded attachments to the new bid by including the attachments
array containing the desired attachment IDs in the request.
Bids must answer questions that are set out in a project’s bid forms.
Some bids must include line items that are mapped to the corresponding bid form’s line items, but most projects and bid packages have no bid form questions and are instead “lump sum” only, as in this example. Include the total
field with the lump sum value of the bid in the request.
Request
curl -X POST -v 'https://developer.api.autodesk.com/construction/buildingconnected/v2/bids' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT' \
-d '{
"inviteId": "64bfd32a1186d55c2f61c1f9",
"total": 3000,
"attachments": [ "64c7d2549923da545191cd14" ]
}'
Response
{
"id": "65cbca64d989f800266430ad",
"projectId": "64c2873f56831b0045b09ad7",
"bidPackageId": "64c2873f56831b0045b09b2f",
"inviteId": "64bfd32a1186d55c2f61c1f9",
"bidderCompanyId": "543792bc96ab4906000e45e9",
"creatorType": "HOST",
"notes": null,
"total": 3000,
"leveledTotal": 3000,
"createdAt": "2024-02-13T20:00:36.267Z",
"updatedAt": "2024-02-13T20:00:36.274Z",
"submittedAt": "2024-02-13T20:00:36.267Z",
"attachments": [ "64c7d2549923da545191cd14" ],
"revision": 0,
"createdBy": "62e2d09e5f849100753fb397",
"submittedBy": "62e2d09e5f849100753fb397",
"lineItems": {
"results": [
{
"id": null,
"type": "COST_BREAKDOWN",
"description": "Concrete",
"section": null,
"isRequired": true,
"isCustom": false,
"unit": "TOTAL_COST_ONLY",
"code": null,
"quantity": null,
"isQuantityFixed": false,
"unitCost": null,
"value": 3000
}
],
"pagination": {
"limit": 100,
"cursorState": null
}
},
"plugs": {
"results": [],
"pagination": {
"limit": 100,
"cursorState": null
}
}
}
Step 4: Create a Bid Revision with Line Items
Bid line items are mapped to bid form line items using a combination of a bid line item’s description
and section
, not the line item’s unique ID. These two values are therefore required if there is a bid form with required line items.
This step covers two possible scenarios:
- Option A: The bid package has a project bid form but no scope specific bid form.
- Option B: The bid package has both a project bid form and a scope specific bid form.
Note that to update or add attachments to the bid, these revisions include the attachments
array in the request.
Option 4A: Bid on a Project Bid Form Only
To create a bid on a package that has a project bid form but no scope specific bid form, provide the lump sum in the total
field.
Request
curl -X POST -v 'https://developer.api.autodesk.com/construction/buildingconnected/v2/bids' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT' \
-d '{
"inviteId": "64bfd32a1186d55c2f61c1f9",
"attachments": [ "64c7d2549923da545191cd14" ],
"total": 315000,
"lineItems": [
{
"type": "ACKNOWLEDGMENT",
"description": "Do you acknowledge this?",
"unit": "YES_NO",
"value": "YES"
},
{
"type": "BONDING",
"description": "What is your bond rate?",
"unit": "PERCENTAGE",
"value": 4
},
{
"type": "BONDING",
"description": "Another bond rate",
"isCustom": true,
"unit": "PERCENTAGE",
"value": 2
},
{
"type": "CERTIFICATION",
"description": "Do you have this certification?",
"unit": "YES_NO",
"code": null,
"value": "YES"
},
{
"type": "LABOR_RATE",
"description": "What is the employee'\''s hourly rate?",
"unit": "PER_HOUR",
"value": 56
}
]
}'
Response
{
"id": "65cbcd5df324aa001de9d4b2",
"projectId": "64c2873f56831b0045b09ad7",
"bidPackageId": "64c2873f56831b0045b09b2f",
"inviteId": "64c287659e18eb131408497f",
"bidderCompanyId": "55271cb765eea0090005a295",
"creatorType": "HOST",
"notes": null,
"total": 315000,
"leveledTotal": 315000,
"createdAt": "2024-02-13T20:13:17.729Z",
"updatedAt": "2024-02-13T20:13:17.738Z",
"submittedAt": "2024-02-13T20:13:17.729Z",
"attachments": [ "64c7d2549923da545191cd14" ],
"revision": 0,
"createdBy": "62e2d09e5f849100753fb397",
"submittedBy": "62e2d09e5f849100753fb397",
"lineItems": {
"results": [
{
"id": null,
"type": "COST_BREAKDOWN",
"description": "Concrete",
"section": null,
"isRequired": true,
"isCustom": false,
"unit": "TOTAL_COST_ONLY",
"code": null,
"quantity": null,
"isQuantityFixed": false,
"unitCost": null,
"value": 315000
},
{
"id": "65cbcb234c40dfeeba96cd55",
"type": "ACKNOWLEDGMENT",
"description": "Do you acknowledge this?",
"section": null,
"isRequired": true,
"isCustom": null,
"unit": "YES_NO",
"code": null,
"quantity": null,
"isQuantityFixed": null,
"unitCost": null,
"value": "YES"
},
{
"id": "65cbcb234c40dfeeba96cd56",
"type": "BONDING",
"description": "What is your bond rate?",
"section": null,
"isRequired": true,
"isCustom": false,
"unit": "PERCENTAGE",
"code": null,
"quantity": null,
"isQuantityFixed": null,
"unitCost": null,
"value": 4
},
{
"id": "65cbcd5df324aa001de9d4b1",
"type": "BONDING",
"description": "Another bond rate",
"section": null,
"isRequired": true,
"isCustom": true,
"unit": "PERCENTAGE",
"code": null,
"quantity": null,
"isQuantityFixed": null,
"unitCost": null,
"value": 2
},
{
"id": "65cbcb234c40dfeeba96cd57",
"type": "CERTIFICATION",
"description": "Do you have this certification?",
"section": null,
"isRequired": true,
"isCustom": false,
"unit": "YES_NO",
"code": null,
"quantity": null,
"isQuantityFixed": null,
"unitCost": null,
"value": "YES"
},
{
"id": "65cbcb234c40dfeeba96cd58",
"type": "LABOR_RATE",
"description": "What is the employee's hourly rate?",
"section": null,
"isRequired": true,
"isCustom": false,
"unit": "PER_HOUR",
"code": null,
"quantity": null,
"isQuantityFixed": null,
"unitCost": null,
"value": 56
}
],
"pagination": {
"limit": 100,
"cursorState": null
}
},
"plugs": {
"results": [],
"pagination": {
"limit": 100,
"cursorState": null
}
}
}
Note that the lump sum amount is returned in a COST_BREAKDOWN
line item in the response.
Option 4B: Bid on Project and Scope Specific Bid Forms
A bid package with a scope specific bid form enables you to provide bid line items in addition to the ones on the bid forms. These are referred to in the API as custom line items identified by the boolean value "isCustom": true
.
Submit a new revision of your bid, but this time include additional custom line items. Note that a custom line item is permitted when its type is already present on the corresponding bid form.
Note that when a scope specific bid form contains a line item of type COST_BREAKDOWN
, the total
field is not accepted in the request. Instead, the lineItems
array must contain a line item of type COST_BREAKDOWN
that has the same description as the bid form.
Request
curl -X POST -v 'https://developer.api.autodesk.com/construction/buildingconnected/v2/bids' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT' \
-d '{
"inviteId": "64bfdd93f6a6c2504ac624f3",
"attachments": [ "64c7d2549923da545191cd14" ],
"lineItems": [
{
"type": "ALTERNATE",
"description": "Alternate 1",
"unit": "TOTAL_COST_ONLY",
"value": 200
},
{
"type": "COST_BREAKDOWN",
"description": "Line Item 1",
"unit": "TOTAL_COST_ONLY",
"value": 34300
},
{
"type": "COST_BREAKDOWN",
"description": "Line Item 2",
"unit": "CUBIC_FT",
"quantity": 5,
"unitCost": 60
},
{
"type": "COST_BREAKDOWN",
"description": "Line Item 3",
"isCustom": true,
"unit": "TOTAL_COST_ONLY",
"value": 11000
}
]
}'
Response
{
"id": "65cbcf840e95bb001d538721",
"projectId": "64bf017eb3e8944f292b4705",
"bidPackageId": "64bf0187f6a6c2504ac61173",
"inviteId": "64bf0193eeee3e4f187559d6",
"bidderCompanyId": "5430e7bc5cdc2e0300dd8b78",
"creatorType": "HOST",
"notes": null,
"total": 45600,
"leveledTotal": 45600,
"createdAt": "2024-02-13T20:22:28.727Z",
"updatedAt": "2024-02-13T20:22:28.795Z",
"submittedAt": "2024-02-13T20:22:28.727Z",
"attachments": [ "64c7d2549923da545191cd14" ],
"revision": 2,
"createdBy": "62e2d09e5f849100753fb397",
"submittedBy": "62e2d09e5f849100753fb397",
"lineItems": {
"results": [
{
"id": "65cbcf47f5806b211fe2617c",
"type": "ALTERNATE",
"description": "Alternate 1",
"section": null,
"isRequired": true,
"isCustom": false,
"unit": "TOTAL_COST_ONLY",
"code": null,
"quantity": null,
"isQuantityFixed": null,
"unitCost": null,
"value": 200
},
{
"id": "64bf01a6c96b2c49d2c66009",
"type": "COST_BREAKDOWN",
"description": "Line Item 1",
"section": null,
"isRequired": true,
"isCustom": false,
"unit": "TOTAL_COST_ONLY",
"code": null,
"quantity": null,
"isQuantityFixed": false,
"unitCost": null,
"value": 34300
},
{
"id": "65cbcf47f5806b211fe2617e",
"type": "COST_BREAKDOWN",
"description": "Line Item 2",
"section": null,
"isRequired": true,
"isCustom": false,
"unit": "CUBIC_FT",
"code": null,
"quantity": 5,
"isQuantityFixed": false,
"unitCost": 60,
"value": 300
},
{
"id": "65cbcf840e95bb001d538720",
"type": "COST_BREAKDOWN",
"description": "Line Item 3",
"section": null,
"isRequired": true,
"isCustom": true,
"unit": "TOTAL_COST_ONLY",
"code": null,
"quantity": null,
"isQuantityFixed": false,
"unitCost": null,
"value": 11000
},
{
"id": "65cbcf47f5806b211fe2617f",
"type": "SCOPE_CLARIFICATION",
"description": "I acknowledge this.",
"section": null,
"isRequired": null,
"isCustom": null,
"unit": null,
"code": null,
"quantity": null,
"isQuantityFixed": null,
"unitCost": null,
"value": null
}
],
"pagination": {
"limit": 100,
"cursorState": null
}
},
"plugs": {
"results": [],
"pagination": {
"limit": 100,
"cursorState": null
}
}
}