API BIMcollab Twin Quickstart

API BIMcollab Twin Quickstart

This article provides a quick start description of the BIMcollab Twin Public API. With the BIMcollab Twin API you can access information about documents like metadata, and/or download them. Also you can access and create 'to do’s' via the API.

Detailed documentation about our API is available at  https://api.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  support@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).

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)

Authorisation endpoint   – https://api.bimlink.nl/connect/authorize
  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.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)
Info
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.bimlink.nl/domainaccounts/{domainAccountId}/. The following action returns the available domain accounts for the user:  https://api.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.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.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.


    • Related Articles

    • Integrations for BIMcollab Twin

      It is possible to seamlessly link your information stored on BIMcollab Twin to a number of other applications and platforms. Thanks to our Open API, this enables you to work many of your favourite apps within your preferred linked ecosystem. This ...

    • 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 ...

    • System Requirements BIMcollab Twin

      BIMcollab Twin The BIMcollab web application runs on any modern web browser which supports TLS 1.2 or a later version. The following clients are known to be unable to use TLS 1.2. You cannot use these clients for access to the service. Android 4.3 ...

    • 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 document coordination processes within a project into an automatic sequence of tasks. They can be added at either location, project or project phase level by the space administrator who is also ...