API BIMcollab Twin Quickstart

API BIMcollab Twin Quickstart

This document aims to provide a human-friendly quick start description of the BIMcollab Twin Public API . Detailed documentation about our API is available at  https://api.demo-bimlink.nl/swagger . To gain access to our API and the documentation you need a BIMcollab Twin account. To use the BIMcollab Twin Public API from your application you need client credentials and have your redirect URL white listed at our authentication server. If you want to make use of our API, please contact us at  docsdevelopment@bimcollab.com . All endpoints on this page use the domain of our demo server (demo-bimlink.nl) for testing purposes. To request real costumer data, use our live server (bimlink.nl).

Navigating BIMcollab Twin Public API

Step 1: Authorising

Each request to the API needs to be authenticated using an access token, in most cases an access token will be obtained by using the   OAUTH2 Authorization Code flow. Basically, this means the user needs to be redirected to the BIMcollab Twin login page from your application and will be redirected back to your application after authorisation was successful. With the obtained authorisation token an access token can then be requested. The access token can then be added to the “Authorization” header of your requests in the format: “Bearer <accesstoken>”. Tokens are provided in   JWT   format, so when decoded (Base64) they provide more information like expiration time and a unique user-id. We suggest requesting and using a refresh token. This way a user only has to authenticate with BIMcollab Twin once.

Available scopes
  1. bimlink_publicapi – Required to access the  BIMcollab Twin  Public API
  2. offline_access – Required to use refresh tokens
  3. openid – Adds an ID token to the token response
  4. email – Adds the users email to the ID token (only valid when openid is also requested)

  1. The redirect URL should be whitelisted by our authentication server
  2. A state value can be provided to prevent cross-site request forgery

Access token endpoint  –  https://api.demo-bimlink.nl/connect/token

  1. Expiration time is available in the access token.
  2. Contains a refresh token when the user granted the offline_access scope

Refresh token endpoint  –  https://api.demo-bimlink.nl/connect/token

  1. Provides a new access token
  2. Sliding expiration so the lifetime of the refresh token is reset each time a new access token is requested
  3. Should be requested in a POST request with the data in the body (Content-Type: application/x-www-form-urlencoded)
The data responded by the actions is always specific for the current user (the user where the access token was created for). Never use access tokens for a global purpose because the API returns only data which the user is allowed to view and potentially not the complete data set. The scope and permissions of each user are managed in the BIMcollab Twin by the account administrator. For example: GET Locations for a domain account only returns locations the user can view. If the same request is done using another access token which belongs another user the response can contain completely different data.

Step 2: Selecting a domain account

All requests except one (listing the available domain accounts for a user) require a DomainAccountId. A domain account is a corporate account and it holds all data for a certain company or a very big project. Before you can send a API request you will first have to provide a menu to allow the user to select a domain account. We suggest saving the selected domain account, because many users only use one domain account for a long time. In the actual request the domain account can be selected as follows: https://api.demo-bimlink.nl/domainaccounts/{domainAccountId}/. The following action returns the available domain accounts for the user:  https://api.demo-bimlink.nl/swagger/index.html#/DomainAccounts/DomainAccounts_GetAll

Step 3: Selecting a project phase

Many API requests also require a ProjectPhaseId, because data within an account is organised in a structure of locations, projects and project-phases. So for most applications the next step after authentication and and selecting a domain account will be to show a project selection menu, so the user can select a domain account and a project-phase. The following action returns the BIMcollab Twin project structure for a domain account:  https://api.test-bimlink.nl/swagger/index.html#/Locations/Locations_GetAll

Step 4: Selecting a storey

BIMcollab Twin also provides a spatial structure to organise data within a project phase. Especially when requesting BIM data it is advised to allow the user to select a specific storey by creating a spatial selection menu. Note: the spatial structure entities (SpatialStructureElement) does not contain actual BIM data, for more information see “BIM data”. The following action returns the BIMcollab Twin spatial structure for a project phase:  https://api.demo-bimlink.nl/swagger/index.html#/SpatialStructureElements/SpatialStructureElements_GetAll

Pagination

API GET actions where the response is expected to hold a large amount of objects are paginated. Pagination is controlled by sending a limit (maximum number of objects) and an offset (number of objects to skip) in the querystring of your request. The maximum value of limit depends on the action and can be found in the Swagger documentation. Pagination meta-data also be found in the headers of the response: Pagination-Limit, Pagination-Offset, Pagination-Result.

BIM data

The BIM data in BIMcollab Twin is mostly imported from IFC or Revit. The data is represented by the following entities:

Element

ElementType

  1. Represents a family of elements
  2. Contains (when included)
  3. Parameters that apply to all Elements of this type
  4. Geometric data
  5. Materials
  6. Like: IfcElementType
  7. Endpoint:   https://api.demo-bimlink.nl/swagger/index.html#/ElementTypes

Parameter

  1. Contains information about the containing object
  2. Like: IfcProperty or IfcQuantity
  3. Endpoint:  https://api.demo-bimlink.nl/swagger/index.html#/Parameters

    • Related Articles

    • BIMcollab Twin Feature Overview

      BIMcollab Twin offers model-based document and asset management to store, manage and share building and infrastructure data. A Digital Twin platform to create and work together on data and to easily involve stakeholders. Explore our latest features ...

    • Power BI Connector BIMcollab Twin

      With our own Power BI connector, all data from BIMcollab Twin's building file can easily be read into Power BI. No technical knowledge is required to link Power BI and BIMcollab Twin. With this connector, BIMcollab Twin clients can easily develop ...

    • BIMcollab Twin Accounts

      Each account on BIMcollab Twin contains information from construction projects, stored in its own database, accessible to project participants. The accounts are accessible via their own web address, with their own subdomain: [account-URL].bimlink.nl. ...

    • Workflows in BIMcollab Twin

      Workflows are designed to translate the various processes within a project into an automatic workflow. A set workflow starts when a new document is posted that meets the predefined requirements. All workflows can be activated or deactivated from the ...

    • Get Started with BIMcollab Twin for Admins

      This Get Started guide describes the functionalities and configuration of your BIMcollab Twin space. It will get you up and running in no time. Your space has already been activated by our team. When ordering a space, you were asked to provide ...