mQuest API (v1)

Download OpenAPI specification:Download

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.

mQuest webhook

In addition to the API, cluetec also provides a webhook, which is capable of sending notifications to the customer's system about various events that occur on the mQuest platform (e.g. a new data set is available). A detailed description and documentation is available at: (mQuest webhook).

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.

Request a tenant and an API-Key at support@mquest.de
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.
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:

Preferred method: Via a custom header named X-Api-Key
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.

Authorizations:

Header-API-KeyQuery-API-Key

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 .. 1000 ] Default: 20 Specifies the page size (how many elements will be contained in one page at most).
page	integer >= 1 Default: 1 Specifies the page number to be retrieved.

Responses

Response samples

200
401
403

Content type

application/json

[{"name": "FairSurvey",
"mqf_version": 42,
"uuid": "28be4c49-dfc7-4998-b015-639632f44e99",
"created": "2019-01-28T10:34:35+01",
"updated": "2019-07-08T10:28:39+02",
"ref_code": "l9adshcjmt",
"available_languages": ["en",
"de"
],
"accounting_type": "LIVE",
"online_available": false,
"offline_available": true,
"multiple_online_participations_allowed": false,
"unpersonalized_offline_questioning_allowed": true
}
]

Create project

Create a new project.

Authorizations:

Header-API-KeyQuery-API-Key

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

Response samples

400
401
403
409

Content type

application/json

{"code": 3003,
"desc": "Request validation error",
"message": "The request is not valid",
"causes": [{"code": 4009,
"message": "The project name is not valid. Should match: [A-Za-z0-9 -_.]"
}
]
}

Get project-configuration

Get the configuration of the requested project.

Authorizations:

Header-API-KeyQuery-API-Key

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

Response samples

200
401
403
404

Content type

application/json

{"name": "FairSurvey",
"mqf_version": 42,
"uuid": "28be4c49-dfc7-4998-b015-639632f44e99",
"created": "2019-01-28T10:34:35+01",
"updated": "2019-07-08T10:28:39+02",
"ref_code": "l9adshcjmt",
"available_languages": ["en",
"de"
],
"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.

Authorizations:

Header-API-KeyQuery-API-Key

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

Request samples

Payload

Content type

application/json

{"name": "FairSurvey",
"mqf": null,
"accounting_type": "LIVE",
"online_available": false,
"offline_available": true,
"multiple_online_participations_allowed": false,
"unpersonalized_offline_questioning_allowed": true
}

Response samples

400
401
403
404

Content type

application/json

{"code": 3003,
"desc": "Request validation error",
"message": "The request is not valid",
"causes": [{"code": 4009,
"message": "The project name is not valid. Should match: [A-Za-z0-9 -_.]"
}
]
}

Delete project

Delete the given project by its id.

Authorizations:

Header-API-KeyQuery-API-Key

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

Response samples

401
403
404

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Get mqf-file of project

Load the mqf-file of the given project. If the version query parameter isn't specified, the HEAD- (newest) mqf version of the project will be loaded.

Authorizations:

Header-API-KeyQuery-API-Key

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).

query Parameters

version

string(HEAD|[0-9]+)

Default: "HEAD"

Example: version=13

Responses

Response samples

401
403
404

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Update project-mqf

Update the mqf (the questionnaire) of a project.

Authorizations:

Header-API-KeyQuery-API-Key

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/octet-stream

The mqf file format for a mQuest questionnaire.

string <binary>

Responses

Response samples

400
401
403
404

Content type

application/json

{"code": 3003,
"desc": "Request validation error",
"message": "The request is not valid",
"causes": [{"code": 3004,
"message": "the data must not be empty"
}
]
}

Trigger backup-creation of project

This endpoint is used to trigger an asynchronous job that generates a backup of all data for the given questionniare.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	enum (as string) See Version in the Base URI section.
projectName required	string Example: FairSurvey The name of the project (questionnaire).

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

401
403
404
429

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Import project from backup (mqbak)

This endpoint is used to trigger an asynchronous job that imports backed up data and writes the data into a new questionnaire project. The request has a multipart/form-data body that requires a name and a .mqbak-file to be specified for the import.

Authorizations:

Header-API-KeyQuery-API-Key

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 start a long running task for importing backup data into a new questionnaire project.

name	string <= 30 characters [A-Za-z0-9\u0020\u002D\u005F\u002E]+ The name for the project that will be created and populated with the backed up data in the import process.
mqbak	file The mqbak-file to be imported. It gets imported as application/octet-stream.

Responses

Response samples

401
403
429

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Project-Attachments

Get meta-data of all attachments

Load the meta-data of all attachments of the given project. The data will only contain information about the attachments (name, type etc.) but not the actual data.

Authorizations:

Header-API-KeyQuery-API-Key

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).

query Parameters

size	integer [ 1 .. 1000 ] Default: 20 Specifies the page size (how many elements will be contained in one page at most).
page	integer >= 1 Default: 1 Specifies the page number to be retrieved.

Responses

Response samples

200
401
403
404

Content type

application/json

[{"id": 81068,
"name": "make.acl",
"type": "ACL",
"crc": 446592047
},
{"id": 81069,
"name": "model.macl",
"type": "MACL",
"crc": 1381894955
}
]

Get meta-data of attachment

Load the meta-data of a project-attachment. The data will only contain information about the attachment (name, type etc.) but not the actual data.

Authorizations:

Header-API-KeyQuery-API-Key

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).
attachmentId required	integer Example: 4172 Unique id of the project attachment. Numerical value. Mandatory field.

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": 81068,
"name": "make.acl",
"type": "ACL",
"crc": 446592047
}

Get raw data of attachment

Load the raw data of an project-attachment. If the attachment is a ACL/MACL-attachment, the data will be converted back to a csv-representation. The mime-type will be text/plain. The order of the acl/macl-entries in the response might be different to the initially uploaded file. Attachments of type MEDIA will have the mime-type application/octet-stream.

Authorizations:

Header-API-KeyQuery-API-Key

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).
attachmentId required	integer Example: 4172 Unique id of the project attachment. Numerical value. Mandatory field.

Responses

Response samples

200
401
403
404

Content type

application/octet-stream

No sample

Update attachment by id

Update an existing attachment by its id. This will update only the raw attachment data. The checksum of the attachment will be automatically recalculated. Changing the name or type of an attachment is not possible. The acl-data is uploaded via a single PUT request as application/octet-stream.

Authorizations:

Header-API-KeyQuery-API-Key

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).
attachmentId required	integer Example: 4172 Unique id of the project attachment. Numerical value. Mandatory field.

Request Body schema: application/octet-stream

string <binary>

Responses

Response samples

400
401
403
404

Content type

application/json

{"code": 2003,
"message": "The attachment with the id [123] does not exist"
}

Questions

Get questions of project

Load the questions of the given project.

Available query-attributes are:

var_name
properties.* - any question-property. Note: when querying a property - all questions which haven't defined this particular property won't match the query

Authorizations:

Header-API-KeyQuery-API-Key

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).

query Parameters

query	string Example: query=questionnaire=in=(fb_intern,fb_kunde);(user=="admin",version==24) Specifies a filter for the given resource. The syntax of the query is rsql. The following comparison operators are available: Equal to: `==` Not equal to: `!=` In: `=in=` Not in: `=out=` Multiple comparisons can be related to each other with logical operators: Logical AND: ; or and Logical OR: , or or By default, the AND operator takes precedence (i.e. it's evaluated before any OR operators are). However, a parenthesized expression can be used to change the precedence, yielding whatever the contained expression yields. Examples: `query=specifier=="task-0001" query=questionnaire=in=(fb_intern,fb_kunde);(user=="admin",version==24) query=properties.questioning_questionHidden==true` Which attributes can be used depends on the resource.
size	integer [ 1 .. 1000 ] Default: 20 Specifies the page size (how many elements will be contained in one page at most).
page	integer >= 1 Default: 1 Specifies the page number to be retrieved.

Responses

Response samples

200
401
403
404

Content type

application/json

[{"id": 304,
"question_id": 15,
"parent_chapter_id": 34,
"question_type": "mcss",
"choice_type": "list",
"var_name": "TAKEPART",
"analytics_paths": null,
"image_id": null,
"title": null,
"text": {"en": "Hello. My name is … from the company cluetec. We are carrying out a visitor’s survey commissioned by the trade fair organisers. Have you time to answer a few questions?",
"de": "Guten Tag. Mein Name ist ... von der Fa. cluetec GmbH. Wir führen im Auftrag der Messe eine Besucherbefragung durch. Hätten Sie Zeit, ein paar Fragen zu beantworten?"
},
"default_value": null,
"answers": [{"answer_id": 1,
"answer_index": 0,
"question_id": 15,
"code": "1",
"text": {"en": "Yes",
"de": "Ja"
},
"selected": false,
"single_answer": false,
"fixed_position": false
},
{"answer_id": 2,
"answer_index": 1,
"question_id": 15,
"code": "2",
"text": {"en": "No",
"de": "Nein"
},
"selected": false,
"single_answer": false,
"fixed_position": false
}
],
"max_answers": null,
"min_answers": null,
"choice_order": "none",
"autocompletion_list": null,
"quick_click": false,
"required": false,
"m_out_of_n": false,
"additional_choice_allowed": true,
"min_value": null,
"max_value": null,
"characters": null,
"number_of_characters": 255,
"decimal_places": null,
"properties": { },
"included_answers_question_id": null,
"included_answers_mode": null,
"additional_choices": [-1,
-2
],
"validation": [{"if_not": "Q1.1",
"jump_to": [{"@type": "question",
"id": 1
}
],
"validation_message": {"en": "Please agree to the terms and conditions",
"de": "Bitte stimmen Sie den Allgemeinen Geschäftsbedingungen zu"
}
}
],
"branching": [{"if": "Q1 == \"exit\"",
"jump_to": {"@type": "exit"
}
},
{"if": "Q1 == \"skip\"",
"jump_to": {"@type": "end_of_chapter"
}
}
],
"filter": [{"if_not": "0",
"jump_to": {"@type": "next"
}
}
]
}
]

Chapters

Get chapters of a project

Load the chapters of the given project.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	string Value: "v3" The current version of the endpoint
projectName required	string Example: FairSurvey The name of the project (questionnaire).

query Parameters

size	integer [ 1 .. 1000 ] Default: 20 Specifies the page size (how many elements will be contained in one page at most).
page	integer >= 1 Default: 1 Specifies the page number to be retrieved.
version	integer >= 1 Specify the questionnaire version for which to get the chapters. If not provided, the chapters for the currently active version (the head version) will be returned.

Responses

Response samples

200
401
403
404

Content type

application/json

[{"chapter_id": 304,
"parent_id": 15,
"name": {"en": "This is the chapter name",
"de": "Das ist der Kapitelname"
},
"text": {"en": "This is the chapter text",
"de": "Das ist der Kapiteltext"
},
"iteration_prefix": {"en": "Dynamic chapter prefix",
"de": "Prefix für dynamisches Kapitel"
},
"m_out_of_n": 1,
"required_m_out_of_n_child": true,
"complete": true,
"navigable": true,
"sub_elements_order": "AS_ENTERED",
"properties": { },
"var_name": "dynVar",
"filter": "string"
}
]

Dyn-Chapters

Get list of dynamic chapters

Load a list of the dynamic chapters defined for the given project.

Authorizations:

Header-API-KeyQuery-API-Key

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).

