Trimble Connect Status Sharing

The Trimble Connect Status Sharing tool enables cloud-based BIM supply chain management. You can control and keep track of assembly and object-level status information for project management, scheduling, and design review purposes.

The Status Sharing tool is built directly into the Trimble Connect experience — there is nothing separate to download or install:

• Tekla Structures: The Status Sharing UI is embedded directly in Tekla Structures without requiring a separate download or installation.
• Trimble Connect for Browser: The same Status Sharing UI is embedded into Trimble Connect for Browser.
• Trimble Connect for Windows: The same Status Sharing UI is embedded into Trimble Connect for Windows.
• Trimble Connect for Mobile: A mobile version of Status Sharing is also available in the Trimble Connect for Mobile app so that statuses can be viewed on the go.

Usage of Trimble Connect Status Sharing API

The Status Sharing API lets you share and track construction/production status for objects in a project in real time, and keep that status in sync between your own systems and Trimble Connect.

It's built for two directions of integration:

• Push status into Trimble Connect: External systems — for example a fabrication ERP, MES, or scheduling tool — can publish status updates via the API so they show up as a live status feed on the BIM model inside your respective application (Tekla Structures, Trimble Connect for Browser, Trimble Connect for Windows or Trimble Connect for Mobile).
• Read status out of Trimble Connect: Statuses set from within the Trimble Connect user interfaces (or by any other integration) can be read back by external systems, so your own tools stay up to date with what's happening on the project.

In short: if you have a system that tracks the status of objects — fabrication, delivery, installation, inspection, etc. — the Status Sharing API is how you connect that system's status data to the BIM model, in either direction.

Domain model

Project
 ├── Groups                   ← Trimble Connect project groups
 └── Status actions (workflows)
      ├── Custom status values ← own value list (Custom actions only)
      ├── Group access         ← per-group access level on the action
      ├── Current statuses     ← latest state per object + action
      └── Status events        ← history of changes

Access tokens are region-specific

With the Status Sharing API, all requests including the access_token exchange are done against the region-specific servers in the same regions as core Trimble Connect. So the access_tokens are region-specific.

Accessing the API

The API is a standard RESTful API. It uses GET to retrieve information, PUT to store or update a resource, POST to create a new resource, and DELETE to remove it. You can get the region-specific server URLs by adding the Trimble Connect region name to the beginning of the base URL:

Each region's base URL automatically redirects to its own /scalar/v1 API reference, so you can check the reference for any region either by visiting its base URL directly or by adding /scalar/v1 to the end — for example, https://europe.tcstatus.tekla.com redirects to https://europe.tcstatus.tekla.com/scalar/v1.

Status values

Status actions are set up per project to match your process. An action uses either the predefined status values below or its own custom status values (see Custom status values).

The predefined status values and their codes are:

• None (0)
• Enable (1)
• Commit (2)
• Started (3)
• Paused (4)
• Completed (5)

Which predefined values an action accepts is set per action with allowedValues, a comma-separated list of names such as "None,Started,Paused,Completed".

Custom status values

Instead of the predefined values above, a status action can define its own list of values that match your process — for example Ordered, Delivered, Installed. Which kind of values an action uses is set by its valueMode:

valueMode is chosen when the action is created and cannot be changed afterwards. If it is omitted, the action is Predefined.

Each custom status value has the following fields:

A status action can have at most 15 custom status values.

The value field on status events and current statuses

The value of a status event or current status is either a JSON integer or a JSON string:

• Integers: 0–5 for the predefined values (None = 0, Enable = 1, Commit = 2, Started = 3, Paused = 4, Completed = 5), and 100–114 for custom status value codes.
• Strings: the name of a predefined value or of one of the action's custom values, for example "Started" or "MyCustomValue". Names are matched case-insensitively.

