Sync Bid Board with Your CRM
This tutorial demonstrates how to retrieve and use opportunity data to manage your opportunities in your own CRM application. The steps include retrieving opportunities, identifying clients, managing groups, and creating navigation links.
As a BuildingConnected invitee, Bid Board enables you to centralize all opportunity creation. Opportunities are created automatically when your company is invited to bid on a job, and you can import invites from other source to consolidate all invites onto a single platform. For more information, see How to forward invites from your inbox to BuildingConnected (Bid Board Pro).
You can use Bid Board as your primary invite management service while simultaneously operating a CRM tool like Salesforce or Microsoft Dynamics without doing manual work to keep your CRM updated.
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:read
scope.
Step 1: Retrieve Selected Opportunities
Query Bid Board for new and existing opportunities by calling GET opportunities. There are query parameters you can use to narrow your search:
filter[clientCompanyId]
limits the response to opportunities received from the specified client.filter[updatedAt]
limits the response to opportunities that were created or updated since the last time you called GET opportunities.
Request
curl 'https://developer.api.autodesk.com/construction/buildingconnected/v2/opportunities' \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT'
Response
{
"pagination": {
"limit": 100,
"offset": 0
},
"results": [
{
"id": "5c3f0a5c9ca3dda548312ea5",
"client": {
"company": {
"id": "5d420a4c9caedd854831e89a",
"name": "Building Group"
},
"lead": {
"id": "5a1ca5eb48d14a74b5bcf4a9",
"email": "someone@gmail.com",
"firstName": "First",
"lastName": "Last",
"phoneNumber": "555-555-5555"
},
"office": {
"id": "56d2bd74c0b92a0c525823d6",
"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
}
},
"name": "San Francisco Office"
}
},
"competitors": [
{
"bidAmount": 4500,
"companyId": "56d2bd7440b37a0da258c4b9",
"isWinner": true,
"name": "Builders"
}
],
"customTags": [],
"createdAt": "2020-01-13T17:20:29.492Z",
"updatedAt": "2020-01-15T17:20:29.492Z",
"defaultCurrency": "USD",
"source": "BUILDINGCONNECTED",
"isNdaRequired": true,
"isPublic": false,
"outcome": {
"state": "WON",
"updatedAt": "2020-01-16T17:20:00.563Z",
"updatedBy": "58ed681b195f9a0b00708c4b"
},
"requestType": "PROPOSAL",
"submissionState": "SUBMITTED",
"workflowBucket": "WON_ACTIVE_CHILD",
"isParent": false,
"parentId": "5b3f0a5c9d4fdda548313b92",
"groupChildren": [],
"bid": {
"id": "611ee35b3935e500a8b18c8a",
"submittedAt": "2021-08-19T23:07:16.083Z",
"total": 5000,
"revision": 2,
"type": "SEND"
},
"members": {
"viewedAt": "2021-08-19T23:10:16.093Z",
"userId": "5654f7bf8845796ad73bd4e0",
"type": "ASSIGNEE"
},
"engineer": "Name of engineer",
"estimatingHours": 400,
"feePercentage": 10,
"profitMargin": 20,
"finalValue": 5000,
"isArchived": false
}
]
}
Step 2: Identify Clients
We include BuildingConnected’s representation of a unique company ID in the response (client.company.id
). This is not equivalent to other representations of company IDs found elsewhere in ACC APIs. We recommend using your BuildingConnected company ID.
Each invite is hosted by a specific office at the client company (typically the GC). Companies may have many offices. Use client.office.id
to differentiate which office or branch has sent you an opportunity.
Step 3: Manage Groups
Opportunities can be grouped together. We recommend that opportunities are grouped when there are multiple potential clients bidding on the same project. Opportunities are grouped under “parent” opportunities, which are highly similar to other opportunities in most respects.
Each opportunity has its own ID, including the parent opportunity. In the diagram below, all three original opportunities that are nested under the group parent “Salesforce Tower” have the following properties:
isParent=false
to indicate that they are not parentsparentId=[opportunityId of Salesforce Tower]
Meanwhile, group parent “Salesforce Tower” is differentiated by these properties:
isParent=true
to indicate that it is a parentgroupChildren
is an array of the IDs for the three nested opportunities