query Parameters

size	integer [ 1 .. 1000 ] Default: 20 Specifies the page size (how many elements will be contained in one page at most).
page	integer >= 1 Default: 1 Specifies the page number to be retrieved.

Responses

Response samples

200
401
403
404

Content type

application/json

[{"var_name": "dynChap01",
"iteration_prefix": {"en": "en02",
"de": "de02"
},
"name": {"en": "The name of the dynamic chapter 'dynChap01'",
"de": "Der Name des dynamischen Kapitels 'dynChap01'"
},
"text": {"en": "The english text for the dynamic chapter 'dynChap01'",
"de": "Der deutsche Text für das dynamische Kapitel 'dynChap01'"
}
}
]

Get dynamic chapter results

Load the results of the given dynamic chapter. This will load the results of all iterations of this chapter over all interviews. The results can be filtered / queried by all columns defined in the header (this varies depending on the questionnaire). E.g. to filter the dynamic chapter results by main-result-id, the query might look like this:

query=id==1008

which will return data only for the (main-) id 1008. The value with which to filter refers to the value field inside the single response-column object. Here are some examples of valid queries:

query=OPT==1
query=QXY_1==0,(FILTER==0;OPT=='hello')

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	enum (as string) See Version in the Base URI section.
projectName required	string Example: FairSurvey The name of the project (questionnaire).
dynChapName required	string Example: dynVar The variable-name of the dynamic chapter of which to load the results.

query Parameters

query	string Example: query=questionnaire=in=(fb_intern,fb_kunde);(user=="admin",version==24) Specifies a filter for the given resource. The syntax of the query is rsql. The following comparison operators are available: Equal to: `==` Not equal to: `!=` In: `=in=` Not in: `=out=` Multiple comparisons can be related to each other with logical operators: Logical AND: ; or and Logical OR: , or or By default, the AND operator takes precedence (i.e. it's evaluated before any OR operators are). However, a parenthesized expression can be used to change the precedence, yielding whatever the contained expression yields. Examples: `query=specifier=="task-0001" query=questionnaire=in=(fb_intern,fb_kunde);(user=="admin",version==24) query=properties.questioning_questionHidden==true` Which attributes can be used depends on the resource.
size	integer [ 1 .. 1000 ] Default: 20 Specifies the page size (how many elements will be contained in one page at most).
page	integer >= 1 Default: 1 Specifies the page number to be retrieved.

Responses

Response samples

200
401
403
404

Content type

application/json

{"header": {"id": {"data_type": "LONG",
"source": "META_DATA"
},
"sub_id": {"data_type": "LONG",
"source": "META_DATA"
},
"sub_iter_idx": {"data_type": "LONG",
"source": "META_DATA"
},
"<column-name>": {"var_name": "QA1",
"data_type": "STRING",
"source": "ANSWER",
"question_type": "uit",
"choice_type": "text"
}
},
"data": [{"responses": {"id": {"value": 42
},
"sub_id": {"value": 4242
},
"sub_iter_idx": {"value": 1
},
"<column-name>": {"value": "Some answer",
"is_in_sequence": true
}
}
}
]
}

Results

Get all project-results

Load all results of one project (questionnaire).

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	string Value: "v2" The current version of the endpoint
projectName required	string Example: FairSurvey The name of the project (questionnaire).

query Parameters

query	string Example: query=questionnaire=in=(fb_intern,fb_kunde);(user=="admin",version==24) Specifies a filter for the given resource. The syntax of the query is rsql. The following comparison operators are available: Equal to: `==` Not equal to: `!=` In: `=in=` Not in: `=out=` Multiple comparisons can be related to each other with logical operators: Logical AND: ; or and Logical OR: , or or By default, the AND operator takes precedence (i.e. it's evaluated before any OR operators are). However, a parenthesized expression can be used to change the precedence, yielding whatever the contained expression yields. Examples: `query=specifier=="task-0001" query=questionnaire=in=(fb_intern,fb_kunde);(user=="admin",version==24) query=properties.questioning_questionHidden==true` Which attributes can be used depends on the resource.
size	integer [ 1 .. 1000 ] Default: 20 Specifies the page size (how many elements will be contained in one page at most).
page	integer >= 1 Default: 1 Specifies the page number to be retrieved.

Responses

Response samples

200
401
403
404

Content type

application/json

{"header": {"id": {"data_type": "LONG",
"source": "META_DATA"
},
"<column-name>": {"var_name": "QA1",
"data_type": "STRING",
"source": "ANSWER",
"question_type": "uit",
"choice_type": "text"
}
},
"data": [{"responses": {"id": {"value": 42
},
"<column-name>": {"value": "Some answer",
"is_in_sequence": true
}
}
}
]
}

Delete multiple project-results

This method is used to delete multiple results. A time frame to delete only results from a certain period can be chosen with query parameters. If no query parameters are provided, all results will be deleted.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	string Value: "v2" The current version of the endpoint
projectName required	string Example: FairSurvey The name of the project (questionnaire).

query Parameters

from	string <date> Example: from=2016-08-21 Specifies the beginning of a time frame for deleting results from a certain period. Including this day (0 am). If nothing is specified for this parameters, the earliest day will be used. The `from` date must be before the `until` date, otherwise there will be an error response.
until	string <date> Example: until=2016-11-21 Specifies the end of a time frame for deleting results from a certain period. Including this day (11:59 pm). The default value, if nothing is specified for this parameters, is todays date.

Responses

Response samples

401
403
404

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Get a single result

Load a single result by its id.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	string Value: "v2" The current version of the endpoint
projectName required	string Example: FairSurvey The name of the project (questionnaire).
resultId required	integer Example: 2485 The id of the result.

Responses

Response samples

200
401
403
404

Content type

application/json

{"header": {"id": {"data_type": "LONG",
"source": "META_DATA"
},
"<column-name>": {"var_name": "QA1",
"data_type": "STRING",
"source": "ANSWER",
"question_type": "uit",
"choice_type": "text"
}
},
"data": {"responses": {"id": {"value": 42
},
"<column-name>": {"value": "Some answer",
"is_in_sequence": true
}
}
}
}

Delete result

This method is used to delete a single result of a project by the resultId.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	string Value: "v2" The current version of the endpoint
projectName required	string Example: FairSurvey The name of the project (questionnaire).
resultId required	integer Example: 2485 The id of the result.

Responses

Response samples

401
403
404

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Render a single result using a template

Render a single result based on a template. The template should be provided as a request payload. You can use any velocity syntax in the provided template. The variable $result is available in the template and contains all responses of the given result. If the query parameter o is set to PDF or RTF - the endpoint expects a FOP-template containing velocity placeholders.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	string Value: "v2" The current version of the endpoint
projectName required	string Example: FairSurvey The name of the project (questionnaire).
resultId required	integer Example: 2485 The id of the result.

query Parameters

o

string

Default: "text"

Enum: "pdf" "rtf" "json" "text" "xml" "html"

Specifies the output format. If pdf or rtf is set as output format, the provided template must be a valid FOP template. The other output formats do not influence the way the provided template ist rendered, but the proper content-type will be set. If not set, the content-type will be text/plain.

Request Body schema: text/plain

string

Responses

Response samples

400
401
403
404

Content type

application/json

{"code": 4502,
"message": "could not process the fop-template: 'org.apache.fop.fo.ValidationException: First element must be the\nfo:root formatting object. Found fo:rootX instead. Please make sure you're producing a valid XSL-FO\ndocument.'\n"
}

Get stats regarding dynamic chapters within a result

Get a list of all dynamic chapters in the project and the iteration count for each chapter for this result. The list will contain all dynamic chapters contained in the current (head) project version. If no iterations were created for a chapter for the given result, the chapter will still be included in this list - but with an iteration count of zero. Dynamic chapters which may have existed in the project version of the particular result but do not exist in the head version of the project won't be included in this list - even if there are results for some or all of these deleted chapters.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	string Value: "v2" The current version of the endpoint
projectName required	string Example: FairSurvey The name of the project (questionnaire).
resultId required	integer Example: 2485 The id of the result.

Responses

Response samples

200
401
403
404

Content type

application/json

[{"chapter_var": "dyn123",
"iteration_count": 3
},
{"chapter_var": "dyn456",
"iteration_count": 0
},
{"chapter_var": "dyn789",
"iteration_count": 4
}
]

Trigger result export

This endpoint is used to trigger an asynchronous job that writes all results of the given questionnaire into a file. The file format can be either XLSX, SAV or CSV. Choose the file format with query parameters. Depending on the file format there are more query parameters for configuration available.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	enum (as string) See Version in the Base URI section.
projectName required	string Example: FairSurvey The name of the project (questionnaire).

query Parameters

format required	string Enum: "xlsx" "sav" "csv" Example: format=csv Specifies the file format of the export for the result data.
delimiter	string Default: "semicolon" Enum: "comma" "colon" "semicolon" Example: delimiter=comma Only available for CSV-export. Specifies the delimiter to separate columns in a CSV-export.
quote_character	string Default: "double" Enum: "single" "double" Example: quote_character=double Only available for CSV-export. Specifies if the CSV-export should contain single or double quotes surrounding the column-values.
header	boolean Default: true Example: header=true Only available for CSV-export. Specifies if the CSV-export should contain a header row or not.
charset	string Default: "utf-8" Example: charset=utf-8 Only available for CSV-export. Defines the charset used for writing the CSV-file.
replace_newlines	boolean Default: false Only available for CSV-export. Specifies if the rows of the CSV-file get separated by a newline or by a whitespace. Set to false to separate rows by newlines.
lang	string Default: "en" Example: lang=de Only available for SAV-export. Set the language for the export. If the query parameter is not set, or if the specified language doesn't exist in the project, the async-job tries to use english (en). Then all languages of the project get checked. If english is available it will be used. If english is not in the list of languages, the first one in the list will be used for the export.

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

400
401
403
404
429

Content type

application/json

Example

Bad Request, unknown

{"code": 3003,
"desc": "Request validation error",
"message": "The request is not valid",
"causes": [{"code": 3004,
"message": "the value [xyz] set in the query parameter [format] is not a valid format. expected one of [csv, xlsx, sav, json (default), ascii]"
}
]
}

Trigger generation of random-results

This endpoint is used to trigger an asynchronous job that generates random results for the given project. This POST request requires a JSON body. It contains parameters to configure the generated test data.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	enum (as string) See Version in the Base URI section.
projectName required	string Example: FairSurvey The name of the project (questionnaire).

header Parameters

Content-Type

required

string

Example: application/json

Specifies the MIME-Type for the request. Must be set to application/json for this request.

Request Body schema: application/json

A JSON body for the test data long running task endpoint.

number_of_data_sets	number [ 1 .. 10000 ] The number of data sets that will get generated with random data.
language	string The language that is used for the generated data sets.
create_statistics	boolean Determines if statistics for the generated data sets will be calculated.
include_media_responses	boolean Determines if the generated random data sets contain media responses.

Responses

Request samples

Payload

Content type

application/json

{"number_of_data_sets": 100,
"language": "en",
"create_statistics": true,
"include_media_responses": false
}

Response samples

400
401
403
404
429

Content type

application/json

{"code": 3003,
"desc": "Request validation error",
"message": "The request is not valid",
"causes": [{"code": 3004,
"message": "must be greater or equal 1"
}
]
}

Trigger excel-reporting

This endpoint is used to trigger an asynchronous job that generates an excel report from results of the given project. An excel template file (.xlsx or .xlsm) is required in the POST request.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	enum (as string) See Version in the Base URI section.
projectName required	string Example: FairSurvey The name of the project (questionnaire).

Request Body schema: multipart/form-data

The form parameters for generating a report for a specific project.

type	string Value: "excel" Determines which file type to use for the generated report. Example: `"excel"` (required)
lang	string [ 2 .. 6 ] characters Abbreviation for the language that gets uses in the report. Example: `"en_US"`
exclude_canceled_datasets	boolean Specifies if canceled datasets get included in the report or not. Example: `true` (required)
do_formula_evaluation	boolean Specifies if all formula cells of the generated excel report get evaluated. This may cause the export process to take longer. Example: `false` (required)
template	file This file is either one of [xlsx, xlsm] that serves as a template for the report. Example: `"FairSurveyTemplate.xlsx"` (required)
template_format	string Enum: "xlsx" "xlsm" Determines which file type the uploaded template has. Example: `"xlsx"` (required)

Responses

Response samples

401
403
404
429

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Medias

Get filenames of project-medias

Load the metadata (filenames) to all medias for the given project.

Authorizations:

Header-API-KeyQuery-API-Key

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).

query Parameters

from	string <date> Example: from=2016-08-21 Specifies the beginning of a time frame for deleting results from a certain period. Including this day (0 am). If nothing is specified for this parameters, the earliest day will be used. The `from` date must be before the `until` date, otherwise there will be an error response.
until	string <date> Example: until=2016-11-21 Specifies the end of a time frame for deleting results from a certain period. Including this day (11:59 pm). The default value, if nothing is specified for this parameters, is todays date.

Responses

Response samples

200
401
403
404

Content type

application/json

[{"filename": "medias_test-2-74883+3.jpg"
},
{"filename": "medias_test-2-74883+1.jpg"
},
{"filename": "medias_test-2-74882+1.jpg"
}
]

Get filenames of result-medias

Load the metadata for files belonging to a specific result.

Authorizations:

Header-API-KeyQuery-API-Key

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).
resultId required	integer Example: 2485 The id of the result.

