Create an empty iModel


This quick start is intended to help you understand what an iModel is and how to leverage iTwin Platform iModels API for managing it.

By the end of this walk-through, you will be able to create an empty iModel using iModels API which later on can be used as a destination iModel for your synchronization workflow.


Skill level:



5 minutes


This tutorial assumes that you already have:

  • Project created and configured.

1. Register an Application

To build an application on the iTwin Platform, you will need to register a client.

Click the Register Application button on the right-hand side to automatically register a client for this quick start. You can find registered application in My apps page.

Optional: Manual Application registration process

To manually register a client:

  1. Go to
  2. Click the Sign In button and sign-in using your Bentley account credentials
    • If you have not already registered, click Register now and complete the registration process.
  3. Click on your user icon and navigate to the My Apps page
  4. Click the Register New button
  5. Give your application a Name
  6. Select the Data Management API
  7. Select application type SPA (Single Page Web Application)
  8. Enter Redirect URL
    • For this tutorial use https://localhost:3000
  9. Leave post logout redirect URIs empty.
  10. Click the Save button
Note the Client ID that is generated during the registration process. You will need this in a later step.

2. Get a token

To make request to API user token is needed. There are several ways to get it.

Implement Authorization Code Flow in the application

Follow this article to implement Authorization code workflow in your application.

Here you can use Client ID generated from previous registration step.

Grab a user token from Api reference “Try it” Section

  1. Go to Create Connection - Synchronization
  2. Click “Try it” button.
  3. On Authorization section select “AuthorizationCode”.
  4. After popup closes Authorization header with your user token value should be visible.
  5. Save user token value for this tutorial.
Use user token to replace JWT_TOKEN dynamic parameter in the next steps.

3. Create an empty iModel

An iModel is a specialized information container for exchanging data associated with the lifecycle of infrastructure assets. iModels were created to facilitate the sharing and distribution of information regardless of the source and format of the information.

iTwin Platform iModels API is based on iModelHub cloud service which enables alignment, accountability and accessibility of infrastructure digital twins. It is the control center for iModels and is responsible for coordinating concurrent access to iModels as well as changes made to them.

An empty iModel is created by sending a HTTP POST message to endpoint with the payload describing the iModel to be created.

There are two required properties for the create iModel payload.

name - iModel name is required which uniquely identifies the iModel within the Project.
projectId - provides Project identifier that created iModel will belong to. Project identifier is required property.
description - free form text field so you could give more information about the iModel.
extent - iModels usually are placed at some location on the Earth. This property allows to specify the maximum rectangular area on the Earth which encloses the iModel. The maximum extent is used to help keep your iModel clean. When new elements are imported, those outside the extent will be flagged for further processing. This extent will also help to zoom to the area of interest in web viewers.

Note: please replace dynamic parameters (JWT_TOKEN and PROJECT_ID) with relevant values from previous steps.

You can execute the request in Create iModel documentation page, “Try it” section.

Since an empty iModel does not contain any graphical elements or any data it cannot be opened yet for viewing. In order to bring data to the created iModel you may setup synchronization connection which will transform engineering data from native design formats to iModel. Once the synchronization has been setup and executed, viewing session can be started.

Request Syntax

1 GET HTTP/1.1

Request Headers

1 2 3 Accept: application/json Authorization: Bearer JWT_TOKEN Content-Type: application/json

Request Body

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 { "projectId": "PROJECT_ID", "name": "Sun City Renewable-energy Plant", "description": "Overall model of solar farms in Sun City", "extent": { "southWest": { "latitude": 46.13267702834806, "longitude": 7.672120009938448 }, "northEast": { "latitude": 46.302763954781234, "longitude": 7.835541640797823 } } }

Response Headers

1 2 Content-Type: application/json Location:

Response Body

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 { "iModel": { "id": "5e19bee0-3aea-4355-a9f0-c6df9989ee7d", "displayName": "Sun City Renewable-energy Plant", "name": "Sun City Renewable-energy Plant", "description": "Overall model of wind and solar farms in Sun City", "initialized": true, "createdDateTime": "2020-10-20T10:51:33.1700000Z", "projectId": "PROJECT_ID", "extent": { "southWest": { "latitude": 46.13267702834806, "longitude": 7.672120009938448 }, "northEast": { "latitude": 46.302763954781234, "longitude": 7.835541640797823 } }, "_links": { "creator": { "href": "" } } } }

More resources that you may like

Data Management API documentation

An overview and detailed Data Management API documentation.

Overview of iModel

An overview of iModel data structure.