Known limitations and FAQ for BIMcollab developers

This article collects the known limitations of the BIMcollab APIs, the BIMcollab SDK, and file specifications, and answers the questions developers ask most often. Each answer links to the article for more details.

💡 Tip: Starting a new integration? Read BIMcollab developers options overview first.

Known limitations

General

Limitation	What to do instead
Only the authorization code flow is supported. A user must sign in, and your application only sees the data that this user can see.	For server applications, request a non-expiring refresh token. See Server-to-server integrations with non-expiring refresh tokens.
Standard refresh tokens expire after 15 days without use, and after 30 days at most.	Ask the user to sign in again, or request a non-expiring refresh token for a server application.
`GET` requests have rate limits: 100 per second, 5,000 per minute, and 50,000 per 30 minutes.	Handle `429 Too Many Requests` with a wait-and-retry approach. See Rate limits and handling HTTP 429.

Connection API

Limitation	What to do instead
The document and event services of the BCF-API standard aren't supported. Requests return empty data.	Use the Documents API for files, and the activity logs for the history of a project. See Connection API behavior compared to the BCF-API standard.
Only the first viewpoint of an issue and viewpoints linked to a comment are visible to users.	Add a comment for every viewpoint you upload. See Working with viewpoints and comments in the Connection API.
The project extensions (allowed types, statuses, custom fields, and other values) can't be changed with the API.	Change them manually on the settings page of the BIMcollab project.
There are no webhooks or push notifications when issues change.	Check for changes regularly with the modification dates. See Connection API behavior compared to the BCF-API standard.

Documents API

Limitation	What to do instead
You can only upload documents to a project or a project phase.	Choose the project or project phase that the document belongs to. See Uploading documents with the Documents API.
Requests for a list fail without the `limit` parameter.	Always add `limit`, for example `limit=100`.
The API covers the most common actions of the document management system, not all of them.	Check the available endpoints in the Swagger reference. See Getting started with the Documents API.
You can't publish model files in the WebViewer with the API.	Publish the model manually in BIMcollab.

BIMcollab SDK (Connector with full GUI)

Limitation	What to do instead
The Connector only works on Windows, in applications that can host a .NET Framework 4.8 user control.	For other platforms, use the Connection API and build your own interface.
The Connector works online only.	An offline workflow with BCF files is available on request.
The generic developer token only connects to the Playground.	Request an app token for your application. See SDK Connector with full GUI: overview and requirements.

Frequently asked questions

Getting started

Which developer option should I use?
It depends on what you want to build. Use the Connection API for issues, the Documents API for files, the SDK for a ready-made issue interface in a Windows application, and .bcsv file specifications to create Smart Views. See BIMcollab developers options overview.
Where can I test my integration?
On the Playground, our development space. To get access, apply for a developer account. See Developing on the Playground and moving to production.
How do I get client credentials for my own space?
Send an email to [email protected] with the type of implementation (private or commercial), your callback URL, and the BIMcollab spaces to connect. See Developing on the Playground

Authentication

What's the difference between client credentials and my BIMcollab account?
Client credentials (Client ID and client secret) identify your application. The BIMcollab account identifies the user who signs in. Your application needs both, and it only sees the data that the user can see. See How to authenticate with the BIMcollab API.
How do I make users sign in again, for example to switch accounts?
Add prompt=login to the authorization request. The sign-in page then asks for the user's credentials, even if they are already signed in.
What is my space ID?
On the Playground, the space ID is 8e3136c4-2e93-4819-a44e-227c59de8f02. For your own space, you receive it with your client credentials. Only the Documents API needs it. See Getting started with the Documents API.

Connection API

Why can't users see a viewpoint I uploaded?
In BIMcollab, extra viewpoints are only visible when a comment refers to them. Add a comment with the viewpoint_guid of the viewpoint. See Working with viewpoints and comments in the Connection API.
How do I find out which issues changed since my last sync?
Check two dates on each issue: modified_date for changes to the issue, and comments_modified_date for new or changed comments. See Connection API behavior compared to the BCF-API standard.
Why does my request for logs fail?
Logs need the data_analysis scope in your access token, and use version 2.0.0 in the URL instead of bc_2.1. User access logs are only available for Administrators on spaces with an Enterprise plan. See Retrieving activity logs and user access logs.

Documents API

Why does my request return 400 Bad request?
The most common cause is a missing limit parameter on a request for a list. Add limit, for example limit=100. See Getting started with the Documents API.
How do I get only the documents that changed?
Add the newVersionSinceDateTime filter to the request for documents. It only returns documents with a new version since that date and time. See Getting started with the Documents API.

BIMcollab SDK

How do I get the SDK package?
Apply as a BIMcollab developer, and request the SDK package in your application. See SDK Connector with full GUI: overview and requirements.
How do I get an app token for my application?
Test your application on the Playground with the generic developer token. Then send a recording of your application working with the Connector on the Playground to [email protected]. After a successful test, you receive your app token. See SDK Connector with full GUI: overview and requirements.
Why are all controls in the BCF Manager disabled?
Your application hasn't called the Initialize() method of the user control yet. See Getting started with the SDK Connector: implementing the AppInterface.

Still have questions?

Send an email to [email protected].