Responses

Response samples

200
401
403
404

Content type

application/json

[{"filename": "medias_test-2-74883+3.jpg"
},
{"filename": "medias_test-2-74883+1.jpg"
},
{"filename": "medias_test-2-74882+1.jpg"
}
]

Get metadata of media-file

Load the metadata that belongs to a specific media file.

Authorizations:

Header-API-KeyQuery-API-Key

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).
resultId required	integer Example: 2485 The id of the result.
mediaFileName required	string Example: tradeshow2017-Q45-1234.jpg The name of the media-file including file extension.

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": 523,
"result_id": 124,
"filename": "medias_test-2-74883+1.jpg",
"handover": "2018-02-21T10:44:04+01",
"is_file_present": true,
"hidden": false,
"question_var_name": "TAKEPHOTO",
"rotation": null
}

Get media-file

Load an explicit file with the given file name. The File must be from the given project and inside the given result(id). Raw medias can be pictures, videos or audiofiles. Construction of the filename: {questionnaire-name}-{Question-Varname}-{ResultId}.{file-extension}

Authorizations:

Header-API-KeyQuery-API-Key

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).
resultId required	integer Example: 2485 The id of the result.
mediaFileName required	string Example: tradeshow2017-Q45-1234.jpg The name of the media-file including file extension.

Responses

Response samples

401
403
404

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Trigger media-export

This endpoint is used to trigger an asynchronous job that packages all media files for all results of the given questionnaire into a zip archive.

Authorizations:

Header-API-KeyQuery-API-Key

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

Response samples

401
403
404
429

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Tasks

A task can be used as a specialized project. Tasks are always bound to a project, but also to a certain user. This means, only this particular user will be able to see / load the task on its device.

Additionally, tasks can have some specialized configurations which might affect when the task will be visible to the user (availability), until when can the user execute the task (end_date), how many interviews the user should conduct before the task is completed (finish_type) etc.

A task can also be configured to alert the user via local or push notifications at the tasks start_date.

As opposed to projects / questionnaires, users don't need to explicitly load tasks on their device. They will be automatically synchronized, with all their dependencies (e.g. questionnaire, attachments etc.).

You can control which users should receive a particular task by assigning the task to a user or to a user-group. When a task is assigned to a group, all users which are members of the particular group or any sub-group will receive the task.

Tasks can also have attachments like auto-completion-lists or images attached to them. See Task Attachments.

Sometimes you might not want a project to be loadable without a task attached to it. You can achive this by setting the unpersonalized_offline_questioning_allowed attribute of the particular project to false.

Because a task is bound to a project, when a project is removed, all associated tasks will be removed as well.

Get list of tasks

Get a list of tasks.

The resource is a paged resource, which means that not all elements will be included in the response but only a page. You can control the size of the page via the size query parameter and which page should be loaded via the page query parameter.

All attributes of the task can be used for filtering the list of tasks with the query query parameter. If filtering by nested attributes (e.g. task parameters) use the dot-notation to access the nested attribute (e.g. parameters.key_xyz==abc_val;short_desc.en=="very important task"). The equals (==) and not equals (!=) operators, when used with string-attributes, also support wildcards (e.g. detail_desc.de=="*Berlin*" - this will search for all tasks which contain the word Berlin in their german short-desc).

Chapter presets are accessed by the following syntax: chapter_presets.[<0-based array_index>].(index|label.|parameters.) e.g.: to access the parameter store in the second preset-element of the chapter storeCheck: chapter_presets.storeCheck[1].parameters.store

The same applies for sorting of tasks which can be configured via the sort query parameter.

Authorizations:

Header-API-KeyQuery-API-Key

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

