mQuest API (v1)

The mQuest API is a collection of RESTful JSON endpoints with which you can automate the management of your mQuest projects.

This API reference includes all technical documentation developers need to integrate third-party applications and platforms.

Conventions used in this API

The HTTP-headers which are used within the API-Calls are case-insensitive. We follow the W3C standard for HTTP Message (W3C RFC 2616).

Quick Start Guide

For developers eager to hit the ground running with the mQuest API, here are 3 quick steps to make your first call with the API.

  1. Request a tenant and an API-Key at support@mquest.de

  2. Make a test call using your key. You may use the code examples provided below to make a test call with your programming language of choice. This example fetches all users for your tenant. Be sure to replace the tenant and the API Key in sample code with your own and use API domain teststage.mquest.de if testing with our teststage.mquest.de environment.

  3. Implement your application. Now that you've confirmed your API Key is working, get familiar with the API by reading the rest of this API Reference and commence building your application.

View Quick Start Code Examples
cURL command line
  curl -X GET \
    -H 'X-Api-Key: Yjc5MmIDRh.eyJ0ZW5hbnQi9jYWwifQ==.bK5VIdH-CgzN8qgLZalfzltFmNCKH1FtmLQMfL9Jy_pDg==' \
    -H 'Content-Type: application/json' \
    https://teststage.mquest.de/qs/staging/api/v1/users/
Node.js
  const request = require("request");

  const options = {
    method: 'GET',
    url: 'https://teststage.mquest.de/qs/staging/api/v1/users/',
    headers: {
      'X-Api-Key': 'Yjc5MmIDRh.eyJ0ZW5hbnQi9jYWwifQ==.bK5VIdH-CgzN8qgLZalfzltFmNCKH1FtmLQMfL9Jy_pDg==',
      'Content-Type': 'application/json'
    }
  };

  request(options, function (error, response, body) {
    if (error) {
      console.log('API call error:', error.message);
    } else {
      console.log('API call response:', body);
    }
  });
Python
  import requests

  url = "https://teststage.mquest.de/qs/staging/api/v1/users/"

  payload = ""
  headers = {
      'Content-Type': "application/json",
      'X-Api-Key': "Yjc5MmIDRh.eyJ0ZW5hbnQi9jYWwifQ==.bK5VIdH-CgzN8qgLZalfzltFmNCKH1FtmLQMfL9Jy_pDg==",
  }

  response = requests.request("GET", url, data=payload, headers=headers)

  print(response.text)
PHP
  $request = new HttpRequest();
  $request->setUrl('https://teststage.mquest.de/qs/staging/api/v1/users/');
  $request->setMethod(HTTP_METH_GET);

  $request->setHeaders(array(
    'X-Api-Key' => 'Yjc5MmIDRh.eyJ0ZW5hbnQi9jYWwifQ==.bK5VIdH-CgzN8qgLZalfzltFmNCKH1FtmLQMfL9Jy_pDg==',
    'Content-Type' => 'application/json'
  ));

  try {
    $response = $request->send();

    echo $response->getBody();
  } catch (HttpException $ex) {
    echo $ex;
  }
Java
  OkHttpClient client = new OkHttpClient();

  Request request = new Request.Builder()
    .url("https://teststage.mquest.de/qs/staging/api/v1/users/")
    .get()
    .addHeader("Content-Type", "application/json")
    .addHeader("X-Api-Key", "Yjc5MmIDRh.eyJ0ZW5hbnQi9jYWwifQ==.bK5VIdH-CgzN8qgLZalfzltFmNCKH1FtmLQMfL9Jy_pDg==")
    .build();

  Response response = client.newCall(request).execute();
C#
  var client = new RestClient("https://teststage.mquest.de/qs/staging/api/v1/users/");
  var request = new RestRequest(Method.GET);
  request.AddHeader("X-Api-Key", "Yjc5MmIDRh.eyJ0ZW5hbnQi9jYWwifQ==.bK5VIdH-CgzN8qgLZalfzltFmNCKH1FtmLQMfL9Jy_pDg==");
  request.AddHeader("Content-Type", "application/json");
  IRestResponse response = client.Execute(request);
