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 "Web Service" option:

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

https://login.xplorer.ch/projects/21425/0

• After setting up the search profile, values can be retrieved if the web service option is selected. The retrieval process will start the next day.
• New results can only be retrieved from selected days.

Environments

Login

To connect to the web service, you must first log in. This can be achieved under the endpoint POST /login_check. Refer to below example:

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 two 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 Baublatt 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.

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 Tenders) per call are provided from the above-mentioned endpoints. Two ways are available to retrieve the next 20 records as explained below:

If you do not want to call another endpoint, data retrieval can be confirmed by using the X-AUTO-ACK header as shown 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.