shorten	boolean Default: false Specifies if task should be shortened. A shortened task doesn't contain detail-descriptions, parameters and chapter-presets If not provided, the response will contain all task-details.
query	string Example: query=questionnaire=in=(fb_intern,fb_kunde);(user=="admin",version==24) Specifies a filter for the given resource. The syntax of the query is rsql. The following comparison operators are available: Equal to: `==` Not equal to: `!=` In: `=in=` Not in: `=out=` Multiple comparisons can be related to each other with logical operators: Logical AND: ; or and Logical OR: , or or By default, the AND operator takes precedence (i.e. it's evaluated before any OR operators are). However, a parenthesized expression can be used to change the precedence, yielding whatever the contained expression yields. Examples: `query=specifier=="task-0001" query=questionnaire=in=(fb_intern,fb_kunde);(user=="admin",version==24) query=properties.questioning_questionHidden==true` Which attributes can be used depends on the resource.
sort	string Example: sort=name,ASC Specifies sorting of the requested list. Possible directions are ASC and DESC.
size	integer [ 1 .. 1000 ] Default: 20 Specifies the page size (how many elements will be contained in one page at most).
page	integer >= 1 Default: 1 Specifies the page number to be retrieved.

Responses

Response samples

200
401
403

Content type

application/json

[{"id": 4123,
"namespace": "93b6fc76-9f43-470f-964d-80ab6fa9c9b8",
"specifier": "e67ebf8c-2c9e-4130-acef-6086375f1167",
"version": 42,
"name": "Task 1: Clean the dishes",
"questionnaire": "dishes",
"status": "OPEN",
"availability": "ALWAYS_VISIBLE_ALWAYS_STARTABLE",
"category_id": "cars-category",
"finish_type": 1,
"start_notifications": true,
"push_notifications": false,
"rejectable": false,
"user": "me",
"group": "/org-x/sales",
"creation_date": "2019-08-24T14:15:22Z",
"due_date": "2019-08-24T14:15:22Z",
"start_date": "2019-08-24T14:15:22Z",
"end_date": "2019-08-24T14:15:22Z",
"local_time": false,
"short_desc": {"en": "Please do the dishes",
"de": "Bitte mach den Abwasch"
},
"detail_desc": {"en": "Please do the dishes",
"de": "Bitte mach den Abwasch"
},
"parameters": {"plate_a": "true",
"spoon_g": "false",
"mug_o": "true"
},
"chapter_presets": [{"chapter_var": "dry",
"entries": [{"index": 1,
"label": {"en": "Don't forget to dry the dishes",
"de": "Nicht vergessen abzutrocknen"
},
"parameters": {"spoon_g": "true"
}
}
]
}
],
"training": false
}
]

Create new task

Create a new task. A task is always bound to a project (questionnaire). Therefore the questionnaire set in the task must exist - otherwise the resource will respond with an error.

Although a task is assigned to a user, the user attribute in the task might be omitted. This might be useful if you can't set the user immediately when creating the task but want to set the user afterwards by updating the task. A task without user or with a user which doesn't exist will not be available to any clients.

Authorizations:

Header-API-KeyQuery-API-Key

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: application/json

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

namespace	string >= 3 characters Namespace for grouping tasks. If no namepsace was provided, one will be generated while creating a task.
specifier	string >= 3 characters In combination with the namespace, clearly identifies a task. There cannot be more than one task with the same combination of specifier and namespace in the system. It is an Alphanumerical value and needs at least 3 characters. If a specifier was not provided while creating a task, one will be generated.
name	string >= 3 characters The name of the task.
questionnaire	string The name of the questionnaire which is to be used for the task.
status	string Default: "OPEN" Enum: "OPEN" "LOADED" "IN_PROGRESS" "ABORTED" "CANCELED" "EXPIRED" "FINISHED" "REJECTED" "UNKNOWN" Specifies status of the task.
availability	string Default: "ALWAYS_VISIBLE_ALWAYS_STARTABLE" Enum: "ALWAYS_VISIBLE_ALWAYS_STARTABLE" "ALWAYS_VISIBLE_STARTABLE_IN_TIMEFRAME" "VISIBLE_IN_TIMEFRAME_STARTABLE_IN_TIMEFRAME" "ALWAYS_VISIBLE_STARTABLE_IN_GEO_FENCE" "VISIBLE_IN_GEO_FENCE_STARTABLE_IN_GEO_FENCE" Specifies the visibility / availability of a task.
category_id	string A Task can have a category. Tasks will be arranged into the categories on the clients startscreen.
finish_type	integer >= -1 Indicates under which condition the task is considered completed. Refers to how often the associated questionnaire has to be completed. -1: the questionnaire can be completed an indefinite number of times. 1-N: the task is completed once the questionnaire has been completed n times.
start_notifications	boolean Default: false Indicates whether the user gets a notification when the task is available on starttime.
push_notifications	boolean Default: false Indicates whether the user gets push notifications when there are updates.
rejectable	boolean Default: false Indicates whether the user has the possibility to reject the task.
user	string The name of the user that will carry out the task.
group	string A task can also be assigned to a group of users. In this case, users which are members of this group or of any sub group will receive this task. E.g. a user who is a member of the group `/org-x/sales` will receive all tasks assigned to `/org-x` and `/org-x/sales`. But the user won't receive a task assigned to the group `/org-x/sales/project-a`. See the groups section for more information on managing groups. And the join group and leave group operations on how to assign/unassign a user to/from a group.
due_date	string <date-time> Specifies the date starting from which the task should be completed.
start_date	string <date-time> Specifies the start date from which the task will be available.
end_date	string <date-time> Specifies the end date from which the task will not be available anymore.
local_time	boolean Default: false If set to `true`, the client will ignore any time-zones provided in start/end/due date and interpret these values with its local time-zone. E.g.: a client with Pacific Standard Time (UTC-08:00) will interpret the timestamp `11:20:00+0100` as `11:20:00-0800` if `local_time=true`. As opposed to `02:20:00-0800` if `local_time=false`. This setting only affects the client. For task expiration, the timezone as set in `end_date` will be used.
	object Internationalized short description of the task. A dictionary of key-values where key is the language-code (e.g. de, en etc.) and value is the internationalized text. This text will appear on task overview screen.
	object Internationalized detailed description of the task. A dictionary of key-values where key is the language-code (e.g. de, en etc.) and value is the internationalized text. In this text you can use a lot of variables which change the text during runtime. E.g. %task_property_myTaskProperty1%
	object
	Array of objects
training	boolean Default: false Indicates whether the task is for training or for a real questioning scenario.

Responses

Request samples

Payload

Content type

application/json

{"namespace": "93b6fc76-9f43-470f-964d-80ab6fa9c9b8",
"specifier": "e67ebf8c-2c9e-4130-acef-6086375f1167",
"name": "Task 1: Clean the dishes",
"questionnaire": "dishes",
"status": "OPEN",
"availability": "ALWAYS_VISIBLE_ALWAYS_STARTABLE",
"category_id": "cars-category",
"finish_type": 1,
"start_notifications": true,
"push_notifications": false,
"rejectable": false,
"user": "me",
"group": "/org-x/sales",
"due_date": "2019-08-24T14:15:22Z",
"start_date": "2019-08-24T14:15:22Z",
"end_date": "2019-08-24T14:15:22Z",
"local_time": false,
"short_desc": {"en": "Please do the dishes",
"de": "Bitte mach den Abwasch"
},
"detail_desc": {"en": "Please do the dishes",
"de": "Bitte mach den Abwasch"
},
"parameters": {"plate_a": "true",
"spoon_g": "false",
"mug_o": "true"
},
"chapter_presets": [{"chapter_var": "dry",
"entries": [{"index": 1,
"label": {"en": "Don't forget to dry the dishes",
"de": "Nicht vergessen abzutrocknen"
},
"parameters": {"spoon_g": "true"
}
}
]
}
],
"training": false
}

Response samples

400
401
403
409

Content type

application/json

{"code": 3003,
"desc": "Request validation error",
"message": "The request is not valid",
"causes": [{"code": 3004,
"message": "name must not be null"
}
]
}

Get task by id

Load a single task with the given id. The response contains all information about the task. The json response can be shortened with a query parameter.

Authorizations:

Header-API-KeyQuery-API-Key

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
taskId required	integer Example: 272 Unique id of the task. Numerical value. Mandatory field.

query Parameters

shorten

boolean

Default: false

Specifies if task should be shortened. A shortened task doesn't contain detail-descriptions, parameters and chapter-presets If not provided, the response will contain all task-details.

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": 4123,
"namespace": "93b6fc76-9f43-470f-964d-80ab6fa9c9b8",
"specifier": "e67ebf8c-2c9e-4130-acef-6086375f1167",
"version": 42,
"name": "Task 1: Clean the dishes",
"questionnaire": "dishes",
"status": "OPEN",
"availability": "ALWAYS_VISIBLE_ALWAYS_STARTABLE",
"category_id": "cars-category",
"finish_type": 1,
"start_notifications": true,
"push_notifications": false,
"rejectable": false,
"user": "me",
"group": "/org-x/sales",
"creation_date": "2019-08-24T14:15:22Z",
"due_date": "2019-08-24T14:15:22Z",
"start_date": "2019-08-24T14:15:22Z",
"end_date": "2019-08-24T14:15:22Z",
"local_time": false,
"short_desc": {"en": "Please do the dishes",
"de": "Bitte mach den Abwasch"
},
"detail_desc": {"en": "Please do the dishes",
"de": "Bitte mach den Abwasch"
},
"parameters": {"plate_a": "true",
"spoon_g": "false",
"mug_o": "true"
},
"chapter_presets": [{"chapter_var": "dry",
"entries": [{"index": 1,
"label": {"en": "Don't forget to dry the dishes",
"de": "Nicht vergessen abzutrocknen"
},
"parameters": {"spoon_g": "true"
}
}
]
}
],
"training": false
}

Update task by id

Update an existing task by its id. The namespace and specifier can't be changed. If provided in the request payload, they will be ignored.

Authorizations:

Header-API-KeyQuery-API-Key

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
taskId required	integer Example: 272 Unique id of the task. Numerical value. Mandatory field.

Request Body schema: application/json

The form parameters for a put request to update a task.

namespace	string >= 3 characters Namespace for grouping tasks. If no namepsace was provided, one will be generated while creating a task.
specifier	string >= 3 characters In combination with the namespace, clearly identifies a task. There cannot be more than one task with the same combination of specifier and namespace in the system. It is an Alphanumerical value and needs at least 3 characters. If a specifier was not provided while creating a task, one will be generated.
name	string >= 3 characters The name of the task.
questionnaire	string The name of the questionnaire which is to be used for the task.
status	string Default: "OPEN" Enum: "OPEN" "LOADED" "IN_PROGRESS" "ABORTED" "CANCELED" "EXPIRED" "FINISHED" "REJECTED" "UNKNOWN" Specifies status of the task.
availability	string Default: "ALWAYS_VISIBLE_ALWAYS_STARTABLE" Enum: "ALWAYS_VISIBLE_ALWAYS_STARTABLE" "ALWAYS_VISIBLE_STARTABLE_IN_TIMEFRAME" "VISIBLE_IN_TIMEFRAME_STARTABLE_IN_TIMEFRAME" "ALWAYS_VISIBLE_STARTABLE_IN_GEO_FENCE" "VISIBLE_IN_GEO_FENCE_STARTABLE_IN_GEO_FENCE" Specifies the visibility / availability of a task.
category_id	string A Task can have a category. Tasks will be arranged into the categories on the clients startscreen.
finish_type	integer >= -1 Indicates under which condition the task is considered completed. Refers to how often the associated questionnaire has to be completed. -1: the questionnaire can be completed an indefinite number of times. 1-N: the task is completed once the questionnaire has been completed n times.
start_notifications	boolean Default: false Indicates whether the user gets a notification when the task is available on starttime.
push_notifications	boolean Default: false Indicates whether the user gets push notifications when there are updates.
rejectable	boolean Default: false Indicates whether the user has the possibility to reject the task.
user	string The name of the user that will carry out the task.
group	string A task can also be assigned to a group of users. In this case, users which are members of this group or of any sub group will receive this task. E.g. a user who is a member of the group `/org-x/sales` will receive all tasks assigned to `/org-x` and `/org-x/sales`. But the user won't receive a task assigned to the group `/org-x/sales/project-a`. See the groups section for more information on managing groups. And the join group and leave group operations on how to assign/unassign a user to/from a group.
due_date	string <date-time> Specifies the date starting from which the task should be completed.
start_date	string <date-time> Specifies the start date from which the task will be available.
end_date	string <date-time> Specifies the end date from which the task will not be available anymore.
local_time	boolean Default: false If set to `true`, the client will ignore any time-zones provided in start/end/due date and interpret these values with its local time-zone. E.g.: a client with Pacific Standard Time (UTC-08:00) will interpret the timestamp `11:20:00+0100` as `11:20:00-0800` if `local_time=true`. As opposed to `02:20:00-0800` if `local_time=false`. This setting only affects the client. For task expiration, the timezone as set in `end_date` will be used.
	object Internationalized short description of the task. A dictionary of key-values where key is the language-code (e.g. de, en etc.) and value is the internationalized text. This text will appear on task overview screen.
	object Internationalized detailed description of the task. A dictionary of key-values where key is the language-code (e.g. de, en etc.) and value is the internationalized text. In this text you can use a lot of variables which change the text during runtime. E.g. %task_property_myTaskProperty1%
	object
	Array of objects
