Request

Response

    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 and data: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
    }'
    
    Show More

    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"
    }
    
    Show More

    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"'
    
    Show More

    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" ]
    }'
    
    Show More

    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
            }
        }
    }
    
    Show More

    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
            }
        ]
    }'
    
    Show More

    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
            }
        }
    }
    
    Show More

    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
            }
        ]
    }'
    
    Show More

    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
            }
        }
    }
    
    Show More