Getting Started

Setting up your account

  1. Create an API Account and confirm your email address.

  2. Sign in and go to the Products page.

  3. Select the 'Mapiq Public API' and Subscribe to a new subscription. Use your organization's name for this.

  4. Now we will confirm your subscription manually. The state of your subscription will be 'Submitted'.

  5. You'll receive an email when we've confirmed your subscription. The state of your subscription will now be 'Active'.

  6. You can find your API keys on your Profile page.

  7. Find all the details of the API on the API Reference page, where you can try out requests in your browser.

‍ If you run into any issues or need any help — contact our support and we'll get you up and running.

Authentication

The Mapiq API supports OAuth 2.0 Resource Owner Password Credential (ROPC) flow in order to retrieve a token that can be used to authenticate yourself against the public API. Mapiq will create a service account and provide the necessary information that you need to connect successfully.

Route

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

Required headers

  • content-type

    • application/x-www-form-urlencoded

  • mapiq-api-key

    • A key that will be issued per customer/service account.

Body

  • client_id

    • Unique identifier for your connection to the API (provided by Mapiq).

  • scope

    • openid https://mapiqprod.onmicrosoft.com/api/shifts/Default

  • username

    • Username of your API service account (provided by Mapiq).

  • password

    • Password of your API service account (provided by Mapiq).

  • grant_type

    • password

  • response_type

    • token id_token

Response

After you have successfully retrieved a token from the endpoint., you can use the access_token to authenticate yourself against the public API. The token has the following properties:

  • Access_token

    • The access token you need to authenticate yourself against the public API

  • Token_type

    • Type of the token

  • expires_in

    • After how many seconds the token will expire.

  • id_token

Example

Picture

Example request

Example with a curl command to retrieve the authentication token.

curl --request POST \
--url 'https://api.mapiq.com/auth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--header 'mapiq-api-key: {Use subscription id}' \
  --data 'client_id={Provided by mapiq}' \
  --data 'scope=openid https://api.mapiq.com/Default offline_access' \
  --data 'username={Provided by Mapiq }' \
--data 'password={Provided by Mapiq }' \
--data grant_type=password \
--data 'response_type=token id_token'

Shift registrations

The endpoint to retrieve registrations. In the object there is some basic information pertaining the registration like:

  • The date of the registration.

  • Which user registered.

  • Which location in the building is registered.

All content is in the ‘application/json’ type.

Route

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

Required headers

  • Authorization

    • The access_token that you get from the ROPC flow

  • Mapiq-api-key

    • Provided by Mapiq

  • x-api-version

    • 2.0

Query parameters

  • startDate

    • Description: The start of the date range.

    • Format: Date (yyyy-MM- dd)

    • Required: Yes

  • endDate

    • Description: The end of the date range. If not provided it will equal startDate.

    • Format: Date (yyyy-MM- dd)

    • Required: No

  • userId

    • Description: The identifier used by Mapiq, if provided we will retrieve the registrations for that specific user.

    • Format: GUID

    • Required: No

  • buildingId

    • Description: The identifier used by Mapiq, if provided we will retrieve the registrations for that specific building.

    • Format: GUID

    • Required: No

Responses

Successful response

Return a list of registrations, with the items in the list having the following properties.

  • id

    • Nullable: No

    • Format: Guid

    • Description: Identifier for the registration.

  • userId

    • Nullable: No

    • Format: Guid

    • Description: Internal Mapiq identifier.

  • userExternalId

    • Nullable: Yes

    • Format: String

    • Description: External identifier, as used by the customer.

  • firstName

    • Nullable: Yes

    • Format: String

    • Description: First name of the user.

  • lastName

    • Nullable: Yes

    • Format: String

    • Description: Last name of the user.

  • email

    • Nullable: No

    • Format: String

    • Description: Email address of the user.

  • date

    • Nullable: No

    • Format: DateTime

    • Description: On which date the registration is valid.

  • nodeId

    • Nullable: No

    • Format: Guid

    • Description: Identifier of the location of the registration, can be areaId, floorId or buildingId.

  • areaId

    • Nullable: Yes

    • Format: Guid

    • Description: Identifier for the area the registration is in. Can be null depending on what level the registration is made.

  • floorId

    • Nullable: Yes

    • Format: Guid

    • Description: Identifier for which floor the registration is in. Can be null depending on what level the registration is made.

  • buildingId

    • Nullable: No

    • Format: Guid

    • Description: Identifier for which building the registration is in.

  • buildingName

    • Nullable: No

    • Format: String

    • Description: The name of the building the registration is in.

  • floorName

    • Nullable: Yes

    • Format: String

    • Description: The name of the floor.

  • areaName

    • Nullable: Yes

    • Format: String

    • Description: The name of the area.

Example successful response:
Picture

Bad response

When there is a server side validation error, the server will return a 400. Together with a body containing the details of what went wrong.

  • title

    • Format: String

    • Description: The title of the error.

  • status

    • Format:httpStatusCode

    • Description: The http status code.

  • errors

    • Format:List<KeyValuePair>

    • Description: A list of key value pair containing the errorKey and the errorValue.

Example bad response:
Picture

Rate limited

Currently on the API there is a rate limitation set up. We allow up to 20 request per 5 minutes. If you exceed this limitation an error response will be thrown.

Example rate limited response:
Picture
Mapiq logo

Go to mapiq.com