training	boolean Default: false Indicates whether the task is for training or for a real questioning scenario.

Responses

Request samples

Payload

Content type

application/json

{"namespace": "93b6fc76-9f43-470f-964d-80ab6fa9c9b8",
"specifier": "e67ebf8c-2c9e-4130-acef-6086375f1167",
"name": "Task 1: Clean the dishes",
"questionnaire": "dishes",
"status": "OPEN",
"availability": "ALWAYS_VISIBLE_ALWAYS_STARTABLE",
"category_id": "cars-category",
"finish_type": 1,
"start_notifications": true,
"push_notifications": false,
"rejectable": false,
"user": "me",
"group": "/org-x/sales",
"due_date": "2019-08-24T14:15:22Z",
"start_date": "2019-08-24T14:15:22Z",
"end_date": "2019-08-24T14:15:22Z",
"local_time": false,
"short_desc": {"en": "Please do the dishes",
"de": "Bitte mach den Abwasch"
},
"detail_desc": {"en": "Please do the dishes",
"de": "Bitte mach den Abwasch"
},
"parameters": {"plate_a": "true",
"spoon_g": "false",
"mug_o": "true"
},
"chapter_presets": [{"chapter_var": "dry",
"entries": [{"index": 1,
"label": {"en": "Don't forget to dry the dishes",
"de": "Nicht vergessen abzutrocknen"
},
"parameters": {"spoon_g": "true"
}
}
]
}
],
"training": false
}

Response samples

400
401
403
404

Content type

application/json

{"code": 3003,
"desc": "Request validation error",
"message": "The request is not valid",
"causes": [{"code": 3004,
"message": "name must not be null"
}
]
}

Delete task by id

Deletes a task by id.

Authorizations:

Header-API-KeyQuery-API-Key

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
taskId required	integer Example: 272 Unique id of the task. Numerical value. Mandatory field.

Responses

Response samples

401
403
404

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Task-Attachments

Get meta-data of all task-attachments

Load the meta-data of all attachments of the given task. The data will only contain information about the attachments (name, type etc.) but not the actual data.

Authorizations:

Header-API-KeyQuery-API-Key

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
taskId required	integer Example: 272 Unique id of the task. Numerical value. Mandatory field.

query Parameters

size	integer [ 1 .. 1000 ] Default: 20 Specifies the page size (how many elements will be contained in one page at most).
page	integer >= 1 Default: 1 Specifies the page number to be retrieved.

Responses

Response samples

200
401
403
404

Content type

application/json

[{"id": 81068,
"name": "make.acl",
"type": "ACL",
"crc": 446592047
},
{"id": 81069,
"name": "model.macl",
"type": "MACL",
"crc": 1381894955
}
]

Create new task-attachment

Add a new attachment to the given task.

Authorizations:

Header-API-KeyQuery-API-Key

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
taskId required	integer Example: 272 Unique id of the task. Numerical value. Mandatory field.

Request Body schema: multipart/form-data

The form parameters for a post request to create a new attachment for a task.

name	string The name of the attachment. The attachment can be referenced via this name in the questionnaire. (required)
type	string Enum: "ACL" "MACL" "MEDIA" The type of the attachment. If ACL or MACL is choosen the `data` file is expected to be in a csv-format. The csv-file will be parsed and transformed to the binary ACL/MACL-format. (required)
data	file The attachment file to be uploaded. The data-part must provide a `Content-Disposition` with a filename. (required)

Responses

Response samples

400
401
403
404
409

Content type

application/json

{"code": 3003,
"desc": "Request validation error",
"message": "The request is not valid",
"causes": [{"code": 3004,
"message": "the form parameter [name] must be set"
}
]
}

Get meta-data of task-attachment

Load the meta-data of a task-attachment. The data will only contain informations about the attachment (name, type etc.) but not the actual data.

Authorizations:

Header-API-KeyQuery-API-Key

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
taskId required	integer Example: 272 Unique id of the task. Numerical value. Mandatory field.
attachmentId required	integer Example: 4172 Unique id of the tasks attachment. Numerical value. Mandatory field.

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": 81068,
"name": "make.acl",
"type": "ACL",
"crc": 446592047
}

Delete task-attachment

Delete the given attachment by its id.

Authorizations:

Header-API-KeyQuery-API-Key

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
taskId required	integer Example: 272 Unique id of the task. Numerical value. Mandatory field.
attachmentId required	integer Example: 4172 Unique id of the tasks attachment. Numerical value. Mandatory field.

Responses

Response samples

401
403
404

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Get raw data of task-attachment

Load the raw data of an task-attachment. If the attachment is a ACL/MACL-attachment, the data will be converted back to a csv-representation. The mime-type will be text/plain. The order of the acl/macl-entries in the response might be different to the initially uploaded file. Attachments of type MEDIA will have the mime-type application/octet-stream.

Authorizations:

Header-API-KeyQuery-API-Key

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
taskId required	integer Example: 272 Unique id of the task. Numerical value. Mandatory field.
attachmentId required	integer Example: 4172 Unique id of the tasks attachment. Numerical value. Mandatory field.

Responses

Response samples

200
401
403
404

Content type

application/octet-stream

No sample

Update raw data of task-attachment

Update an existing task-attachment. This will update only the raw-attachment data. The checksum of the attachment will be automatically recalculated. Changing the name or type of an attachment is not possible. The acl-data is uploaded via a single PUT request as application/octet-stream.

Authorizations:

Header-API-KeyQuery-API-Key

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
taskId required	integer Example: 272 Unique id of the task. Numerical value. Mandatory field.
attachmentId required	integer Example: 4172 Unique id of the tasks attachment. Numerical value. Mandatory field.

Request Body schema: application/octet-stream

string <binary>

Responses

Response samples

400
401
403
404

Content type

application/json

No sample

Traffic

Get all project-rides

Load the rides of the given project.

Authorizations:

Header-API-KeyQuery-API-Key

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).

query Parameters

size	integer [ 1 .. 1000 ] Default: 20 Specifies the page size (how many elements will be contained in one page at most).
page	integer >= 1 Default: 1 Specifies the page number to be retrieved.

Responses

Response samples

200
401
403
404

Content type

application/json

[{"ride_id": 22,
"server_side_id": 8913,
"unique_ride_id": "11891683-0f25-49b4-a901-ac75dcadeacf",
"ride_name": "Ride 101",
"questionnaire_name": "SampleTraffic",
"status": 0,
"questionnaire_version": 18,
"device_id": "b7243561-faab-445a-b368-70dab7638c62",
"interviewer": "demo"
}
]

Trigger traffic-results export

This endpoint is used to trigger an asynchronous job that writes all results for the given ride project into a file.

Authorizations:

Header-API-KeyQuery-API-Key

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

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

401
403
404
429

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Get ride

Load a specific ride of the given project.

Authorizations:

Header-API-KeyQuery-API-Key

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).
rideId required	integer Example: 121 The id of the ride.

Responses

Response samples

200
401
403
404

Content type

application/json

{"ride_id": 22,
"server_side_id": 8913,
"unique_ride_id": "11891683-0f25-49b4-a901-ac75dcadeacf",
"ride_name": "Ride 101",
"questionnaire_name": "SampleTraffic",
"status": 0,
"questionnaire_version": 18,
"device_id": "b7243561-faab-445a-b368-70dab7638c62",
"interviewer": "demo"
}

Get list of ride-counts

Load a list of counts for a ride of the given project.

Authorizations:

Header-API-KeyQuery-API-Key

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).
rideId required	integer Example: 121 The id of the ride.

query Parameters

size	integer [ 1 .. 1000 ] Default: 20 Specifies the page size (how many elements will be contained in one page at most).
page	integer >= 1 Default: 1 Specifies the page number to be retrieved.

Responses

Response samples

200
401
403
404

Content type

application/json

[{"id": 60730,
"stop_idx": 1,
"stop_id": "XY1",
"stop_name": "Hauptbahnhof",
"begin_timestamp": "1970-01-01T01:00:00+01",
"end_timestamp": "1970-01-01T01:00:00+01",
"cat1_in": 0,
"cat1_out": 0,
"cat1_manning": null,
"cat2_in": 3,
"cat2_out": 5,
"cat2_manning": null,
"cat3_in": 0,
"cat3_out": 0,
"cat3_manning": 0,
"cat4_in": 2,
"cat4_out": 1,
"cat4_manning": null,
"cat5_in": 0,
"cat5_out": 0,
"cat5_manning": null
}
]

Get ride-count

Load a specific count for a ride of the given project.

Authorizations:

Header-API-KeyQuery-API-Key

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).
rideId required	integer Example: 121 The id of the ride.
countId required	integer Example: 56 The id of the count.

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": 60730,
"stop_idx": 1,
"stop_id": "XY1",
"stop_name": "Hauptbahnhof",
"begin_timestamp": "1970-01-01T01:00:00+01",
"end_timestamp": "1970-01-01T01:00:00+01",
"cat1_in": 0,
"cat1_out": 0,
"cat1_manning": null,
"cat2_in": 3,
"cat2_out": 5,
"cat2_manning": null,
"cat3_in": 0,
"cat3_out": 0,
"cat3_manning": 0,
"cat4_in": 2,
"cat4_out": 1,
"cat4_manning": null,
"cat5_in": 0,
"cat5_out": 0,
"cat5_manning": null
}

