1. Overview
Congrid Public API enables customers & third parties to integrate with the Congrid platform. Through the API you can access and manage different resources of the Congrid platform. The API provides an easy way to automate day-to-day tasks, such as creating a project and managing the base data of the project.
The API is a REST style API with JSON as the data format making it easy to approach with plenty of tooling available.
You’ll find detailed documentation for different API versions from Documentation. For a hands-on guide for using the Congrid Public API see Tutorial. The tutorial provides real-life use cases with actual example requests / responses. We will use curl during the tutorial for executing the requests.
Currently supported operations by the API are creating and configuring projects in the system.
1.1. Contact
Any questions, issues, suggestions etc please do not hesitate to contact us at
2. API Information
2.1. Current version
Currently the latest API version is v2. You should always use the latest public API version. For old API versions see All API Versions.
|
Note
|
The previous version v1 is still available, but will be deprecated 1.1.2020. |
2.2. Documentation
Detailed documentation for API end-points is available in
2.3. Media types
The API both consumes and produces data in the following formats:
application/json
2.4. All API Versions
Congrid public API sets version in end-point URL. There are two API versions available:
-
https://api.congrid.com/v1 (To be deprecated 1.1.2020)
New versions add more functionality and in rare cases cause backwards incompatibility. For more details see detailed version documentation or contact our support at support@congrid.com.
3. Tutorial
A short tutorial about using the API is available at
The tutorial explains how to create a project and fetch project related data. It contains source code and example requests and responses.
4. Authentication & Authorization
API requests are authenticated and authorized with a Authorization Token sent in HTTP headers. E.g.
Congrid-API-Token: c67714zxcvc8f866f762345595269ac119234568531f
Authorization Tokens are user account specific. Tokens are available for special API access accounts. The user accounts that have API-access enabled have access to ALL the projects of the customer.
There are two types of API users, namely full-access and read-only. The full-access API users are able to perform all the API operations that are available. The read-only API user can only read data through the API. The read-only user is a natural choice for third parties that require read access to the data, but do not need to be able to modify the data.
The API users are always enabled by Congrid admins. Thereafter the company admin users can obtain and change the API tokens from the user settings page:
5. Testing in Staging Environment
Congrid provides a staging environment to test your API implementation against the Congrid Public API before actual production use.
|
Note
|
Please note that the data in the staging environement is NOT guaranteed to stay intact but is subject to occasional resets with data from production environment. |
|
Note
|
The files, floor plans and photos are not replicated to the staging environment. Hence
for example all the entries returned by the /project/{projectId}/files end-point might not be downloadable.
At the moment it is not possible to generate new reports on the sandbox host.
|
The staging environment is located under:
And the API URL for the environment is:
Please ask Congrid to provide an account for you in the staging environment by contacting support@congrid.fi
6. Headers
| Name | Description | Direction |
|---|---|---|
Congrid-API-Token |
The API Token used for authentication and authorization of requests |
Request |
Congrid-Request-Id |
Generated by the API to help troubleshoot requests if there is need Please do NOT set this Header in the client application as it will be overwritten by the API. |
Response |
7. Users & Roles
Congrid system has to separate entities to handle user accounts and access rights.
-
Users define user accounts and information related to the user, such as name and email
-
Roles specify access rights for users
A User is something that is handled by Congrid system internally. Hence user objects
cannot be modified through the API.
A Role on the other hand is something that is used to grant (and remove) access rights for
different objects and actions in Congrid system.
The roles can be managed through AD. This requires mapping the project roles to AD groups. This can be done through the API projects end-point. Refer to AD configuration in API documentation for more details about the properties related AD to group mapping.
7.1. Removing a User
Removing or disabling a user in Congrid system essentially means removing all the roles from the user. The easiest way to perform this through the API is to fetch all the roles through the roles end-point and then one by one remove those roles.