Migrate from v1 to v2

In March 2023, we have released a new version of our Mapiq API. The Mapiq API v2 offers some great new features and enhancements compared to the older v1 API. This guide will help you to find out if actions are required and will take you through all of the changes you'll need to make to get your integration working with the v2 API.

Is my integration affected by this change?

This guide is intended for developers that have built an integration with our v1 API. You are using v1 if the API endpoints you call do not have the v2 prefix and if you are authenticating using the token endpoint on our api.mapiq.com domain.

To know if your integration is impacted, check if you are using any of the following API endpoints:

1. https://api.mapiq.com/auth/token

2. https://api.mapiq.com/shifts/users

3. https://api.mapiq.com/shifts/registrations

4. https://api.mapiq.com/shifts/buildings

5. https://api.mapiq.com/localization/admin/checkin/events

6. https://api.mapiq.com/localization/admin/checkin/statuses

7. https://api.mapiq.com/localization/admin/checkin

8. https://api.mapiq.com/parkinglots

9. https://api.mapiq.com/parkingReservations

Are you using one or more of the above endpoints? Then you will need to update your integration to use our v2 API.

Why and when should I upgrade to v2?

Our v2 API was redesigned from the ground up to make it easier for developers to use. Documentation on our API endpoints improved significantly, and we have switched to a new authentication scheme that is more in line with the industry standard. This should make it easier for developers to work with our new API. New features (like the ability to ingest occupancy data) will not be made available in v1.

You can keep using v1 for a while, but we strongly encourage you to upgrade to v2 as soon as possible. We will officially retire v1 in June 2023. This means that integrations that are still using v1 of our API may stop working at June 1st, 2023.

What changed?

Besides new functionality, v2 of our API also contains some breaking changes compared to v1.

Authentication

We have switched from the OAuth v2.0 ROPC (username/password) grant flow in v1 to the OAuth v2.0 client credentials grant flow in v2, which is the industry standard for authenticating as an application. Moreover, we have introduced a more fine-grained permissions system, that will allow you as a developer to better control the permissions that your application has when accessing your subscription data in our API.

To find out details on how to migrate your integration with our API to use the new authentication method, check out this step-by-step guide.

From shift registrations to workdays and workspace reservations

Mapiq is moving to a new, flexible booking concept that allows users to seamlessly book everything needed for their workday: workspaces, meeting rooms and parking spots.

To enable this product update, we’re introducing several new API endpoints: a workspace reservations endpoint and a workdays endpoint.

If you have been using the shifts registrations resource in our v1 API, you have two options for migrating: the workdays and the workspace reservations resource.

Workdays

The workdays resource in v2 is the recommended way to get insight in who is at the office at a certain day. This new endpoint will allow you to request, for a given range of dates, the workday status of Mapiq users in your subscription. A workday status of a user on a certain day indicates whether that user is working at the office, working remotely, or not working at all.

When to use this resource?

We recommend that you use this endpoint for use cases where it is important to know who has indicated to be in the building at a certain day.

Example use cases

• An integration with an access management system, in which you allow employees access to your building only if they have indicated to have an office day.

• An integration that automatically creates attendance reports for catering purposes or reimbursement tools for costs incurred by working from home or travel allowances.

Workspace reservations

The workspace reservations resource in v2 is replacing the shift registrations that was available in v1. You should use the workspace reservations endpoint if you want to know what workspace (desk) users in your subscription have booked.

When to use this resource?

We recommend that you use this endpoint in case you need to know the usage of your workspaces and if you want to know which workspaces is booked by whom.

Example use cases

• An integration that automatically generates a report of desks that require cleaning, based on which desks have been booked that day.

• An integration that performs analysis on workspace usage.

Other changes

Parking lots and buildings data (Spaces)

Data returned by the parking-lots and buildings resources do not contain unpublished changes anymore. All parking lots and buildings returned by this endpoint in v2 will now always reflect the status of the currently published spaces. We standardized the name of certain fields used in both Parking Lots and Buildings. We have also removed some properties that are not relevant for these resources.

Check-in events and statuses (UserLocations)

Data returned by the UserLocations resources check-in events and check-in statuses have a slightly different JSON representation to make them more in line with our other endpoints.

How to migrate?

Follow the steps below to migrate your app from v1 to v2.

1. Update your authentication

API key is no longer required

Our v1 API is using API keys as part of the authentication process. When calling one of our v1 endpoints, you had to pass the mapiq-api-key in the request headers. In our v2 version, this is no longer required.

Switching from ROPC grant to Client Credentials grant

The v1 API uses OAuth v2.0 with the Resource Owner Password Credentials (ROPC) grant to authenticate. We are still using OAuth v2.0 in our v2 API, but we have now switched to the Client Credentials grant (the OAuth standard for client authentication).

To retrieve a token using this grant, you will need to obtain a client credential in the form of a client_id and a client_secret. Mapiq will provide a client application and provide the necessary information that you need to connect successfully.

Note: the username and password that you used to retrieve tokens in v1 does not work in v2. The client_id and client_secret is replacing the username and password.

Route

POST https://account.mapiq.com/api/public/oauth2/token

Required headers

• content-type

  • Required, always: application/x-www-form-urlencoded

Request form parameters

• grant_type

  • Required, always: client_credentials

• scope

  • Required, always: https://api.mapiq.com/public/.default

• client_id

  • Required, the id of your Mapiq API client application (provided by Mapiq)

• client_secret

  • Required, the secret of your Mapiq API client application (provided by Mapiq)

Use the access_token from the reponse as a Bearer token when calling our API endpoints. Check out our new Getting Started guide to find more information on the authentication method used in v2.

2. Update your endpoints

We have made several changes in v2 in the endpoints compared to v1. In the table below, you will find a summary of all endpoints that were available in v1 and their corresponding endpoint in v2.

For a complete overview of all endpoints in v2, and their specification, please check out our API Reference.

In most cases, the new endpoint returns data in a JSON representation that is very similar to the v1 version. There may be some subtle rename changes.

A more important change is that the reservations endpoints in v2 are returning reservations that contain a startTime and endTime, instead of the single date property in v1. This is to support future product updates that make it possible for a user to have multiple reservations on the same day, for different facilities.