Go
  package main

  import (
      "fmt"
      "net/http"
      "io/ioutil"
  )

  func main() {

      url := "https://teststage.mquest.de/qs/staging/api/v1/users/"

      req, _ := http.NewRequest("GET", url, nil)

      req.Header.Add("Content-Type", "application/json")
      req.Header.Add("X-Api-Key", "Yjc5MmIDRh.eyJ0ZW5hbnQi9jYWwifQ==.bK5VIdH-CgzN8qgLZalfzltFmNCKH1FtmLQMfL9Jy_pDg==")

      res, _ := http.DefaultClient.Do(req)

      defer res.Body.Close()
      body, _ := ioutil.ReadAll(res.Body)

      fmt.Println(res)
      fmt.Println(string(body))

  }

Base URI

The base URI for all endpoints is: https://{mQuest-host}/qs/{tenant}/api/{version}
It is continued by the endpoint of your operation. Expand the endpoint's path to see the request URL.

Host

The {mQuest-host} string depends on what server you are.
Example: "staging.mquest.de"

Tenant

The {tenant} (mandator) string is basically your cluetec customer ID.
Example: "default"

Version

The {version} refers to endpoint versioning. (It's an enum where most of the times "v1" is used.)
Example: "v1"

Authentication

All HTTP requests made against the mQuest API must be validated with an API Key.

Acquiring an API Key

If you don't have an API Key yet contact our support team to register for one.

Using Your API Key

You may use any server side programming language that can make HTTP requests to target the mQuest API. All requests should target the domain you've been assigned to and include your tenant in the url. E.g. https://qs3.mquest.de/qs/{tenant}

You can supply your API Key in REST API calls in one of two ways:

  1. Preferred method: Via a custom header named X-Api-Key
  2. Convenience method: Via a query string parameter named api_key

Header-API-Key

The authorization is granted with an api-key that is sent via custom header.

Security Scheme Type API Key
Header parameter name: X-Api-Key

Query-API-Key

The authorization is granted with an api-key that is sent as query parameter.

Security Scheme Type API Key
Query parameter name: api_key

Security Warning: It's important to secure your API Key against public access. The custom header option is strongly recommended over the querystring option for passing your API Key in a production environment

Errors

The API uses standard HTTP status codes to indicate the success or failure of an API call.

  • 400 (Bad Request) The server could not process the request, likely due to an invalid argument.
  • 401 (Unauthorized) Your request lacks valid authentication credentials, likely an issue with your API Key.
  • 403 (Forbidden) Your request was rejected due to a permission issue, likely a restriction on the API Key's associated permissions.
  • 500 (Internal Server Error) An unexpected server issue was encountered.

Projects

Get projects-list

Get a list of all projects for the specified tenant.

path Parameters
tenant
required
string [\w\d@\.\-_]{3,100}

See Tenant in the Base URI section.

version
required
string
Value: "v1"

The current version of the endpoint

query Parameters
sort
string
Example: sort=name,ASC

Specifies sorting of the requested list. Possible directions are ASC and DESC.

size
integer >= 1
Default: 20

Specifies the page size (how many elements will be contained in one page).

page
integer >= 1
Default: 1

Specifies the page number to be retrieved.

Responses

200

Load a list of all projects.

401

The server could not authenticate the request. Either the api-key is not correct or it wasn't provided in the request at all. Check if you have provided the correct api-key within the X-Api-Key header or as api_key query-parameter. See: Authentication

403

The api-key has not the required rights to perform the request on this resource.

get /projects
https://{mQuest-host}/qs/{tenant}/api/{version}/projects

Staging example

https://staging.mquest.de/qs/{tenant}/api/{version}/projects

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Create project

Create a new project.

path Parameters
tenant
required
string [\w\d@\.\-_]{3,100}

See Tenant in the Base URI section.

version
required
string
Value: "v1"

The current version of the endpoint

Request Body schema: multipart/form-data

The form parameters for a post request to create a new project.

name
string [A-Za-z0-9 -_\.]+

The name of the project.

mqf
file

The questionnaire (mqf) file

accounting_type
string
Enum: "TEST" "LIVE"

If you don't have a license for the project then this property will be null.

If you have a license for the project, then this property can either be :

  • TEST - Synchronize up to 30 datasets free of charge.
  • LIVE - Normal usage and every dataset gets charged.

The accounting-type can only be switched from TEST to LIVE. While changing, you can decide to keep the test datasets and get charged for them or else they will be deleted. Switching the accounting-type from LIVE to TEST is not possible.

online_available
boolean
Default: false

Whether the project should be available for online clients (mQuest DR).

offline_available
boolean
Default: true

Whether the project should be available for offline clients (iOS, Android).

multiple_online_participations_allowed
boolean
Default: false

Whether one user can participate multiple times in an online-project.

unpersonalized_offline_questioning_allowed
boolean
Default: true

Whether a user on an offline client can access the project without a task assigned to the user.

Responses

201

The Project was successfully created.

400

The provided project is not valid

401

The server could not authenticate the request. Either the api-key is not correct or it wasn't provided in the request at all. Check if you have provided the correct api-key within the X-Api-Key header or as api_key query-parameter. See: Authentication

403

The api-key has not the required rights to perform the request on this resource.

409

An identical project already exists.

post /projects
https://{mQuest-host}/qs/{tenant}/api/{version}/projects

Staging example

https://staging.mquest.de/qs/{tenant}/api/{version}/projects

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "code": 3003,
  • "desc": "Request validation error",
  • "message": "The request is not valid",
  • "causes":
    [
    ]
}

