Create and Update a Risk Flag
This walkthrough demonstrates how to create and update a subcontractor risk flag in TradeTapp from an external system. Flags are objects on subcontractor or vendor records that help general contractors annotate key qualification information, such as safety or financial concerns.
You can identify the subcontractor by specifying one of the following identifiers in your request:
companyId, taxId (without hyphens), or taxType.
When creating a flag, you can optionally mark it to trigger an alert, which displays a pop-up modal when a user opens the subcontractor’s profile in TradeTapp.
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. The TradeTapp API is housed under the BuildingConnected API heading.
- Acquire a 3-legged OAuth token with
data:readanddata:writescopes. - Find a subcontractor’s
companyId,taxId, andtaxTypeto use when creating the flag by calling GET financials or GET qualifications. In these responses,taxIdis returned asfederalTaxIdandtaxTypeis returned astaxIdType.
Important: TradeTapp API v2 will return data points for instances where an invited subcontractor has made at least one historical submission or the data was imported. Data will not be returned for the following circumstances:
- Invitations where the subcontractor has been invited but has not yet made a submission
- Project approval data (This function is currently not supported by APIs)
Understanding User Types
It is important to understand which users have access to which flags.
Flags include a field named isVisibleInPlatform that determines whether a flag is visible to TradeTapp users only, or to both TradeTapp users and BuildingConnected (BC) users who do not have a TradeTapp license.
TradeTapp Users
A TradeTapp user is any user who has an active TradeTapp account. If the user can log into their TradeTapp account, they are considered a TradeTapp user.
These users always have access to all flags created via the API, regardless of the value of isVisibleInPlatform.
BC Users without TradeTapp Licenses
A BC user without a TradeTapp license is any user who belongs to your general contractor company’s BC account (which must be linked to your TradeTapp account) but does not have an active TradeTapp account.
BC users without TradeTapp licenses only have access to flags where isVisibleInPlatform is set to true.
Step 1 – Create a Flag
Use the subcontractor’s identifier (companyId or taxId and taxType if applicable) to call POST flags
and create a new risk flag in TradeTapp.
A flag records key qualification information such as safety, insurance, or financial concerns.
Notes:
You must specify at least one identifier — either
companyIdortaxId. If both are provided, they must refer to the same subcontractor. When multiple subcontractors share the sametaxIdbut have differenttaxTypevalues, includetaxTypeto ensure the correct record is found. If no subcontractor matches the supplied identifiers, the request returns an error and no flag is created.
Optionally, set triggerAlert to true to display a pop-up alert when a user opens the subcontractor’s profile in TradeTapp.
Request
curl -X POST -v 'https://developer.api.autodesk.com/construction/tradetapp/v2/flags' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN_VALUE>' \
-d '{
"companyId": "59d2b8660675250927442cbf",
"taxId": "321654876",
"taxType": "US_FEIN",
"eventDate": "2017-05-21",
"name": "Safety Concern",
"priority": "HIGH",
"summary": "This application has a high safety concern due to a high number of injuries.",
"type": "GENERAL",
"triggerAlert": true,
"isVisibleInPlatform": false
}'
Response
{
"id": 1265,
"company":
{
"id": "59d2b8660675250927442cbf",
"uniqueId": "98h2fbd84k9s322chr",
"name": "Gr8 Builders",
"taxId": "321654876",
"taxType": "US_FEIN"
},
"name": "Safety Concern",
"type": "GENERAL",
"priority": "HIGH",
"eventDate": "2017-05-21",
"summary": "This application has a high safety concern due to a high number of injuries.",
"triggerAlert": true,
"isVisibleInPlatform": false,
"flagProposalId": null,
"updatedAt": "2017-05-04T14:11:35.100929Z",
"createdAt": "2017-05-04T14:11:35.100929Z",
"createdBy":
{
"firstName": "Jane",
"lastName": "Doe",
"email": "user@example.com",
"id": "ABCDEF3XYZABCD1M"
},
"state":
{
"createdAt": "2017-05-04T14:11:35.100929Z",
"updatedAt": "2017-05-04T14:11:35.100929Z",
"value": "ACTIVE",
"summary": "This flag was opened due to safety concerns arising.",
"createdBy":
{
"firstName": "Jane",
"lastName": "Doe",
"email": "user@example.com",
"id": "ABCDEF3XYZABCD1M"
}
}
}
Note the flag ID (id - 1265 for the next step.
Step 2 – Update the Flag
Use the Flag ID (1265) from Step 1 to call PATCH flags/:flagId and update the flag’s status or details.
This endpoint supports partial updates: include only the fields you want to change (for example, priority, summary, or triggerAlert).
You can also resolve a flag by setting state.value to RESOLVED and adding a brief state.summary.
Request
curl -X PATCH -v 'https://developer.api.autodesk.com/construction/tradetapp/v2/flags' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN_VALUE>' \
-d '{
"eventDate": "2017-05-21",
"name": "Safety Concern",
"priority": "HIGH",
"summary": "This application has a high safety concern due to a high number of injuries.",
"type": "GENERAL",
"triggerAlert": true,
"state": {
"value": "RESOLVED",
"summary": "This flag has been resolved because concerns have been addressed."
}
}'
Response
{
"id": 1234,
"company":
{
"id": "59d2b8660675250927442cbf",
"uniqueId": "98h2fbd84k9s322chr",
"name": "Gr8 Builders",
"taxId": "321654876",
"taxType": "US_FEIN"
},
"name": "Safety Concern",
"type": "GENERAL",
"priority": "HIGH",
"eventDate": "2017-05-21",
"summary": "This application has a high safety concern due to a high number of injuries.",
"triggerAlert": true,
"isVisibleInPlatform": false,
"flagProposalId": 1234,
"updatedAt": "2017-05-04T14:11:35.100929Z",
"createdAt": "2017-05-04T14:11:35.100929Z",
"createdBy":
{
"firstName": "Jane",
"lastName": "Doe",
"email": "user@example.com",
"id": "ABCDEF3XYZABCD1M"
},
"state":
{
"createdAt": "2017-05-04T14:11:35.100929Z",
"updatedAt": "2017-05-04T14:11:35.100929Z",
"value": "RESOLVED",
"summary": "This flag has been resolved because concerns have been addressed.",
"createdBy":
{
"firstName": "Jane",
"lastName": "Doe",
"email": "user@example.com",
"id": "ABCDEF3XYZABCD1M"
}
}
}
To review the change history later, call GET flags and include include=stateHistory in the request, or call GET flags/:flagId/state-history.
Congratulations! You have created and updated a risk flag in TradeTapp.