opportunities
Retrieves a list of the opportunities available to the user’s company.
To access the “Opportunity” data, the user making the request must be a verified employee of the company owning the opportunity and must be associated with an office that has a Pro subscription to Bid Board. The opportunity comments can only be accessed via the API if the office, identified by the ‘owningOfficeId’ for the opportunity, has a Bid Board Pro subscription. Contact your sales representative to gain access to the BuildingConnected API.
Resource Information
Method and URI | GET https://developer.api.autodesk.com/construction/buildingconnected/v2/opportunities |
Authentication Context | user context required |
Required OAuth Scopes | data:read |
Data Format | JSON |
Request
Headers
Authorization* string | Must be Bearer <token> , where <token> is obtained via a three-legged OAuth flow. |
Request
Query String Parameters
cursorState string | An opaque cursor token that identifies where the next page of paginated results should start. It’s returned in each paginated response so that it can be provided in the next request to continue paginated results. If a paginated response contains no cursorState value, there are no further pages to return.
Omit this parameter to initiate a paginated request or to restart pagination. |
limit int | The maximum number of records that the endpoint may return per page.
Note that a returned page may contain fewer records than the limit under either of these conditions:
Default value: |
filter[clientCompanyId] string | The BuildingConnected ID of a client company whose invites generated the opportunities that are returned in the response. |
filter[updatedAt] string | The required range of dates and times during which the last update must have been made to the objects returned in the response, in ISO 8601 format.
A single date and time takes this format: |
Response
HTTP Status Code Summary
200 OK | OK |
400 Bad Request | The parameters of the requested operation are invalid. |
401 Unauthorized | The provided bearer token is not valid. |
403 Forbidden | The user or service represented by the bearer token does not have permission to perform this operation. |
404 Not Found | The requested resource could not be found. |
429 Too Many Requests | Rate limit exceeded; wait some time before retrying. The ‘Retry-After’ header might provide the amount of the time to wait. |
500 Internal Server Error | An unknown error occurred on the server. |
Response
Body Structure (200)
pagination object | The pagination details of a response. |
limit int | The maximum number of records to return per page.
Note that a returned page may contain fewer records than the limit under either of these conditions:
|
cursorState string | An opaque cursor token that identifies where the next page of paginated results should start. It’s returned in each paginated response so that it can be provided in the next request to continue paginated results. If a paginated response contains no cursorState value, there are no further pages to return.
Omit this parameter to initiate a paginated request or to restart pagination. |
nextUrl string | The URL path that returns the next page of data. |
results array: object | Information about the returned opportunities. Opportunities represent invites to bid on a project. |
id string | The unique ID of the opportunity.
Max length: 24 |
name string | The name of the opportunity. The default value is the name of the project that the opportunity is for. |
number string | The opportunity’s number. This value need not be unique. |
client object | Information about the client company issuing the bid opportunity. |
company object | The company issuing the bid opportunity. |
id string | The company ID of the company issuing the bid opportunity.
Max length: 24 |
name string | The name of the company issuing the bid opportunity. |
lead object | The lead contact at the client’s company. |
id string | The BuildingConnected user ID of the client’s lead contact.
Max length: 24 |
email string | The email address of the client’s lead contact. |
firstName string | The first name of the lead contact. |
lastName string | The last name of the lead contact. |
phoneNumber string | The phone number of the lead contact. |
office object | The client company’s office that is issuing the bid opportunity. |
id string | The office ID of the office issuing the opportunity.
Max length: 24 |
location object | The structured address details for a location. |
country string | The country code of the location. |
state string | The state, territory, or province code of the location. |
streetName string | The street name of the location. This can be combined with streetNumber to get the street address. |
streetNumber string | The numeric value of the street address. This can be combined with streetName to get the street address. |
suite string | The suite number or second address line of the location. |
city string | The city of the location. |
zip string | The ZIP or Postal code of the location. |
complete string | The complete human-readable address of the location. |
coords object | The latitude and longitude coordinates of the location. |
lat number | The geographic latitude of the location. |
lng number | The geographic longitude of the location. |
precisionLevel int | The precision with which location identifies an actual place, on a scale of 0 to 10.
This value is initially |
name string | A name describing the office. |
competitors array: object | An array of competing bidders on the project. This can contain 20 bidders maximum. |
bidAmount number | The amount bid by the competitor. |
companyId string | The unique BuildingConnected company ID of the competitor.
Max length: 24 |
isWinner boolean | Indicates whether the competitor won the opportunity. Possible values:
|
name string | The name of the company. |
customTags array: string | An array of string values associated with the opportunity. |
createdAt datetime: ISO 8601 | The date and time that the opportunity was created, in ISO 8601 format. |
updatedAt datetime: ISO 8601 | The date and time that the opportunity was last updated, in ISO 8601 format. |
defaultCurrency string | The default currency used in the opportunity. |
source enum:string | Indicates how the opportunity was connected.
Possible values: DISCOVERED , DUPLICATE_BUILDINGCONNECTED , DUPLICATE_EMAIL , DUPLICATE_MANUAL , EMAIL , IMPORTED , MANUAL , BUILDINGCONNECTED , API |
isNdaRequired boolean | Indicates whether an NDA is required on the project. Possible values:
|
projectIsPublic boolean | Indicates whether the project is listed in the client company’s public plan room. |
outcome object | Information about the outcome of the opportunity. |
state enum:string | Indicates the outcome of the opportunity. Default: UNKNOWN .
Possible values: UNKNOWN , WON , LOST , OTHER |
otherReason enum:string | Indicates the reason when the outcome state is OTHER . If state is not OTHER , then this value is null.
Possible values: CANCELED , REBID , CLIENT_NOT_AWARDED , OTHER |
updatedAt datetime: ISO 8601 | The date and time that the opportunity’s outcome was set, in ISO 8601 format. |
updatedBy string | The ID of the user who set the outcome of the opportunity.
Max length: 24 |
requestType enum:string | Indicates the type of the opportunity.
Possible values: PROPOSAL , BUDGET |
submissionState enum:string | The current state of the opportunity’s proposal.
Note that |
workflowBucket enum:string | A highly specific status indicator of the opportunity.
Possible values: ACCEPTED_ACTIVE_CHILD , ACCEPTED_ACTIVE_ORPHAN , ACCEPTED_ACTIVE_PARENT , ACCEPTED_ARCHIVED_CHILD , ACCEPTED_ARCHIVED_ORPHAN , ACCEPTED_ARCHIVED_PARENT , DECLINED_ACTIVE_CHILD , DECLINED_ACTIVE_ORPHAN , DECLINED_ACTIVE_PARENT , DECLINED_ARCHIVED_CHILD , DECLINED_ARCHIVED_ORPHAN , DECLINED_ARCHIVED_PARENT , LOST_ACTIVE_CHILD , LOST_ACTIVE_ORPHAN , LOST_ACTIVE_PARENT , LOST_ARCHIVED_CHILD , LOST_ARCHIVED_ORPHAN , LOST_ARCHIVED_PARENT , OTHER_ACTIVE_CHILD , OTHER_ACTIVE_ORPHAN , OTHER_ACTIVE_PARENT , OTHER_ARCHIVED_CHILD , OTHER_ARCHIVED_ORPHAN , OTHER_ARCHIVED_PARENT , SUBMITTED_ACTIVE_CHILD , SUBMITTED_ACTIVE_ORPHAN , SUBMITTED_ACTIVE_PARENT , SUBMITTED_ARCHIVED_CHILD , SUBMITTED_ARCHIVED_ORPHAN , SUBMITTED_ARCHIVED_PARENT , UNDECIDED_ACTIVE_CHILD , UNDECIDED_ACTIVE_ORPHAN , UNDECIDED_ACTIVE_PARENT , UNDECIDED_ARCHIVED_CHILD , UNDECIDED_ARCHIVED_ORPHAN , UNDECIDED_ARCHIVED_PARENT , WON_ACTIVE_CHILD , WON_ACTIVE_ORPHAN , WON_ACTIVE_PARENT , WON_ARCHIVED_CHILD , WON_ARCHIVED_ORPHAN , WON_ARCHIVED_PARENT |
isParent boolean | Indicates whether this opportunity is a group parent. Possible values:
|
parentId string | The ID of this opportunity’s parent opportunity.
Max length: 24 |
groupChildren array: string | A list of the unique IDs of opportunities that are grouped under this opportunity. Only populated if this is a parent opportunity. |
bid object | The last bid submitted for this opportunity. This value is null if no bids have been submitted. Note that this value is always null if the opportunity is a group parent as bids can’t be submitted on group parents. |
id string | The ID of the bid.
Max length: 24 |
submittedAt datetime: ISO 8601 | The date and time the bid was submitted, in ISO 8601 format. |
total number | The total cost of the bid. |
revision number | The revision number of the bid. The first bid submitted by the bidder for a given bid package has a revision number of 0 (zero). Each time the bidder submits an updated bid, the new bid’s revision number is incremented by one. |
type enum:string | Indicates whether the bid was logged or sent to the client via BuildingConnected.
Possible values: SEND , LOG |
members array: object | An array of the users following the opportunity. |
viewedAt datetime: ISO 8601 | The date and time that the specified user first viewed the opportunity, in ISO 8601 format. |
userId string | The unique BuildingConnected user ID of the user following the opportunity. |
type enum:string | Indicates the specified user’s relationship to the opportunity, added for improved indexing and queries.
Possible values: ASSIGNEE , FOLLOWER , VENDOR |
dueAt datetime: ISO 8601 | The date and time that bids must be submitted for the opportunity, in ISO 8601 format. |
jobWalkAt datetime: ISO 8601 | The date and time that a job walk for the opportunity is scheduled, in ISO 8601 format. |
rfisDueAt datetime: ISO 8601 | The date and time that pre-bid RFIs are due, in ISO 8601 format. |
expectedStartAt datetime: ISO 8601 | The expected date and time that construction will start on site, in ISO 8601 format. |
expectedFinishAt datetime: ISO 8601 | The expected date and time that the construction project or a specified scope of work covered by the opportunity will complete, in ISO 8601 format. |
invitedAt datetime: ISO 8601 | The date and time that the invite corresponding to this opportunity was received, in ISO 8601 format.
Note that this value is not the same as |
tradeName string | The trade to which the opportunity applies. |
projectSize number | The area of the project in square feet. This value is always returned in units of square feet regardless of the unit it was originally specified with. For example, if it was specified in square meters, it will be converted to square feet. |
projectInformation string | General information about the opportunity. This field may contain HTML tags for formatting. |
location object | The structured address details for a location. |
country string | The country code of the location. |
state string | The state, territory, or province code of the location. |
streetName string | The street name of the location. This can be combined with streetNumber to get the street address. |
streetNumber string | The numeric value of the street address. This can be combined with streetName to get the street address. |
suite string | The suite number or second address line of the location. |
city string | The city of the location. |
zip string | The ZIP or Postal code of the location. |
complete string | The complete human-readable address of the location. |
coords object | The latitude and longitude coordinates of the location. |
lat number | The geographic latitude of the location. |
lng number | The geographic longitude of the location. |
precisionLevel int | The precision with which location identifies an actual place, on a scale of 0 to 10.
This value is initially |
tradeSpecificInstructions string | Description provided for the specific scope of work requested in the opportunity. This field may contain HTML tags for formatting. |
architect string | The name of the architect associated with the opportunity. |
engineer string | The name of the project engineer associated with the opportunity. |
propertyOwner string | The name of the property owner associated with the opportunity. |
propertyTenant string | The name of the property tenant associated with the opportunity. |
declineReasons array: string | The user’s internal justification for declining to bid the opportunity. |
additionalInfo string | Internal notes on the opportunity. This field may contain HTML tags for formatting. |
priority enum:string | The priority of this opportunity relative to other opportunities in your pipeline. Possible values:
|
marketSector enum:string | An internal value indicating the market sector of the construction project for tracking purposes.
Possible values: NONE , AIRPORT , ASSISTED_LIVING , AUTOMOTIVE_SERVICE_STATION , BRIDGE_TUNNEL , CASINO_GAMING , CLUBHOUSE , CONVENTION_CENTER , DATA_CENTER , DAY_CARE_CENTER_PRESCHOOL , EDUCATION_K12 , FINANCIAL , FITNESS_CENTER_GYM , GOLF_COURSE , GOVERNMENT_CIVIC , HIGHER_EDUCATION_DORMITORY , HIGHER_EDUCATION_INSTRUCTIONAL , HIGHER_EDUCATION_SPORTS_RECREATION , HIGHWAY_STREET , HOSPITAL , HOTEL_MOTEL , INFRASTRUCTURE , JAIL_PRISON , LABORATORY , LIBRARY , MANUFACTURING , MARINE , MILITARY , MUNICIPAL , MUSEUM_GALLERY , OFFICE_FINANCIAL , OFFICE_MEDICAL , OFFICE_OTHER , OFFICE_TENCHNOLOGY , PARK_RECREATION_SPORTS , PARKING , PERFORMANCE_CENTER , PIPELINE , POOL , POWER_INFRASTRUCTURE , POWER_PLANT , RELIGIOUS , RESIDENTIAL_MULTIFAMILY , RESIDENTIAL_SINGLE_FAMILY , RESTAURANT , RETAIL , SEWAGE_WASTE_DISPOSAL , SOLAR_POWER , STADIUM_ARENA , THEATER_AUDITORIUM , TRANSPORTATION_TERMINAL , WAREHOUSE , WATER_SUPPLY , WIND_FARM , OTHER |
rom number | The bidder company’s rough order of magnitude estimate of the value of the opportunity, provided as a number. Use the value of defaultCurrency to calculate the monetary value. |
winProbability number | A numeric value representing your company’s best guess at your probability of winning this opportunity. A value of 90 represents a high probability.
Possible values: |
followUpAt datetime: ISO 8601 | The date and time that the assignee should follow up on the opportunity, in ISO 8601 format. Bid Board will send the assignee a reminder email on this date. |
contractStartAt datetime: ISO 8601 | The date and time that you expect the contract to start, in ISO 8601 format. |
contractDuration number | The number of weeks that you expect the contract to last. |
averageCrewSize number | The average number of crew members you expect to be required on site during the contract. |
estimatingHours number | The number of hours that you expect to take to estimate the contract work for the opportunity. |
feePercentage number | The percentage of fees that a subcontractor can track for the opportunity. |
profitMargin number | The percent margin of profit that a subcontractor can track for the opportunity. |
finalValue number | The final proposed value of the user’s bid for this opportunity.
Often times a subcontractor will negotiate after a bid has been submitted, and the price you originally submitted may not be the final price. This field is used to indicate that final proposal value. |
isArchived boolean | Indicates whether the opportunity has been archived. Possible values:
|
owningOfficeId string | The unique ID of the BuildingConnected office to which this opportunity belongs.
Max length: 24 |
isSealedBidding boolean | Indicates whether bids will be sealed until the due date. Possible values:
|
clientValues object | If the opportunity was created from a BuildingConnected project and bid package, this object’s properties were copied from their corresponding original fields in the project and bid package at creation.
Note, however, that if the value of any of these fields is modified either in the original or in the opportunity, they will no longer match. If the opportunity was not created from a BuildingConnected project and bid package, this object’s value is null. |
name string | The name of the project. |
dueAt string | The date and time that bids must be submitted by, in ISO 8601 format. |
jobWalkAt string | The date and time that a job walk is scheduled, in ISO 8601 format. |
rfisDueAt string | The date and time that pre-bid RFIs are due, in ISO 8601 format. |
expectedStartAt string | The expected date and time that construction will start on site, in ISO 8601 format. |
expectedFinishAt string | The expected date and time that the construction project or a specified scope of work covered by the bid package will complete, in ISO 8601 format. |
tradeName string | The trade to which the bid package applies. |
projectSize number | The area of the project in square feet.
Note that this value is always returned in units of square feet regardless of the unit it was originally specified with. For example, if it was specified in square meters, it will be converted to square feet. |
projectInformation string | General information about the project. This field may contain HTML tags for formatting. |
location object | The structured address details for a location. |
country string | The country code of the location. |
state string | The state, territory, or province code of the location. |
streetName string | The street name of the location. This can be combined with streetNumber to get the street address. |
streetNumber string | The numeric value of the street address. This can be combined with streetName to get the street address. |
suite string | The suite number or second address line of the location. |
city string | The city of the location. |
zip string | The ZIP or Postal code of the location. |
complete string | The complete human-readable address of the location. |
coords object | The latitude and longitude coordinates of the location. |
lat number | The geographic latitude of the location. |
lng number | The geographic longitude of the location. |
precisionLevel int | The precision with which location identifies an actual place, on a scale of 0 to 10.
This value is initially |
tradeSpecificInstructions string | A description provided for the specific scope of work requested in the bid package. This field may contain HTML tags for formatting. |
architect string | The name of the architect associated with the project. |
Example
OK
Request
curl -v 'https://developer.api.autodesk.com/construction/buildingconnected/v2/opportunities?filter[updatedAt]=2020-05-01T06:00:00.000Z..' \
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a'
Response
{
"pagination": {
"limit": 100,
"cursorState": "eyJsaW1pdCI6MjUsIm9mZnNldCI6MjV9",
"nextUrl": ""
},
"results": [
{
"id": "5c3f0a5c9ca3dda548312ea5",
"name": "Office Renovation",
"number": "12345",
"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
},
"precisionLevel": 10
},
"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,
"projectIsPublic": false,
"outcome": {
"state": "WON",
"otherReason": "CANCELED",
"updatedAt": "2020-01-16T17:20:00.563Z",
"updatedBy": "58ed681b195f9a0b00708c4b"
},
"requestType": "PROPOSAL",
"submissionState": "SUBMITTED",
"workflowBucket": "WON_ACTIVE_CHILD",
"isParent": true,
"parentId": "5b3f0a5c9d4fdda548313b92",
"groupChildren": [
"5d4f0a5c9ca3cbd548313b5a"
],
"bid": {
"id": "611ee35b3935e500a8b18c8a",
"submittedAt": "2021-08-19T23:07:16.083Z",
"total": 5000,
"revision": 0,
"type": "SEND"
},
"members": [
{
"viewedAt": "2021-08-19T23:10:16.093Z",
"userId": "5654f7bf8845796ad73bd4e0",
"type": "ASSIGNEE"
}
],
"dueAt": "2014-09-03T08:00:00.000Z",
"jobWalkAt": "2015-03-31T07:00:00.000Z",
"rfisDueAt": "2014-09-25T19:00:00.000Z",
"expectedStartAt": "2014-11-03T08:00:00.000Z",
"expectedFinishAt": "2015-03-31T07:00:00.000Z",
"invitedAt": "2014-10-03T19:00:00.000Z",
"tradeName": "Electrical",
"projectSize": 2000,
"projectInformation": "",
"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
},
"precisionLevel": 10
},
"tradeSpecificInstructions": "",
"architect": "",
"engineer": "Name of engineer",
"propertyOwner": "",
"propertyTenant": "",
"declineReasons": [
"LOCATION"
],
"additionalInfo": "",
"priority": "UNKNOWN",
"marketSector": "AIRPORT",
"rom": "",
"winProbability": 10,
"followUpAt": "",
"contractStartAt": "",
"contractDuration": "",
"averageCrewSize": "",
"estimatingHours": 400,
"feePercentage": 10,
"profitMargin": 20,
"finalValue": 5000,
"isArchived": false,
"owningOfficeId": "614f0a5c9ca3cbd548313c5b",
"isSealedBidding": "",
"clientValues": {
"name": "",
"dueAt": "",
"jobWalkAt": "",
"rfisDueAt": "",
"expectedStartAt": "",
"expectedFinishAt": "",
"tradeName": "",
"projectSize": "",
"projectInformation": "",
"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
},
"precisionLevel": 10
},
"tradeSpecificInstructions": "",
"architect": "Browning Day Mullins Dierdorf Architects"
}
}
]
}