Responses return value as the value's name. A value that isn't allowed for its action (a predefined value not in allowedValues, or a code or name that doesn't exist on a custom action) rejects the whole request with 400 Bad Request.

Code examples

Authenticate with Trimble Identity using Oauth 2.0

See the Getting Started Guide for details. As a result, the Trimble Identity access_token is returned.

Notice the below examples are for the EU region.

Exchange the access_token for a Status Sharing API access token

The status_token is returned in the response body as a JSON string.

POST https://europe.tcstatus.tekla.com/statusapi/1.0/auth/token
Authorization: Bearer <access_token>

Optional query parameters:

• projectId — one or more comma-separated project IDs to scope the token to.
• admin — optional boolean requesting admin rights on the token. The parameter exists, but admin-license enforcement is currently disabled, so the API grants admin rights regardless of whether true or false is supplied.

The Status Sharing API can then be invoked using the status_token. Your organization and your project group memberships decide which status actions you can read and write (see License levels and access rules).

Check if statuses are enabled for a project

Does not require authentication — useful as a lightweight probe before exchanging a token.

GET https://europe.tcstatus.tekla.com/statusapi/1.0/auth/enabled/<project_id>

List projects you have access to

GET https://europe.tcstatus.tekla.com/statusapi/1.0/projects
Authorization: Bearer <status_token>

Query Status Actions in a project

GET https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/statusactions
Authorization: Bearer <status_token>

GET .../statusactions/{id}, PUT .../statusactions/{id} and DELETE .../statusactions/{id} are also available for reading, updating, and deleting a single status action.

Only the actions you can read are returned. Each action includes valueMode, isWritable and — when you can read but not write it — accessDeniedReason.

You can also filter to just the actions tagged with one or more values (any match):

GET https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/statusactions
?tags=fabrication,delivery
Authorization: Bearer <status_token>

If no readable action matches any of the tags, all readable actions are returned.

GET .../statusactions, GET .../status and GET .../statusevents support filtering and sorting on their fields with a standard OData $filter/$orderby/$top/$skip/$select query string, for example:

GET https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/statusevents
?$filter=statusActionId eq <action_id> and value eq 5&$orderby=changeDate desc
Authorization: Bearer <status_token>

Get current statuses for an action

GET https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/status
?statusActionId=<action_id>
Authorization: Bearer <status_token>

GET .../status and GET .../statusevents both accept optional objectId and statusActionId filters, each as a comma-separated list to filter on multiple values at once, e.g. ?statusActionId=<action_id_1>,<action_id_2>. Statuses on actions you can't read are left out; if none of the requested actions are readable, the request returns 403 with a GROUP_ACCESS_ERROR_TYPE or ORGANIZATION_ACCESS_ERROR_TYPE error.

Add a Status Action

POST https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/statusactions
Authorization: Bearer <status_token>
Content-Type: application/json

{
       "isPublic": true,
       "name": "Test action",
       "valueMode": "Predefined",
       "allowedValues": "None,Started,Paused,Completed"
}

The action is owned by your organization. name is required (max 200 characters); description (max 300) and tags (comma-separated, max 200) are optional. Creating actions requires a FULL_ACCESS license. The API also checks the token's admin claim, but admin-license enforcement is currently disabled, so exchanged tokens receive admin rights regardless of the admin query-parameter value.

PUT .../statusactions/{id} keeps the action's valueMode, and callers from another organization cannot change its owning organization. DELETE .../statusactions/{id} removes the action from all lists.

Add Status Events for two objects

POST https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/statusevents
Authorization: Bearer <status_token>
Content-Type: application/json

[{
       "objectId": "ifc-guid1",
       "statusActionId": "<action_id>",
       "value": "Completed",
       "valueDate": "2017-06-01T19:54:30.00Z"
},
{
       "objectId": "ifc-guid2",
       "statusActionId": "<action_id>",
       "value": "Paused",
       "valueDate": "2017-06-02T16:30:00.00Z"
}]

Note: Object guids must be in the IFC GUID format.

value can be the value's name or its code (for example "Completed" or 5). Up to 5000 events can be sent per request, and the request body is limited to 2 MB. All events must be on actions you can write to; one invalid value or unwritable action rejects the whole request.

Add a Status Action with custom status values

POST https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/statusactions
Authorization: Bearer <status_token>
Content-Type: application/json

{
       "isPublic": true,
       "name": "Delivery",
       "valueMode": "Custom"
}

Add custom status values to an action

One or more values can be added in a single request. Codes are assigned by the server in the order the values are sent.

POST https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/statusactions/<action_id>/customstatusvalues
Authorization: Bearer <status_token>
Content-Type: application/json

[{
       "name": "Ordered",
       "color": "#737373",
       "isActive": true,
       "order": 1
},
{
       "name": "Delivered",
       "color": "#217CBB",
       "isActive": true,
       "order": 2
}]

Response (201 Created):

[
  { "statusActionId": "<action_id>", "code": 100, "order": 1, "name": "Ordered", "color": "#737373", "isActive": true, "changeDate": "2026-09-29T10:00:00Z", "changeUserId": "<user_id>" },
  { "statusActionId": "<action_id>", "code": 101, "order": 2, "name": "Delivered", "color": "#217CBB", "isActive": true, "changeDate": "2026-09-29T10:00:00Z", "changeUserId": "<user_id>" }
]

Adding values to a Predefined action, going over 15 values, reusing a name, or sending an order outside 1–15 returns 400 Bad Request.

List or read custom status values

GET https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/statusactions/<action_id>/customstatusvalues
Authorization: Bearer <status_token>

GET .../customstatusvalues/{code} returns a single value.

Update a custom status value

The body replaces name, color, isActive and order, so send all of them — omitting order clears it. The code is taken from the URL and cannot be changed.

PUT https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/statusactions/<action_id>/customstatusvalues/101
Authorization: Bearer <status_token>
Content-Type: application/json

{
       "name": "Delivered to site",
       "color": "#217CBB",
       "isActive": true,
       "order": 2
}

Add Status Events on a custom action

Use either the custom value's code or its name:

POST https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/statusevents
Authorization: Bearer <status_token>
Content-Type: application/json

[{
       "objectId": "ifc-guid1",
       "statusActionId": "<action_id>",
       "value": 101,
       "valueDate": "2026-09-29T08:00:00.00Z"
},
{
       "objectId": "ifc-guid2",
       "statusActionId": "<action_id>",
       "value": "Ordered",
       "valueDate": "2026-09-29T08:30:00.00Z"
}]

List the groups in a project

Returns the Trimble Connect groups of the project, so you can pick the group IDs to use in group access.

GET https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/groups
Authorization: Bearer <status_token>

Response:

[
  { "id": "<group_id_1>", "name": "Fabrication" },
  { "id": "<group_id_2>", "name": "Site" }
]

Read the group access of a status action

GET https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/statusactions/<action_id>/groupaccess
Authorization: Bearer <status_token>

Response:

[
  { "statusActionId": "<action_id>", "groupId": "<group_id_1>", "name": "Fabrication", "accessLevel": "FULL_ACCESS", "changeDate": "2026-09-29T10:00:00Z", "changeUserId": "<user_id>" },
  { "statusActionId": "<action_id>", "groupId": "<group_id_2>", "name": "Site", "accessLevel": "READ_ACCESS", "changeDate": "2026-09-29T10:00:00Z", "changeUserId": "<user_id>" }
]

name is the group's current name in Trimble Connect, resolved when the entries are read.

Set the group access of a status action

PUT replaces the whole group access list: whatever you send becomes the complete list, and any existing entry not included is removed. There is no PATCH or per-group add/delete — to remove a group, send the list without it; to change a group's level, send the full list with the new level.

PUT https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/statusactions/<action_id>/groupaccess
Authorization: Bearer <status_token>
Content-Type: application/json

[{
       "groupId": "<group_id_1>",
       "accessLevel": "FULL_ACCESS"
},
{
       "groupId": "<group_id_2>",
       "accessLevel": "NO_ACCESS"
}]

Sending an empty list [] removes all group access from the action. Each entry needs a groupId, and a group can appear only once — otherwise the request returns 400 Bad Request. Entries for groups that no longer exist in the project are dropped, and the response lists the entries that were kept.

License levels and access rules

Access is gated first by a project-wide license level, then refined per action:

The following per-action rules come on top of the license level. When none of your project groups have a group access entry on the action:

• an action is readable if it belongs to your organization or isPublic is true.
• it's writable only if it belongs to your organization.

When one or more of your groups do have an entry on the action, group access decides instead — see Group access below.

To check your license level for a project, call GET /statusapi/1.0/license/{projectId} (see Error responses for how to read its result).

Group access

Access to a single status action can also be granted per Trimble Connect project group, using the same three levels:

How group access combines with the rules above:

• The project license level is still checked first — a group entry never grants more than the caller's license allows.
• If the caller belongs to one or more groups that have an entry on the action, those entries decide access and the organization / isPublic rules are not used for that action. When several of the caller's groups have entries, the highest level wins.
• If none of the caller's groups have an entry on the action, the organization / isPublic rules apply. An action with no group access entries works on organization / isPublic alone.
• A NO_ACCESS entry denies the group's members even if the action belongs to their organization.

Group access applies to both Predefined and Custom actions, and covers everything on the action: the action itself, its custom status values, its current statuses and status events, and its group access list.

Reading group access requires read access to the action; changing it requires a FULL_ACCESS license and write access to the action.

Status actions returned by the API include two fields that reflect the caller's access:

Blocked actions and the state-transition limit

• An action can become blocked, preventing new status events from being created on it.
• If a single object + action pair accumulates more than 100 status-event transitions, the action is automatically blocked for every user, not just that object. Clearing this requires contacting support — there is no self-service unblock.

Region-specific rate limiting

A WAF-level rate limit (keyed on Authorization header + caller IP) is planned per region:

Pagination

The non-paginated GET .../status and GET .../statusevents endpoints return 413 Payload Too Large when the result would exceed 50,000 rows. For larger result sets, use the cursor-based /page endpoints, which page reliably without missing or duplicating rows as new events come in:

• GET .../status/page
• GET .../statusevents/page

Parameters:

First request (no cursor needed):

GET https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/statusevents/page
?statusActionId=<action_id>&pageSize=1000
Authorization: Bearer <status_token>

Response:

{
  "data": [ { "objectId": "ifc-guid1", "statusActionId": "<action_id>", "value": "Completed", "valueDate": "2026-07-28T10:00:00Z" } ],
  "hasMore": true,
  "nextCursor": "3f2504e0-4f89-41d3-9a0c-0305e82c3301#638123456780000000#42",
  "first": "https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/statusevents/page?statusActionId=<action_id>&pageSize=1000",
  "self": "https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/statusevents/page?statusActionId=<action_id>&pageSize=1000",
  "next": "https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/statusevents/page?statusActionId=<action_id>&pageSize=1000&cursor=3f2504e0-4f89-41d3-9a0c-0305e82c3301%23638123456780000000%2342"
}

Keep following the next link (or pass nextCursor back in as cursor) until hasMore is false — that's the end of the result set. pageSize outside the 1,000–10,000 range returns 400 Bad Request.

Error responses

Access failures (license, project membership, organization, group access, blocked actions) and the status-event limit return a JSON ErrorResponse with four fields. Validation failures (400 Bad Request) return a plain error message instead, and a status action or custom status value that doesn't exist returns 404 Not Found.

{
  "errorType": "READ_ACCESS_ERROR_TYPE",
  "message": "A different license is required to access this feature. Upgrade your license to unlock this feature and maximize the benefits of Trimble Connect.",
  "tooltip": "Upgrade to unlock feature",
  "actionMessage": "Upgrade today"
}

GET /statusapi/1.0/license/{projectId} is special: it returns 200 OK with an empty ErrorResponse (all fields blank) when the caller has full access, and 200 OK with a populated ErrorResponse when access is restricted — check errorType, not the status code.

errorType values

The table below lists the errorType values, with the exact message text clients should expect. License-related rows may also include tooltip and actionMessage as shown in the example above.