The Mapiq app already has powerful tools to give proper insights in your office capacity and daily occupancy. Many administrators, however, love to do more with the data and find that they can't manage everything directly from within the app. For this Mapiq provides an API that can be leveraged for more in-depth analysis. Many customers are happily using the API, but setting it up sometimes is slightly complex. In this FAQ we'll address a few causes and the associated resolution.

Causes

As mentioned in the introduction, customers face some difficulties when gaining access to the Mapiq API. The most common are listed below:

1. You have no service account
2. Unauthorized (401 error) on the server
3. Missing query parameters

You have no service account

In other documentation (e.g. Getting started with the Mapiq API, Mapiq API) it is explained that customers that want to use the Mapiq API need to register yourself on developer.mapiq.com. In some cases, customers think by doing so they automatically have access to the API. That is not the case. It is simply the first step in the chain. Find the resolution below.

Unauthorized (401 error) on the server

When getting started users follow along with the Getting Started steps outlined on https://developer.mapiq.com/ . In these steps, however, new users of the API often miss the fact that access is based on a OAuth 2.0 Resource Owner Password Credential (ROPC) flow. This flow retrieves a token that can be used to authenticate on the Mapiq API. This means that the token type is a bearer token. The bearer token is often missed, and thus not specified. By not specifying, users run into a 401 message.

Missing query parameters

In some API calls that can be made, it is required to add certain query parameters. You are informed on this, but new users often oversee this fact.

Trying it yourself is missing information

You can try the API calls on developer.mapiq.com yourself. To do so, it is required to already have an active account. The same API is called upon as in the production environment.

Resolution

You can find the resolution per case below in under their respective chapter.

You have no service account - resolution

After creating an account on developer.mapiq.com the next step is to submit an access request. To do so follow the next steps:

1. Log in on developer.mapiq.com 
2. Go to Products >> Mapiq Public API
3. Under Your subscriptions you'll find an empty text box, fill in a descriptive name and press Subscribe. Ideally, this contains the customer name and the purpose of the integration. For example, Mapiq - Wi-Fi integration.

After submitting this request a series of events occur in the background. Mapiq Support is notified and reaches out to you. In this process a few things are verified (e.g. Are you a valid requester? Are you a 3rd party? Determine the API owner?). After the verification Mapiq creates a service account that links to your environment and activates the subscription request. Mapiq Support gets back to you and shares the credentials of the service account and some steps to get started.

Unauthorized (401 error) on the server - resolution

When getting a 401 error often the bearer indication is missing in the header of the API call(s). The headers used after the token authorization call has been successful are the same for all the subsequent calls. Copy the header information below and adjust {token_response} by the token you retrieved by calling upon the authorization call and {api_key} by your own API key.

curl --request GET \
  --url https://api.mapiq.com/shifts/buildings \
  --header 'Authorization: bearer {token_reponse}' \
  --header 'mapiq-api-key: {api_key}' \
  --header 'x-api-version: 2.0'

Missing query parameters - resolution

Find a full overview of the API calls in the article Mapiq API. In this article the required query parameters are listed.

Trying it yourself is missing information - resolution

As explained in the cause of this issue, trying it yourself is possible, but for this it is required you first go through the process of requesting a service account and having this activated. After receiving this information, you can start trying it yourself from within the browser.