API Reference

Overview

This page will help you get started with Qminder API.

Welcome to Qminder's API documentation!

Developers can use Qminder's API to integrate applications with Qminder, such as internal backend systems, CRMs and more.

In order to make simple integrations between services without writing code, it is possible to use the Zapier integration.

Library

In order to simplify integration with Qminder's platform, it is possible to use an official Javascript / TypeScript software library. Qminder's official library is tested and used by the team every day.


REST API

The Qminder API is a HTTP REST API. It is possible to connect to the Qminder API with any programming environment that supports sending HTTP requests. Read more about how to connect to REST APIs.

The Qminder API is available at the following URL:

https://api.qminder.com/v1/

Note that the API can only be used with HTTPS (encrypted HTTP). The API cannot be used with regular HTTP (unencrypted) connections.


What you can do with the API

With the Qminder REST API, it is possible to solve these common business problems:

  • Adding visitors to queue, editing the details (using the Tickets API)
  • Managing service lines in a location, enabling and disabling lines (using the Lines API)
  • Managing user access and automatically sending invites to new employees (using the Users API)

Qminder Webhooks

Using webhooks with the Qminder platform, it is possible to integrate your application by registering a webhook listener. This webhook listener will be notified with a HTTP POST request when events occur in the Qminder platform.


Premium support

Premium API support is available if your company is on the Enterprise plan of Qminder. Your developers can contact Qminder support and receive help from the people who created Qminder.

Contact Qminder support to receive more information on how to get support for your API questions.


Authorization

In order to authorize your code to the Qminder API, an API key is required.

Here's how to create the API key in Qminder Dashboard:


Making a request

Qminder API uses two common data exchange formats: JSON and standard URL forms. API calls expect requests to be formatted with the application/x-www-form-urlencoded format, and reply with JSON data, unless specified otherwise in the API method documentation.

In order to call the Qminder API, the API key has to be provided.

The API key can be provided as a HTTP request header or as a query string parameter.

It is recommended to send the API key as a HTTP request header.

Here's how to use the cURL command line tool to send an API call:

curl https://api.qminder.com/v1/locations/ -H "X-Qminder-REST-API-Key: KEY"

As an alternative, here is how to specify the Qminder API key as a query string parameter:

curl https://api.qminder.com/v1/locations/?rest-api-key=KEY


Response

The Qminder API responds to HTTP requests with the correct HTTP status codes.

When the HTTP request succeeds, the HTTP status code will be between 200 and 299.

When the HTTP request fails, the HTTP status code will be between 400 and 599.

API calls also return the HTTP status code in the JSON data to make it easier to extract.

Here is an example HTTP response (Ticket Details API call)

{
  "statusCode": 200,
  "id": "42367593",
  "status": "NEW",
  "source": "MANUAL",
  "line": 102321,
  "firstName": "Mari",
  "lastName": "Müür",
  "created": {
    "date": "2018-12-31T13:53:19.243Z"
  }
}

If an error occurs, Qminder will send a HTTP status code indicating the error and also include a message. Optionally, a developer friendly message will be included as well.

{
  "statusCode": 401,
  "message": "Please authenticate",
  "developerMessage": "Set X-Qminder-REST-API-Key HTTP header with API key"
}

API rate limits

The Qminder API is rate limited in order to prevent abuse and ensure that every customer can access the Qminder API. Please design your integration to work within the API rate limits.

Rate limit: 5 requests per second per user / API key

Here is how the rate limits work:

All API calls count against the rate limit.
The algorithm used for rate limiting is the token bucket algorithm. The capacity of the bucket (the burst size) is 40 requests, the replenish rate for the bucket (the average rate) is 10 per second.

The Qminder API sends a HTTP response header for the amount of API calls remaining: X-Ratelimit-Remaining. This HTTP header can be used to determine how much of the rate limit has been used.

Reaching the rate limit will block access to the API (for the given API key) until the rate limit replenishes. When the limit has been reached, the value of the X-Ratelimit-Remaining header will be -1 and all responses will return an HTTP response status of 429.

It is possible to request a rate limit increase from Qminder by contacting support.