Users

Get list of users

Get a list of all users for the specified tenant.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	enum (as string) See Version in the Base URI section.

query Parameters

sort	string Default: "user_name,ASC" Example: sort=last_name,DESC Sorts the list of users based on the specified parameter. The list can be sorted in ascending or descending order by appending a comma to the parameter followed by `ASC` for ascending or `DESC` for descending (e.g. `sort=first_name,DESC` - will sort by users first name in descending order). If no order direction is specified (e.g. `sort=last_name`), then `ASC` will be used by default. The user list will be sorted by user_name in ascending order by default (if no sort parameter was provided). The following user attributes can be used for sorting: id, user_name, first_name, last_name, email, email_verified, roles, groups, company, gender, phonenumber, notes, attributes.[attribute-name].
size	integer [ 1 .. 1000 ] Default: 20 Specifies the page size (how many elements will be contained in one page at most).
page	integer >= 1 Default: 1 Specifies the page number to be retrieved.
search	string Example: search=smith Filters users by username or email or first name or last name. Will find users whose username/email/first_name/last_name contains the provided value. The filter is case-insensitive (upper- and lowercase letters are treated the same). Any accents (diacritic signs) will be ignored (e.g. müller is equal to muller). This filter is ANDed with all other search.* filters.
search.username	string Example: search.username=j.doe Filters users by username. Will find users whose username contains the provided value. The filter is case-insensitive (upper- and lowercase letters are treated the same). Any accents (diacritic signs) will be ignored (e.g. müller is equal to muller). This filter is ANDed with all other search.* filters.
search.email	string Example: search.email=%40my-company.com Filters users by email. Will find users whose email contains the provided value. The filter is case-insensitive (upper- and lowercase letters are treated the same). Any accents (diacritic signs) will be ignored (e.g. müller is equal to muller). This filter is ANDed with all other search.* filters.
search.first-name	string Example: search.first-name=john Filters users by first name. Will find users whose first name contains the provided value. The filter is case-insensitive (upper- and lowercase letters are treated the same). Any accents (diacritic signs) will be ignored (e.g. müller is equal to muller). This filter is ANDed with all other search.* filters.
search.last-name	string Example: search.last-name=doe Filters users by last name. Will find users whose last name contains the provided value. The filter is case-insensitive (upper- and lowercase letters are treated the same). Any accents (diacritic signs) will be ignored (e.g. müller is equal to muller). This filter is ANDed with all other search.* filters.
search.role.blank	boolean Example: search.role.blank=true Filters users by role. Will find users which have no roles assigned if the filter is set to true. Otherwise, if the filter is set to false, will find users with at least one role assigned. This filter is ORed with search.role.name and ANDed with all other search.* filters. Note: if set to false then search.role.name will have no effect as the filter would search for users with at least one role OR having the role search.role.name* assigned*
search.role.name	string Example: search.role.name=tenant_admin Filters users by role name. Will find users which have any of the provided roles assigned. To filter by multiple roles, search.role.name can be provided multiple times (e.g. `?search.role.name=tenant_admin&search.role.name=surveyor` -- will find all users which have either the role tenant_admin or the role surveyor or both assigned). This filter is ORed with search.role.blank and ANDed with all other search.* filters.
search.group.blank	boolean Example: search.group.blank=true Filters users by group. Will find users which have no groups assigned if the filter is set to true. Otherwise, if the filter is set to false, will find users with at least one group assigned. This filter is ORed with search.group.id and ANDed with all other search.* filters. Note: if set to false then search.group.id will have no effect as the filter would search for users being a member of at least one group OR being a member of search.group.id
search.group.id	string Example: search.group.id=e552383e-d5b6-45c0-8c7c-beb55f996b06 Filters users by group id. Will find users which have any of the provided groups assigned. To filter by multiple groups, search.group.id can be provided multiple times (e.g. `?search.group.id=e552383e-d5b6-45c0-8c7c-beb55f996b06&search.group.id=b22ab954-6754-4a1b-9192-b11e593079d1` -- will find all users which are either member of the group e552383e-d5b6-45c0-8c7c-beb55f996b06 or the group b22ab954-6754-4a1b-9192-b11e593079d1 or both). This filter is ORed with search.group.blank and ANDed with all other search.* filters.
search.attribute.<attribute-name>	string Example: search.attribute.<attribute-name>=attribute-value Filters users by their attributes. Will find users which have the given attribute and the attributes value contains the provided value. E.g. to filter users by company: `?search.attribute.company=cluetec`. The filter is case-insensitive (upper- and lowercase letters are treated the same). Any accents (diacritic signs) will be ignored (e.g. müller is equal to muller). This filter is ANDed with all other search.* filters.

Responses

Response samples

200
401
403

Content type

application/json

[{"id": "c5419821-27a3-4e52-896b-2596960b6082",
"user_name": "john@doe.com",
"email": "john@doe.com",
"email_verified": true,
"phone": "740-501-2338",
"first_name": "John",
"last_name": "Doe",
"roles": ["tenant_admin"
],
"effective_roles": ["tenant_admin",
"surveyor"
],
"groups": [{"id": "5955879e-14e9-484d-86a0-b5a2dff56f8c",
"name": "sub-department-x",
"parent_id": "7ff544e9-b854-4607-9020-af863c56257b",
"path": "/department-a/sub-department-x",
"roles": ["surveyor"
]
}
],
"gender": "MALE",
"company": "John-Doe Inc.",
"notes": "Some additional notes about John Doe."
}
]

Create new user

Create a new user.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	enum (as string) See Version in the Base URI section.

Request Body schema: application/json

The user object for a post request to create a new user.

user_name	string[\w\d@\.\-_]{3,100} If the user role is tenant_admin or surveyor, the username must be a valid e-mail-address.
email	string The email that belongs to this user.
password	string If the user role is not tenant_admin or surveyor, then this password-attribute is mandatory. At least 8 characters, at least one upper-case character, at least one lower-case character, at least one digit, at least one special character.
phone	string The phone number that belongs to this user.
first_name	string The first name of the user.
last_name	string The last name of the user.
roles	Array of strings A list of roles directly assigned to this user. This list won't include roles inherited by group roles. Available default roles: [tenant_admin, surveyor, interviewer, external_system, quest_report]
effective_roles	Array of strings A list of roles assigned to this user. This list won't include only the direct roles (like the `roles` attribute) but also any inherited roles (e.g. through group memberships).
gender	string Enum: "male" "female" The gender of this user.
company	string The company of this user.
notes	string Additional notes for this user.

Responses

Request samples

Payload

Content type

application/json

{"user_name": "john@doe.com",
"email": "john@doe.com",
"password": "t0p_S€cR3T!",
"phone": "740-501-2338",
"first_name": "John",
"last_name": "Doe",
"roles": ["tenant_admin"
],
"effective_roles": ["tenant_admin",
"surveyor"
],
"gender": "MALE",
"company": "John-Doe Inc.",
"notes": "Some additional notes about John Doe."
}

Response samples

400
401
403
409

Content type

application/json

{"code": 3003,
"desc": "Request validation error",
"message": "The request is not valid",
"causes": [{"code": 4003,
"message": "The provided user name is not valid. The [user_name] attribute must not be null and it must match the following regular expression: [\\w\\d@\\.\\-_]{3,100}"
}
]
}

Get user by id

Get a certain user object.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	enum (as string) See Version in the Base URI section.
id required	string Example: 720e81c0-a13c-4aa3-9323-c915d2bc85ae Unique id of the user. String value. Contains UUID representation.

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": "c5419821-27a3-4e52-896b-2596960b6082",
"user_name": "john@doe.com",
"email": "john@doe.com",
"email_verified": true,
"phone": "740-501-2338",
"first_name": "John",
"last_name": "Doe",
"roles": ["tenant_admin"
],
"effective_roles": ["tenant_admin",
"surveyor"
],
"groups": [{"id": "5955879e-14e9-484d-86a0-b5a2dff56f8c",
"name": "sub-department-x",
"parent_id": "7ff544e9-b854-4607-9020-af863c56257b",
"path": "/department-a/sub-department-x",
"roles": ["surveyor"
]
}
],
"gender": "MALE",
"company": "John-Doe Inc.",
"notes": "Some additional notes about John Doe."
}

Update user by id

Update an existing user.

Please note: The roles-attribute can only be changed in this request for users with the role tenant_admin or surveyor. For all other roles the JSON-body which contains such an attribute it will get ignored by the server.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	enum (as string) See Version in the Base URI section.
id required	string Example: 720e81c0-a13c-4aa3-9323-c915d2bc85ae Unique id of the user. String value. Contains UUID representation.

Request Body schema: application/json

A user in mQuest.

user_name	string[\w\d@\.\-_]{3,100} If the user role is tenant_admin or surveyor, the username must be a valid e-mail-address.
email	string The email that belongs to this user.
password	string If the user role is not tenant_admin or surveyor, then this password-attribute is mandatory. At least 8 characters, at least one upper-case character, at least one lower-case character, at least one digit, at least one special character.
phone	string The phone number that belongs to this user.
first_name	string The first name of the user.
last_name	string The last name of the user.
roles	Array of strings A list of roles directly assigned to this user. This list won't include roles inherited by group roles. Available default roles: [tenant_admin, surveyor, interviewer, external_system, quest_report]
effective_roles	Array of strings A list of roles assigned to this user. This list won't include only the direct roles (like the `roles` attribute) but also any inherited roles (e.g. through group memberships).
gender	string Enum: "male" "female" The gender of this user.
company	string The company of this user.
notes	string Additional notes for this user.

Responses

Request samples

Payload

Content type

application/json

{"user_name": "john@doe.com",
"email": "john@doe.com",
"password": "t0p_S€cR3T!",
"phone": "740-501-2338",
"first_name": "John",
"last_name": "Doe",
"roles": ["tenant_admin"
],
"effective_roles": ["tenant_admin",
"surveyor"
],
"gender": "MALE",
"company": "John-Doe Inc.",
"notes": "Some additional notes about John Doe."
}

Response samples

400
401
403
404

Content type

application/json

{"code": 3003,
"desc": "Request validation error",
"message": "The request is not valid",
"causes": [{"code": 4003,
"message": "The provided user name is not valid. The [user_name] attribute must not be null and it must match the following regular expression: [\\w\\d@\\.\\-_]{3,100}"
}
]
}

