Webservice Documentation

Preparation

To be able to use the web service, you first need to set up a search profile. When saving the search profile, make sure that it is created with the "Cloud Connect" option:

If you do not see this option when saving your search profile, the web service has not yet been activated for your account. In this case, please contact our customer service at (kundenservice@ibau.de).

The ID of the search profile can be obtained from its URL, as shown in below example:

https://login.ibau.de/projects/21425/0

• After the search profile has been set up, it can only be accessed via the web service from the next day!
• New results can only be retrieved on the days that were activated when saving the search profile!
• When creating the search profile, you can specify on which days new results should be automatically pushed to the web service. Whether a search profile pushes to the web service can be identified by the green cloud icon next to the search profile name.

• By default, all new search profile results and any updates to these results are pushed to the web service on the days you have defined. If you only want the results once, without updates, you can select the "One-time delivery" option instead of "All updates" below. In this case, you will only receive the result once via the interface, when the result first matches your search profile, on the next available day you have selected for the transfer.
• The automatic pushing of results to the web service occurs up to once per day.
• In addition to the automatic pushing of results, Projects or Public Notices can also be manually pushed to the interface. This is explained in the next section. This allows you to make interesting Projects or Public Notices immediately available via the interface.

If you want a Project or an Public Notice to be available directly in the interface, you can proceed as follows:

• Go to one of your search profiles with the green cloud.
• Select the checkbox next to the Project or Public Notice that you want to make available directly in the interface.
• A cloud icon (Cloud Connect) will appear in the toolbar above the results list. Click on this icon:

• A green confirmation will briefly appear in the top-right corner, indicating that the entities have been successfully transferred to Cloud Connect.
• The selected Projects or Public Notices are now directly available in the web service under the previously selected search profile.

Environments

Depending on whether you are a customer of Infobau or Ibau, you need to use a different URL for the web service:

Product	Webservice-URL
Ibau Xplorer	https://api.login.ibau.de/
Infobau Xplorer	https://api.login.infobau-muenster.de
Greenprofi Xplorer	https://api.login.greenprofi.de

Login

To connect to the web service, you must first log in. This can be reached via the endpoint POST /login_check. Here, a request is made using the username and password of the provided user.

A successful access provides a JWT token and a refresh token. The former is required for any further contact with the interface. The latter is required to obtain a new token after the expiration of the current token.

A security cookie is required for concurrent access, as shown in below example.

Session management note: When testing the interface, please note that only one active session per user account is allowed. If you log in via the interface using a username and password, any existing browser session will be automatically terminated. The same applies in reverse: once you log in again in the browser, the existing API session will be terminated. This should be taken into account especially during development and testing activities.

The JWT is valid for one hour by default. If a longer session is needed, then the token can be renewed using the refresh token under POST /token/refresh as follows:

This query result is identical to the login query. Also, the refresh token is valid for 8 hours and is renewed with each call.

Fetching the data

There are three possible endpoints corresponding to the products available in Xplorer.

SearchProfile IDs are strictly tied to their respective endpoint (object type) and cannot be reused across different endpoints. If a SearchProfile is used with a mismatched endpoint, it will result in a "SearchProfile with given id not found" error, even if the ID itself exists.

Note: The objects available to you depend on your Ibau or Infobau framework agreement.

The data retrieval process takes place via one of the above-mentioned endpoints using the GET method, for example /web_service/all_pn_headers/. Bearing this in mind, the previously obtained JWT token and the ID of the previously created search profile are required. The token is passed using the Authorization header, and the search profile ID is provided using a GET parameter as follows:

If available, this query now provides the new information of your search profile. The record format can be selected by using the “Accept header” as shown below:

• Accept: application/xml
• Accept: application/json
• Accept: application/ld+json

For new integrations, we recommend using the application/json format, as this format is natively supported in most programming languages and integration platforms.

Project images can be retrieved via the projectFiles field within a project record.

The image URL is not provided as a fully public link but as a relative path within the API structure. Access is only possible with a valid authenticated API session.

The respective project must contain an entry in the field /root/hydra_member/projectFiles with the following file type: /root/hydra_member/projectFiles/file/fileType/code = PROJECT_IMAGE. Only in this case does a project image exist.

The actual download path is located at /root/hydra_member/projectFiles/file/url. This relative path must be combined with the API base URL.

When this URL is called within a valid API session, the endpoint directly returns the image as the response.

Note: Image information should be processed directly when retrieving a project. It is recommended to check whether projectFiles is filled and whether an entry of type PROJECT_IMAGE exists.

Records are available in the interface for a total of 35 days after being transferred to the web service via a search profile. After this period, the data is automatically removed. If the data is still required, it must be pushed again into the interface via a corresponding search profile.

A description of the data fields for the various object types, along with examples in JSON format, can be found further down in this documentation.

If you do not provide a valid search profile ID, you will receive an error message along with the available search profile IDs for this object type:

Direct backlinks to the Xplorer can be generated for all records. The link is constructed using the respective ID of the record. It is important to use the correct base URL and the appropriate endpoint for the respective data structure.

The respective ID always comes from the corresponding API endpoint of the respective data structure.

Confirmation of Pickup

The web service provides records of your search profile and remembers previous record retrieves. By default, 10 or 20 records (Projects or Public Notices) per call are provided from the above-mentioned endpoints. Two ways are available to retrieve the next 10 or 20 records as explained below:

The next 20 records can be retrieved by using the endpoint POST /web_service/acknowledge/. Search profile ID and the IDs of confirmed records are required in the JSON object as shown below. This method minimizes the risk of losing records in the retrieval process.