This document aims to provide a human-friendly quick start description of the BIMlink 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 BIMlink account. To use the BIMlink 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@bimlink.nl. 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 BIMlink 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 BIMlink 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 BIMlink once.
Available scopes
- bimlink_publicapi – Required to access the BIMlink Public API
- offline_access – Required to use refresh tokens
- openid – Adds an ID token to the token response
- email – Adds the users email to the ID token (only valid when openid is also requested)
Authorisation endpoint – https://api.demo-bimlink.nl/connect/authorize
- The redirect URL should be whitelisted by our authentication server
- A state value can be provided to prevent cross-site request forgery
Access token endpoint – https://api.demo-bimlink.nl/connect/token
- Expiration time is available in the access token.
- Contains a refresh token when the user granted the offline_access scope
Refresh token endpoint – https://api.demo-bimlink.nl/connect/token
- Provides a new access token
- Sliding expiration so the lifetime of the refresh token is reset each time a new access token is requested
- Should be requested in a POST request with the data in the body (Content-Type: application/x-www-form-urlencoded)
Note: 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 BIMlink 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 BIMlink project structure for a domain account: https://api.test-bimlink.nl/swagger/index.html#/Locations/Locations_GetAll
Step 4: Selecting a storey
BIMlink 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 BIMlink 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 BIMlink is mostly imported from IFC or Revit. The data is represented by the following entities:
Element
ElementType
Parameter