Delete user by id

Delete the given user by its id.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	enum (as string) See Version in the Base URI section.
id required	string Example: 720e81c0-a13c-4aa3-9323-c915d2bc85ae Unique id of the user. String value. Contains UUID representation.

Responses

Response samples

401
403
404

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Join group

Join user with the provided id to the group referenced by the group_id in the payload.

If the user already is a member of the referenced group, the server won't respond with an error but with 204 (No Content)

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	enum (as string) See Version in the Base URI section.
id required	string Example: 720e81c0-a13c-4aa3-9323-c915d2bc85ae Unique id of the user. String value. Contains UUID representation.

Request Body schema: application/json

The id of the group the user should join

group_id

string

The id of an existing group (can be either a top-level- or a sub-group).

Responses

Request samples

Payload

Content type

application/json

{"group_id": "c4b8cd48-f398-4597-899e-ffb3735323c0"
}

Response samples

400
401
403
404

Content type

application/json

{"code": 4022,
"message": "User with id [842388d0-f9de-4bf3-8513-ad2f238cd923] at tenant [example-tenant] can't join group. A group with id [4806def2-28cd-4114-9e93-aa150cc12a2a] doesn't exist."
}

Leave group

Remove group membership of the referenced user to the group with id=groupId (see Groups). There will be no error if the user isn't a member of the referenced group. Only if the group doesn't exist at all, an error-response will be returned.

This operation does not delete the user but only the relation between the user and the group.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	enum (as string) See Version in the Base URI section.
id required	string Example: 720e81c0-a13c-4aa3-9323-c915d2bc85ae Unique id of the user. String value. Contains UUID representation.
id required	string Example: f8769e6b-911e-4388-9e79-7586ea09154f Id of a user-group. See Groups

Responses

Response samples

400
401
403
404

Content type

application/json

{"code": 4023,
"message": "User with id [347451de-a233-4483-bbcd-0c4aa8f68e2b] at tenant [example-tenant] can't leave group. A group with id [311ab33d-aaa9-4e85-b55c-627a210d6131] doesn't exist."
}

Groups

Users can be organized into groups. A group can, similar to users, have granted roles. Every user who is a member of the group inherits all granted roles of that group and all parent groups. E.g. if a user with the role interviewer joins a group with granted role tenant_admin, then the effective roles of the user will be interviewer and tenant_admin.

Groups can be organized into hierarchies - meaning that one group can have subgroups. Subgroups will, similar to users, inherit the granted roles of their parent groups.

Besides the ability to control user permissions, groups can also be used in certain api-endpoints as a substitue to a user-name. E.g. you can assign a task to a group rather than a user. This would be equivalent to assigning the task to multiple users (all users who are members of the particular group).

This section covers the management of groups and sub-groups.

When creating or updating a group, you have to make sure that the group-name is unique on its hierarchy level. E.g. there can't be two top-level groups both named groupA. Though you can have a top-level group groupA and a sub-group groupA. The server will respond with 409 (Conflict) if you try to create a top-level- or a sub-group which has not a unique name on this hierarchy level.

Get a list of groups

Get a list of all groups for the specified tenant.

Authorizations:

Header-API-KeyQuery-API-Key

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

size	integer [ 1 .. 1000 ] Default: 20 Specifies the page size (how many elements will be contained in one page at most).
page	integer >= 1 Default: 1 Specifies the page number to be retrieved.

Responses

Response samples

200
401
403

Content type

application/json

[{"id": "0f006336-7b58-4526-ac49-2c65cbaf7216",
"name": "department-a",
"path": "/department-a",
"roles": ["interviewer",
"tenant_admin"
],
"label": {"en": "Department-A",
"de": "Abteilung-A"
},
"sub_groups": {"id": "46b06857-7bcc-44a5-82b9-d2aae8147fcb",
"name": "sub-department-1",
"path": "/department-a/sub-department-1",
"roles": ["special_admin"
],
"label": {"en": "Sub-Group-1",
"de": "Untergruppe-1"
},
"sub_groups": null
}
}
]

Create new group

Create a new group. This will be a top-level group (it won't have any parent-groups).

The group name has to be unique among all top-level groups. If not, the server will respond with 409 (Conflict)

Authorizations:

Header-API-KeyQuery-API-Key

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: application/json

The group-body.

name	string[\w\d@\.\-_]{1,100} The name of the group. The group name must be unique within on the particular hierarchy level.
roles	Array of strings The granted roles of this group. When creating a new group, all roles which doesn't exist for the tenant will be ignored - only the valid roles will be granted. These are the default roles: [tenant_admin, surveyor, interviewer, external_system, quest_report]
	object Internationalized label of the group.

Responses

Request samples

Payload

Content type

application/json

{"name": "department-a",
"roles": ["interviewer",
"tenant_admin"
],
"label": {"en": "Department-A",
"de": "Abteilung-A"
}
}

Response samples

400
401
403
409

Content type

application/json

{"code": 3003,
"desc": "Request validation error",
"message": "The request is not valid",
"causes": [{"code": 4019,
"message": "The provided group name is not valid. The [name] attribute must not be null and it must match the following regular expression [\\w\\d@\\.\\-_]{3,100}"
}
]
}

Get group by id

Load a single group with the given id. The response will contain also all sub-groups (if any) of the requested group.

Authorizations:

Header-API-KeyQuery-API-Key

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
id required	string Example: 720e81c0-a13c-4aa3-9323-c915d2bc85ae Unique id of the group. String value. Contains UUID representation.

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": "0f006336-7b58-4526-ac49-2c65cbaf7216",
"name": "department-a",
"path": "/department-a",
"roles": ["interviewer",
"tenant_admin"
],
"label": {"en": "Department-A",
"de": "Abteilung-A"
},
"sub_groups": {"id": "46b06857-7bcc-44a5-82b9-d2aae8147fcb",
"name": "sub-department-1",
"path": "/department-a/sub-department-1",
"roles": ["special_admin"
],
"label": {"en": "Sub-Group-1",
"de": "Untergruppe-1"
},
"sub_groups": null
}
}

Create new sub-group

Create a new sub-group. This group will be a child (a sub-group) of the group referenced by the groupId path-parameter.

The sub-group name has to be unique among all sub-groups within the parent group (referenced by the groupId path-parameter). If not, the server will respond with 409 (Conflict)

Authorizations:

Header-API-KeyQuery-API-Key

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
id required	string Example: 720e81c0-a13c-4aa3-9323-c915d2bc85ae Unique id of the group. String value. Contains UUID representation.

Request Body schema: application/json

The group-body.

name	string[\w\d@\.\-_]{1,100} The name of the group. The group name must be unique within on the particular hierarchy level.
roles	Array of strings The granted roles of this group. When creating a new group, all roles which doesn't exist for the tenant will be ignored - only the valid roles will be granted. These are the default roles: [tenant_admin, surveyor, interviewer, external_system, quest_report]
	object Internationalized label of the group.

Responses

Request samples

Payload

Content type

application/json

{"name": "department-a",
"roles": ["interviewer",
"tenant_admin"
],
"label": {"en": "Department-A",
"de": "Abteilung-A"
}
}

Response samples

400
401
403
409

Content type

application/json

{"code": 3003,
"desc": "Request validation error",
"message": "The request is not valid",
"causes": [{"code": 4019,
"message": "The provided group name is not valid. The [name] attribute must not be null and it must match the following regular expression [\\w\\d@\\.\\-_]{3,100}"
}
]
}

Update group by id

Update an existing group by its id. Only the roles and label can be updated. If you want to move a sub-group to a new parent, you need to delete the group first and then create it under the other parent again.

The group name has to be unique on his hierarchy level. If not, the server will respond with 409 (Conflict)

Authorizations:

Header-API-KeyQuery-API-Key

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
id required	string Example: 720e81c0-a13c-4aa3-9323-c915d2bc85ae Unique id of the group. String value. Contains UUID representation.

Request Body schema: application/json

The group-body.

name	string[\w\d@\.\-_]{1,100} The name of the group. The group name must be unique within on the particular hierarchy level.
roles	Array of strings The granted roles of this group. When creating a new group, all roles which doesn't exist for the tenant will be ignored - only the valid roles will be granted. These are the default roles: [tenant_admin, surveyor, interviewer, external_system, quest_report]
	object Internationalized label of the group.

Responses

Request samples

Payload

Content type

application/json

{"name": "department-a",
"roles": ["interviewer",
"tenant_admin"
],
"label": {"en": "Department-A",
"de": "Abteilung-A"
}
}

Response samples

400
401
403
404
409

Content type

application/json

{"code": 3003,
"desc": "Request validation error",
"message": "The request is not valid",
"causes": [{"code": 4019,
"message": "The provided group name is not valid. The [name] attribute must not be null and it must match the following regular expression [\\w\\d@\\.\\-_]{3,100}"
}
]
}

Delete a group by id

Deletes a group by id.

Authorizations:

Header-API-KeyQuery-API-Key

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
id required	string Example: 720e81c0-a13c-4aa3-9323-c915d2bc85ae Unique id of the group. String value. Contains UUID representation.

Responses

Response samples

401
403
404

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Asynchronous-Jobs

Trigger backup-creation of project

This endpoint is used to trigger an asynchronous job that generates a backup of all data for the given questionniare.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	enum (as string) See Version in the Base URI section.
projectName required	string Example: FairSurvey The name of the project (questionnaire).

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

401
403
404
429

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Import project from backup (mqbak)

This endpoint is used to trigger an asynchronous job that imports backed up data and writes the data into a new questionnaire project. The request has a multipart/form-data body that requires a name and a .mqbak-file to be specified for the import.

Authorizations:

Header-API-KeyQuery-API-Key

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 start a long running task for importing backup data into a new questionnaire project.

name	string <= 30 characters [A-Za-z0-9\u0020\u002D\u005F\u002E]+ The name for the project that will be created and populated with the backed up data in the import process.
mqbak	file The mqbak-file to be imported. It gets imported as application/octet-stream.

Responses

Response samples

401
403
429

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Trigger traffic-results export

This endpoint is used to trigger an asynchronous job that writes all results for the given ride project into a file.

Authorizations:

Header-API-KeyQuery-API-Key

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

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

401
403
404
429

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Trigger result export