Get project-configuration

Get the configuration of the requested project.

path Parameters
tenant
required
string [\w\d@\.\-_]{3,100}

See Tenant in the Base URI section.

version
required
string
Value: "v1"

The current version of the endpoint

projectName
required
string
Example: FairSurvey

The name of the project (questionnaire).

Responses

200

Load a specific project.

401

The server could not authenticate the request. Either the api-key is not correct or it wasn't provided in the request at all. Check if you have provided the correct api-key within the X-Api-Key header or as api_key query-parameter. See: Authentication

403

The api-key has not the required rights to perform the request on this resource.

404

The project with the given id or name doesn't exist.

get /projects/{projectName}
https://{mQuest-host}/qs/{tenant}/api/{version}/projects/{projectName}

Staging example

https://staging.mquest.de/qs/{tenant}/api/{version}/projects/{projectName}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "name": "FairSurvey",
  • "mqf_version": 42,
  • "uuid": "28be4c49-dfc7-4998-b015-639632f44e99",
  • "created": "2019-01-28T09:34:35.000Z",
  • "updated": "2019-07-08T08:28:39.000Z",
  • "ref_code": "l9adshcjmt",
  • "available_languages":
    [
    ],
  • "accounting_type": "LIVE",
  • "online_available": false,
  • "offline_available": true,
  • "multiple_online_participations_allowed": false,
  • "unpersonalized_offline_questioning_allowed": true
}

Update project-configuration

Update the configuration of the requested project.

path Parameters
tenant
required
string [\w\d@\.\-_]{3,100}

See Tenant in the Base URI section.

version
required
string
Value: "v1"

The current version of the endpoint

projectName
required
string
Example: FairSurvey

The name of the project (questionnaire).

Request Body schema: application/json

A questioning project in mQuest.

name
string [A-Za-z0-9 -_\.]+

The name of the project.

mqf
file

The questionnaire (mqf) file

accounting_type
string
Enum: "TEST" "LIVE"

If you don't have a license for the project then this property will be null.

If you have a license for the project, then this property can either be :

  • TEST - Synchronize up to 30 datasets free of charge.
  • LIVE - Normal usage and every dataset gets charged.

The accounting-type can only be switched from TEST to LIVE. While changing, you can decide to keep the test datasets and get charged for them or else they will be deleted. Switching the accounting-type from LIVE to TEST is not possible.

online_available
boolean
Default: false

Whether the project should be available for online clients (mQuest DR).

offline_available
boolean
Default: true

Whether the project should be available for offline clients (iOS, Android).

multiple_online_participations_allowed
boolean
Default: false

Whether one user can participate multiple times in an online-project.

unpersonalized_offline_questioning_allowed
boolean
Default: true

Whether a user on an offline client can access the project without a task assigned to the user.

Responses