Manage Opportunity Projects and Pairs
This tutorial demonstrates how to create projects from opportunities and link them together. These relationships are called Opportunity Project Pairs. The steps include creating an opportunity project pair and relinking a paired project with a group parent opportunity.
For more information about opportunity groups, see the BuildingConnected API Field Guide.
Many bidders solicit pricing from their own subcontractor and vendors before submitting a bid to a client. BuildingConnected makes this easy. Bidders can create their own BuildingConnected Pro project from an existing opportunity, copying over information, files, bid forms, and NDAs. The opportunity and corresponding project are stored as an opportunityProjectPair object which can be identified by calling either GET opportunityProjectPairs or GET projects.
Note that the GET opportunities endpoint does not return information about opportunity project pairs.
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:readanddata:writescopes.
Step 1: Create an Opportunity Project Pair
To create a new pair, create a new project by calling POST projects, and include the opportunityProjectPair object to specify the opportunityId of the opportunity that you want the new project to be based on and paired with.
Note that the opportunity can be a parent or a child of an opportunity group, or it can be ungrouped.
The opportunityProjectPair object also contains four boolean options that enable you to specify which data you want copied from the opportunity. All of these options default to false:
includeClientFilesincludeInternalFilesincludeBidFormincludeNda
Note that if the opportunity contains a non-disclosure agreement (NDA), the includeNda field defaults to true.
The following example shows how to create a new project and opportunity project pair, copying only client files from the opportunity (as well as the opportunity’s NDA if it exists).
Request
curl -X POST -v 'https://developer.api.autodesk.com/construction/buildingconnected/v2/projects' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT' \
-d '{
"name": "Linked Project",
"opportunityProjectPair": {
"opportunityId": "64c018ac2e67d083fd9f8c49",
"includeClientFiles": true
}
}'
Response
{
"id": "650207c312afa70139343622",
"name": "Linked Project",
"number": null,
"client": null,
"description": null,
"notes": null,
"value": null,
"projectSize": null,
"awarded": "UNKNOWN",
"isBiddingSealed": false,
"state": "DRAFT",
"isNdaRequired": false,
"isPublic": false,
"createdAt": "2023-09-13T19:04:35.904Z",
"updatedAt": "2023-09-13T19:04:35.904Z",
"publishedAt": null,
"bidsDueAt": null,
"endsAt": null,
"rfisDueAt": null,
"startsAt": null,
"jobWalkAt": null,
"dueAt": null,
"location": {
"country": "US",
"state": "CA",
"streetName": "Market Street",
"streetNumber": "1",
"suite": null,
"city": "San Francisco",
"zip": "94105",
"complete": "1 Market St, San Francisco, CA 94105, USA",
"coords": {
"lat": 37.7940386,
"lng": -122.3950847
},
"precisionLevel": 10
},
"isTemplate": false,
"projectSizeUnits": "SQUARE_FEET",
"accountManager": null,
"feePercentage": null,
"marketSector": null,
"createdBy": "62e2d09e5f849100753fb397",
"defaultCurrency": "USD",
"owningOfficeId": "62e2d137c2f0a30059ea7821",
"architect": null,
"isForBudgeting": false,
"isCompetitive": true,
"currentAccLinkedProjectId": null,
"currentAccLinkedHubId": null,
"accProjectLinkedAt": null,
"originalProjectId": null,
"currentAccDocsFolderId": null,
"relevantCertificates": [],
"opportunityProjectPair": {
"id": "650207c412afa7013934363f",
"opportunityId": "64c018ac2e67d083fd9f8c49"
},
"isProjectNameShownBeforeSigningNda": false
}
This creates both a project (identified by id) and an opportunity-project pair (identified by opportunityProjectPair.id).
Step 2: (Optional) Relink Project with Group Parent Opportunity
An opportunity that’s paired with a project might subsequently be grouped (see the Create and Manage Opportunities tutorial). The project will remain paired with that opportunity.
Bid Board provides an in-app experience to relink a paired project with the group parent opportunity rather than with the originally linked opportunity which is now a child opportunity.
To relink the project to the group parent over API, call POST opportunity-project-pairs and include the project’s projectId and the group parent’s opportunityId in the request. The link to the child opportunity is removed.
Note that once a project is paired with a group parent opportunity, it cannot be relinked to a child opportunity.
Request
curl -X POST -v 'https://developer.api.autodesk.com/construction/buildingconnected/v2/opportunity-project-pairs' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT' \
-d '{
"opportunityId": "64c01d572e67d083fd9f8c4b",
"projectId": "650207c412afa7013934363f"
}'
Response
{
"id": "650209224a42e601656da3bf",
"createdBy": "62e2d09e5f849100753fb397",
"createdAt": "2023-09-13T19:10:26.979Z",
"updatedAt": "2023-09-13T19:10:26.979Z",
"opportunityId": "64c01d572e67d083fd9f8c4b",
"projectId": "64c01d572e67d083fd9f8a3f",
"fileSyncingError": null,
"shouldRelinkGroup": false,
"fileStatus": "QUEUED"
}
This returns the new opportunity-project pair.
