This release brings a security improvement to the BuildingConnected API. It adds endpoints for retrieving and signing an opportunity's NDA, adds NDA signature tracking to opportunity members, and applies NDA-based access controls across the Opportunities and Opportunity Project Pairs resources. It also changes how opportunity project pairs are returned when their opportunity has been deleted.
Several existing endpoints now return 403 Forbidden when an opportunity requires an NDA that the current user has not signed, so integrations that work with NDA-protected opportunities should review the sections below. For the complete list, see the BuildingConnected change log. What follows covers the main changes.
Opportunities
A general contractor (GC) can attach an NDA to an opportunity. Until now, the API had no endpoints for working with that NDA, so an integration could not download the document or sign it, and opportunity responses did not show which members had signed. This release adds both, and makes the existing opportunity endpoints aware of NDA status.
Opportunity NDA API
An opportunity's NDA is the document the GC attached to it. The API now lets an integration download that document and sign it as the current user, so an app can check whether an opportunity requires an NDA, retrieve and sign it, and then access the full opportunity details.
GET /opportunities/{opportunityId}/nda(downloads the NDA document attached to the opportunity by the GC)POST /opportunities/{opportunityId}/nda:sign
We've also added the Manage Opportunity NDAs tutorial, which demonstrates this sequence: checking whether an opportunity requires an NDA, retrieving and signing it, and accessing the full opportunity details after signing.
NDA Signature Tracking for Members
Opportunity responses now include members[].ndaSignedAt, the date and time each member signed the NDA. The value is null if the member has not signed it. The field is returned by:
GET /opportunitiesGET /opportunities/{opportunityId}POST /opportunitiesPATCH /opportunities/{opportunityId}
Note: When you include members (userId and type) in the request body of POST /opportunities, ndaSignedAt is always null in the response. An NDA cannot be attached to foreign opportunities through the API or the UI, so ndaSignedAt is always null in this case.
NDA-Based Access Controls for Opportunities
If an opportunity requires an NDA that the current user has not signed, the following endpoints now behave differently:
GET /opportunities/{opportunityId}(returns limited opportunity details)PATCH /opportunities/{opportunityId}(returns403 Forbidden)GET /opportunities/{opportunityId}/comments(returns403 Forbidden)GET /opportunities/{opportunityId}/comments/{commentId}(returns403 Forbidden)
Note: These 403 Forbidden responses apply only to opportunities that are NDA protected, for users who have not signed the NDA.
Together with the NDA endpoints, a user can now go from limited details to the full opportunity entirely through the API: check whether the opportunity requires an NDA with GET /opportunities/{opportunityId} → retrieve it with GET /opportunities/{opportunityId}/nda → sign it with POST /opportunities/{opportunityId}/nda:sign → access the full opportunity details.
Opportunity Project Pairs
NDA-Based Access Controls for Opportunity Project Pairs
Creating or updating an opportunity project pair now returns 403 Forbidden if the associated opportunity requires an NDA that the current user has not signed.
Opportunity Project Pairs for Deleted Opportunities
Opportunity project pairs associated with deleted opportunities are now handled as follows:
GET /opportunity-project-pairs(excludes these opportunity project pairs from its response)GET /opportunity-project-pairs/{opportunityProjectPairId}(returns404 Not Found)PATCH /opportunity-project-pairs/{opportunityProjectPairId}(returns404 Not Found)
Documentation
If you have questions or feedback about any of these changes, please get in touch with us through the APS support channel