This endpoint is used to trigger an asynchronous job that writes all results of the given questionnaire into a file. The file format can be either XLSX, SAV or CSV. Choose the file format with query parameters. Depending on the file format there are more query parameters for configuration available.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	enum (as string) See Version in the Base URI section.
projectName required	string Example: FairSurvey The name of the project (questionnaire).

query Parameters

format required	string Enum: "xlsx" "sav" "csv" Example: format=csv Specifies the file format of the export for the result data.
delimiter	string Default: "semicolon" Enum: "comma" "colon" "semicolon" Example: delimiter=comma Only available for CSV-export. Specifies the delimiter to separate columns in a CSV-export.
quote_character	string Default: "double" Enum: "single" "double" Example: quote_character=double Only available for CSV-export. Specifies if the CSV-export should contain single or double quotes surrounding the column-values.
header	boolean Default: true Example: header=true Only available for CSV-export. Specifies if the CSV-export should contain a header row or not.
charset	string Default: "utf-8" Example: charset=utf-8 Only available for CSV-export. Defines the charset used for writing the CSV-file.
replace_newlines	boolean Default: false Only available for CSV-export. Specifies if the rows of the CSV-file get separated by a newline or by a whitespace. Set to false to separate rows by newlines.
lang	string Default: "en" Example: lang=de Only available for SAV-export. Set the language for the export. If the query parameter is not set, or if the specified language doesn't exist in the project, the async-job tries to use english (en). Then all languages of the project get checked. If english is available it will be used. If english is not in the list of languages, the first one in the list will be used for the export.

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

400
401
403
404
429

Content type

application/json

Example

Bad Request, unknown

{"code": 3003,
"desc": "Request validation error",
"message": "The request is not valid",
"causes": [{"code": 3004,
"message": "the value [xyz] set in the query parameter [format] is not a valid format. expected one of [csv, xlsx, sav, json (default), ascii]"
}
]
}

Trigger media-export

This endpoint is used to trigger an asynchronous job that packages all media files for all results of the given questionnaire into a zip archive.

Authorizations:

Header-API-KeyQuery-API-Key

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

Response samples

401
403
404
429

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Trigger generation of random-results

This endpoint is used to trigger an asynchronous job that generates random results for the given project. This POST request requires a JSON body. It contains parameters to configure the generated test data.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	enum (as string) See Version in the Base URI section.
projectName required	string Example: FairSurvey The name of the project (questionnaire).

header Parameters

Content-Type

required

string

Example: application/json

Specifies the MIME-Type for the request. Must be set to application/json for this request.

Request Body schema: application/json

A JSON body for the test data long running task endpoint.

number_of_data_sets	number [ 1 .. 10000 ] The number of data sets that will get generated with random data.
language	string The language that is used for the generated data sets.
create_statistics	boolean Determines if statistics for the generated data sets will be calculated.
include_media_responses	boolean Determines if the generated random data sets contain media responses.

Responses

Request samples

Payload

Content type

application/json

{"number_of_data_sets": 100,
"language": "en",
"create_statistics": true,
"include_media_responses": false
}

Response samples

400
401
403
404
429

Content type

application/json

{"code": 3003,
"desc": "Request validation error",
"message": "The request is not valid",
"causes": [{"code": 3004,
"message": "must be greater or equal 1"
}
]
}

Trigger excel-reporting

This endpoint is used to trigger an asynchronous job that generates an excel report from results of the given project. An excel template file (.xlsx or .xlsm) is required in the POST request.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	enum (as string) See Version in the Base URI section.
projectName required	string Example: FairSurvey The name of the project (questionnaire).

Request Body schema: multipart/form-data

The form parameters for generating a report for a specific project.

type	string Value: "excel" Determines which file type to use for the generated report. Example: `"excel"` (required)
lang	string [ 2 .. 6 ] characters Abbreviation for the language that gets uses in the report. Example: `"en_US"`
exclude_canceled_datasets	boolean Specifies if canceled datasets get included in the report or not. Example: `true` (required)
do_formula_evaluation	boolean Specifies if all formula cells of the generated excel report get evaluated. This may cause the export process to take longer. Example: `false` (required)
template	file This file is either one of [xlsx, xlsm] that serves as a template for the report. Example: `"FairSurveyTemplate.xlsx"` (required)
template_format	string Enum: "xlsx" "xlsm" Determines which file type the uploaded template has. Example: `"xlsx"` (required)

Responses

Response samples

401
403
404
429

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Get all asynchronous jobs

Load all asynchronous jobs. Once complete, an asynchronous job (and the corresponding export artifact) will only be stored for 48 hours.

Authorizations:

Header-API-KeyQuery-API-Key

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

size	integer [ 1 .. 1000 ] Default: 20 Specifies the page size (how many elements will be contained in one page at most).
page	integer >= 1 Default: 1 Specifies the page number to be retrieved.

Responses

Response samples

200
401
403

Content type

application/json

[{"id": "a1f0570c-a88c-400c-80c5-e74bfae694fc",
"create_time": "2018-02-08T11:40:01+01",
"start_time": "2018-02-08T11:40:01+01",
"end_time": "2018-02-08T11:40:08+01",
"expire_time": "2018-02-10T11:40:01+01",
"status": "COMPLETED",
"type": "TESTDATA",
"user": "john@doe.com",
"params": {"do_statistics": true,
"language": "en",
"number_of_data_sets": 100,
"questionnaire_name": "Fair Survey Demo"
},
"result": {"summary": {"summary_list": ["At question 14 [ type: uin, varname: AGE ] a Validation with a jump back to question 14 [ type: uin, varname: AGE ] was ignored"
]
},
"total_items": 100,
"current_item": 100,
"artifact_name": "20190731_0846_Fair Survey Demo_de_routing.xls",
"artifact_mime_type": "application/vnd.ms-excel"
}
}
]

Get single asynchronous job

Load a single asynchronous job.

Authorizations:

Header-API-KeyQuery-API-Key

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
asyncJobId required	string Example: aa858aaf-0c4d-4597-8199-e316846ff36e Unique id of the async job.

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": "a1f0570c-a88c-400c-80c5-e74bfae694fc",
"create_time": "2018-02-08T11:40:01+01",
"start_time": "2018-02-08T11:40:01+01",
"end_time": "2018-02-08T11:40:08+01",
"expire_time": "2018-02-10T11:40:01+01",
"status": "COMPLETED",
"type": "TESTDATA",
"user": "john@doe.com",
"params": {"do_statistics": true,
"language": "en",
"number_of_data_sets": 100,
"questionnaire_name": "Fair Survey Demo"
},
"result": {"summary": {"summary_list": ["At question 14 [ type: uin, varname: AGE ] a Validation with a jump back to question 14 [ type: uin, varname: AGE ] was ignored"
]
},
"total_items": 100,
"current_item": 100,
"artifact_name": "20190731_0846_Fair Survey Demo_de_routing.xls",
"artifact_mime_type": "application/vnd.ms-excel"
}
}

Get artifact of asynchronous job

Load the artifact of an asynchronous job. The MIME-Type depends on the generated file type. The file gets deleted after 48 hours.

Authorizations:

Header-API-KeyQuery-API-Key

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
asyncJobId required	string Example: aa858aaf-0c4d-4597-8199-e316846ff36e Unique id of the async job.

Responses

Response samples

401
403
404

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Client-Configs

The mobile clients have some configs which are not available through the settings menu. These configs can be set/changed by creating a QR code, containing the desired configs as key/value pairs, which then can be scanned in the apps. This might be tedious in situations where all clients should have a certain config set - as all clients would have to scan the QR code.

Client configs can be set globally for all clients by using this API. The clients will pickup the configs with every sync and configure themselves accordingly.

Get all client configs

List all client configs. These are sent to clients with each sync.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	string Value: "v2" The current version of the endpoint

Responses

Response samples

200
401
403

Content type

application/json

{"disable_chapter_nav_warnings": "true",
"show_task_parameters": "false"
}

Set configurations for all clients

Set client configs for all clients. This will replace all existing client configs with the new ones.

Sending an empty object {} with this request is equivalent to a DELETE request and will remove all client configs.

The response will contain the updated configs.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	string Value: "v2" The current version of the endpoint

Request Body schema: application/json

+*

pattern property

string

Responses

Request samples

Payload

Content type

application/json

{"disable_chapter_nav_warnings": "true",
"show_task_parameters": "false"
}

Response samples

200
401
403

Content type

application/json

{"disable_chapter_nav_warnings": "true",
"show_task_parameters": "false"
}

Delete all client configs

Removes all client configs

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	string Value: "v2" The current version of the endpoint

Responses

Response samples

401
403

Content type

application/json

{"timestamp": "2059-07-24T13:41:13.961+0000",
"path": "/qs/kf_local/api/v1/projects",
"status": 401,
"error": "Unauthorized",
"message": "Not Authenticated"
}

Patch client configs

Use a (https://jsonpatch.com)[jsonpatch request] to update the client configs. Returns the new client config.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	string Value: "v2" The current version of the endpoint

Request Body schema: application/json-patch+json

Array

One of

path required	string (path) A JSON Pointer path.
op required	string Enum: "add" "replace" "test" The operation to perform.
value required	any The value to add, replace or test.

Responses

Request samples

Payload

Content type

application/json-patch+json

[{"path": "/_tc_cat01_icon",
"op": "add",
"value": "clipboard-check"
},
{"path": "/start_survey_on_task_list_element_click",
"op": "add",
"value": "true"
}
]

Response samples

200
401
403

Content type

application/json

{"disable_chapter_nav_warnings": "true",
"show_task_parameters": "false"
}

Get the configuration for the given key

Get the current configuration for the given key. If there is no value set for the given key 404 (Not Found) will be returned.

Authorizations:

Header-API-KeyQuery-API-Key

path Parameters

tenant required	string[\w\d@\.\-_]{3,100} See Tenant in the Base URI section.
version required	string Value: "v2" The current version of the endpoint
key required	string Example: start_survey_on_task_list_element_click The client config key

Responses

Response samples

200
401
403

Content type

application/json

{"key": "disable_chapter_nav_warnings",
"value": "true",
"ts": "2023-08-02T14:18:42+02:00",
"set_by": "6e7177f1-8c72-48b9-924c-f7c61aa7cfdf"
}