The Evaluation API
The Evaluation API offers automated access to the data in the various platforms supplied by Tevreden. This is a RESTful API which accepts and returns plain JSON, unless specified otherwise.
Endpoint ¶
The Tevreden API is available through https://api.tevreden.nl. The API is only accessible over an encrypted connection, traffic sent over an unencrypted line (port 80) will be refused.
Authentication ¶
To use the Tevreden API an API key is needed. This API key has to be sent with every request as a value of the custom HTTP header Tevreden-API-key.
HTTP Methods ¶
The following HTTP methods can be used:
GET: Get object(s)
POST: Create a new object(s)
PATCH: Edit an existing object(s)
PUT: Replace an object(s)
DELETE: Delete an object(s)
Status Codes ¶
Successful requests or errors are replied with standard HTTP status codes. These are:
200 OK: Request successfully executed
201 Created: The object has been successfully created (after a POST)
202 Accepted: The request has been accepted, but the server is still busy processing. Try again later.
400 Bad Request: Invalid syntax / missing arguments
401 Unauthorized: No or invalid API key sent
403 Forbidden: No access to resource
404 Not Found: The requested resource does not exist
405 Method Not Allowed: The used HTTP method (GET/POST, etc.) is not supported for this resource
420 Too Many Requests: Too many requests at once
500 Internal Server Error: Something is wrong
501 Not Implemented: The used HTTP method is not yet built in for this resource
If possible and applicable there will be a JSON response sent after a request with more information if there is an error. This hash will contain at least a key called “message” with an error message.
Date Formats ¶
For various resources a date or datetime can be supplied. These would ideally be formatted by following the ISO8601 norm. For example:
“2015-02-01” (1st February 2015)
“2014-12-31T23:59:59” (1 second before the end of 2015)
It’s also possible to send relative dates or times:
“12 Mar 2015”
“March 1st, 2015”.
“1 year ago”
“last monday”
“next week”.
For a complete overview of the supported formats please visit the documentation of Time::ParseDate.
Root
GET /
A link to this documentation in HTML format.
Example URI
GET https://api.tevreden.nl/
Response 200
Headers
Content-Type: text/html
Body
<html> ... documentation ... </html>
Platforms
All the data collected by Tevreden is split up into “platforms”. The rule for these platforms is that every platform covers a specific sector or “branch”. For example we have: kinderopvang (child day care), autobedrijf (car company) and apotheek (pharmacy). Platforms have their own seperate databases. In some cases we have one or serveral platforms below one of these platforms. These “sub-platforms” share the same database as the main platform but only have access to a subset of the data. This can be for a specific organisation for example.
Each seperate API call can only access 1 platform at a time. This can be a “platform” or a “sub-platform”. For each call made (except for the GET /platforms below) there needs to be a custom HTTP header called Tevreden-platform which contains the name of the platform you are trying to query. For example: “Tevreden-platform: autobedrijf” or “Tevreden-platform: autotaalglas”.
Platform List
GET /platforms
Get a list of available platforms and subplatforms.
Example URI
GET https://api.tevreden.nl/platforms
Request
Headers
Tevreden-API-key: {api_key}
Response 200
Body
{
"platforms": [
{
"name": "autobedrijf",
"uri": "https://autobedrijf.tevreden.nl"
"sub_platforms": [
{
"name": "autotaalglas",
"uri": "https://autotaalglas.tevreden.nl"
},
{
"name": "vaartland",
"uri": "https://vaartland.tevreden.nl"
}
]
},
{
"name": "apotheek",
"uri": "https://apotheek.tevreden.nl"
"sub_platforms": [
{
"name": "serviceapotheek",
"uri": "https://serviceapotheek.tevreden.nl"
}
]
}
],
"total": 2
}
Locations
A location (also known as “vestiging”) is the smallest organisational unit that can be defined as a seperate resource. Every Location has it’s own set of questionnaires (these can be requested by GET /questionnaires, described below).
A Location always has the following fields: id (string), organisationid (string), name (string), created (date) en modified (date). A Location can also have a holdingid. It’s also possible to have additional location-attributes like “address”, “zipcode” or “city”.
Multiple Locations
GET
/locations?q={q}&{attrname}={attrvalue}&modified_since={modified_since}&created_since={created_since}&offset={offset}&limit={limit}&order_by={order_by}&dir={dir}
Get a list of Locations.
Example URI
GET https://api.tevreden.nl/locations?q=q&attrname=attrvalue&modified_since=2014-01-01&created_since=2014-01-01&offset=offset&limit=limit&order_by=order_by&dir=dir
URI Parameters
q
string (optional)
Search term. Only Locations with fields that have the value supplied in this paramater will be sent back. The name and all attributes will be matched on this paramater. “Amste” would match Amsterdam as well as Amstelveen for example.
attrname
string (optional)
Name of the attribute that has to be searched on, like “city” or “name”. It’s possible to search on multiple attributes by sending multiple key/value pairs.
attrvalue
string (optional)
Vaue of the supplied attribute, for example “Rotterdam”. This is an exact match which means that city=Amste would not match on anything, city=“Amsterdam” would match “Amsterdam” but not “Amsterdam-Zuidoost”.
modified_since
date (optional) Example: 2014-01-01
Only locations that have been modified since the date supplied (YYYY-MM-DD) (See date formats above)
created_since
date (optional) Example: 2014-01-01
Only locations that are made since the supplied date (YYYY-MM-DD) (See date formats above)
offset
int (optional) Default: 0
Show results back from the number supplied in this paramater. Default is 0
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Request 200
Headers
Tevreden-platform: {platform_name}
Body
{
"locations": [
{
"id": "location id",
"name": "location name",
"organisationid": "organisation id",
"holdingid": "holding id",
"created": "2013-01-01",
"modified": "2013-07-23",
"properties": [
"address": "address",
"zipcode": "1234AB",
"city": "city",
"telephone": "012-345678",
]
}
],
"total": 1
}
Location
GET /locations/{id}
Get a single Location, by using an ID.
Example URI
GET https://api.tevreden.nl/locations/id
URI Parameters
id string (required)
id van de Location
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}Body
{
"location": {
"id": "location id",
"name": "name",
"organisationid": "organisation id",
"holdingid": "holding id",
"created": "2013-01-01",
"modified": "2013-07-23",
"attributes": {
"address": "address",
"zipcode": "1234AB",
"city": "city",
"telephone": "012-345678",
}
}
}
Response 404
Headers
Tevreden-platform: {platform_name}Body
{
"message": "Location with id {id} not found."
}PATCH /locations/{id}
Updates a Location. To change attributes or the name of a Location you can send a JSON hash with new values by using the PATCH method. Attributes not sent in this request will not be altered. It’s not possible to change the ID.
Example URI
PATCH https://api.tevreden.nl/locations/id
URI Parameters
id string (required)
id van de Location
Request
Headers
Content-Type: application/json
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Body
{
"name": "Updated name",
"attributes": {
"telephone": "Updated telephone"
"city": "new city"
}
}
Response 200
Headers
Tevreden-platform: {platform_name}Body
{
"location": {
"id": "location id",
"name": "Updated name",
"attributes": {
"address": "address",
"zipcode": "1234AB",
"city": "new city",
"telephone": "012-345678",
"foo": "bar"
}
}
}
Organisations
An Organisation is a container for Locations. Every Location belongs to an Organisation; there are also Organisations with just 1 Location under it. The Organisation has a name and an id, both of which are strings.
Multiple Organisations ¶
GET /organisations?q={q}&modified_since={modified_since}&created_since={created_since}
Get a list of Organisations, could be filtered.
Example URI
GET https://api.tevreden.nl/organisations?q=q&modified_since=2014-01-01&created_since=2014-01-01
URI Parameters
q
string (optional)
Search term. Only Organisations that match the search term (the name is used) will be returned.
modified_since
date (optional) Example: 2014-01-01
Only get Organisations that are modified since the supplied date (YYYY-MM-DD) (See date formats above)
created_since
date (optional) Example: 2014-01-01
Only get Organisations that are created since the supplied date (YYYY-MM-DD) (See date formats above)
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"organisations": [
{
"id": "organisation id",
"name": "organisation name",
"modified": "2013-01-01",
"created": "2013-01-01"
}
],
"total": 1
}
Single Organisation
GET /organisations/{id}
Get a single Organisation, based on id
Example URI
GET https://api.tevreden.nl/organisations/id
URI Parameters
id
string (required)
id van de Organisation
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}Body
{
"organisation": {
"id": "organisation id",
"name": "name",
"modified": "2013-01-01",
"created": "2013-01-01"
}
}
Response 404
Headers
Tevreden-platform: {platform_name}
Body
{
"message": "Organisation with id {id} not found."
}
PATCH /organisations/{id}
Update an Organisation. Only the name of an Organisation can be changed. The ID can not be changed.
Example URI
PATCH https://api.tevreden.nl/organisations/id
URI Parameters
id
string (required)
id van de Organisation
Request
Headers
Content-Type: application/json
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Body
{
"name": "Updated name"
}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"organisation": {
"id": "organisation id",
"name": "Updated name",
}
}
Holdings
A Holding is the highest possible organisational level and is a container for Organisations. Not every Organisation is part of a Holding; there are even platforms that do not have Holdings at all (contrary to Organisations or Locations which are available in every platform). A Holding has an id and a name, both of which are strings.
Multiple Holdings
GET /holdings?q={q}
Get a list of Holdings, can be filtered.
Example URI
GET https://api.tevreden.nl/holdings?q=q
URI Parameters
q
string (optional)
Search term. Only Holdings matching the search term will be returned.
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"holdings": [
{
"id": "holding id",
"name": "holding name"
}
],
"total": 1
}
Single holding
GET /holdings/{id}
Get a single Holding, based on ID.
Example URI
URI Parameters
id
string (required)
id of the Holding
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"holding": {
"id": "holding id",
"name": "name",
}
}
Response 404
Headers
Tevreden-platform: {platform_name}
Body
{
"message": "Holding with id {id} not found."
}
PATCH /holdings/{id}
Update a Holding. Only the name of a Holding can be changed, the ID cannot be changed.
Example URI
URI Parameters
id
string (required)
id of the Holding
Request
Headers
Content-Type: application/json
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Body
{
"name": "Updated name"
}
Response 200
Headers
Tevreden-platform: {platform_name}Body
{
"holding": {
"id": "holding id",
"name": "Updated name",
}
}
Questionnaires
A Questionnaire is a survey, and it’s a central object within the Tevreden research software.
A Questionnaire resource always has a (unchangeable and unique) id (int) and a subject (string). The subject of a questionnaire can be used to group several questionnaires that have the same form and questions. In results it’s possible to filter on the subject or to split up by using subject. A Questionnaire can belong to a Location or Organisation (and have a specific locationid and/or organisationid). Questionnaires can also have additional attributes which can be different per platform. All attributes are strings.
Single Questionnaire
GET /questionnaires/{id}
Get a single Questionnaire based on ID.
Example URI
GET https://api.tevreden.nl/questionnaires/id
URI Parameters
id
int (required)
id of the Questionnaire
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}Response 200
Headers
Tevreden-platform: {platform_name}Body
{
"questionnaire": {
"id": 123,
"name": "name",
"subject": "subject",
"active": 1,
"locationid": "location id",
"organisationid": "organisation id",
"holdingid": "holding id",
"attributes": {
"foo": "bar",
"boo": "baz"
}
}
}
Response 404
Headers
Tevreden-platform: {platform_name}
Body
{
"message": "Questionnaire with id {id} not found."
}
Platform Questionnaires
GET /questionnaires?limit={limit}&offset={offset}&{attrname}={attrvalue}&group_by_subject={group_by_subject}
Example URI
GET https://api.tevreden.nl/questionnaires?limit=limit&offset=offset&attrname=attrvalue&group_by_subject=group_by_subject
URI ParametersHide
limit
int (optional) Default: 100
Limit the maximum amount of questionnaires returned. Defaults to 100 and has a maximum of 1500.
offset
int (optional) Default: 0
Return Questionnaires offset from number.
attrname
string (optional)
Name of the attribute that needs to be filtered on. It’s possible to filter on multiple attributes by sending multiple key/value pairs.
attrvalue
string (optional)
Value of a supplied attribute that needs to be filtered on. This is an exact match, not a partial one.
group_by_subject
boolean (optional) Default: 0
Group Questionnaires based on subject. In this specific case a list will be returned of unique questionnaire_subjects.
Request group_by_subject=0
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"questionnaires": [
{
"id": 123,
"subject": "01 Evaluatie na aanmelding",
"active": 1,
"locationid": "location id",
"organisationid": "organisation id",
"holdingid": "holding id",
"nr_reactions": 12345,
"attributes": {
"foo": "bar",
"boo": "baz"
}
},
{
"id": 456,
"subject": "02 Evaluatie na twee maanden",
"active": 1,
"locationid": "location id",
"organisationid": "organisation id",
"holdingid": "holding id",
"nr_reactions": 12345,
"attributes": {
"foo": "bar",
"boo": "baz"
}
},
{
"id": 789,
"name": "name",
"subject": "03 Evaluatie na uitschrijving",
"active": 1,
"locationid": "location id",
"organisationid": "organisation id",
"holdingid": "holding id",
"nr_reactions": 12345,
"attributes": {
"foo": "bar",
"boo": "baz"
}
},
],
"total": 1
}
Request group_by_subject=1
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Reponse 200
Headers
Tevreden-platform: {platform_name}
Body
{
"questionnaire_subjects": [
"01 Evaluatie na aanmelding",
"02 Evaluatie na twee maanden",
"03 Evaluatie na uitschrijving"
],
"total": 3
}Holding Questionnaires
GET /questionnaires/holding/{holdingid}?limit={limit}&offset={offset}&{attrname}={attrvalue}&group_by_subject={group_by_subject}
Example URI
URI Parameters
holdingid
string (required)
id of the Holding.
limit
int (optional) Default: 100
Limit maximum amount of questionnaires, defaults to 100 with a maximum of 1000.
offset
int (optional) Default: 0
Return Questionnaires offset from number.
attrname
string (optional)
Name of the attribute that needs to be filtered on. It’s possible to filter on multiple attributes by sending multiple key/value pairs.
attrvalue
string (optional)
Value of a supplied attribute that needs to be filtered on. This is an exact match, not a partial one.
group_by_subject
boolean (optional) Default: 0
Group Questionnaires based on subject. In this specific case a list will be returned of unique questionnaire_subjects.
Request group_by_subject=0
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"questionnaires": [
{
"id": 123,
"subject": "01 Evaluatie na aanmelding",
"active": 1,
"locationid": "location id",
"organisationid": "organisation id",
"holdingid": "holding id",
"attributes": {
"foo": "bar",
"boo": "baz"
}
},
{
"id": 456,
"subject": "02 Evaluatie na twee maanden",
"active": 1,
"locationid": "location id",
"organisationid": "organisation id",
"holdingid": "holding id",
"attributes": {
"foo": "bar",
"boo": "baz"
}
},
{
"id": 789,
"name": "name",
"subject": "03 Evaluatie na uitschrijving",
"active": 1,
"locationid": "location id",
"organisationid": "organisation id",
"holdingid": "holding id",
"attributes": {
"foo": "bar",
"boo": "baz"
}
},
],
"total": 3
}
Request group_by_subject=1
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"questionnaire_subjects": [
"01 Evaluatie na aanmelding",
"02 Evaluatie na twee maanden",
"03 Evaluatie na uitschrijving"
],
"total": 3
}
Organisation Questionnaires
GET questionnaires/organisation/{organisationid}?limit={limit}&offset={offset}&{attrname}={attrvalue}&group_by_subject={group_by_subject}
Example URI
GET https://api.tevreden.nl/questionnaires/organisation/organisationid?limit=limit&offset=offset&attrname=attrvalue&group_by_subject=group_by_subject
URI Parameters
organisationid
string (required)
id of the Organisation.
limit
int (optional) Default: 100
Limit maximum amount of questionnaires, defaults to 100 with a maximum of 1000.
offset
int (optional) Default: 0
Return Questionnaires offset from number.
attrname
string (optional)
Name of the attribute that needs to be filtered on. It’s possible to filter on multiple attributes by sending multiple key/value pairs.
attrvalue
string (optional)
Value of a supplied attribute that needs to be filtered on. This is an exact match, not a partial one.
group_by_subject
boolean (optional) Default: 0
Group Questionnaires based on subject. In this specific case a list will be returned of unique questionnaire_subjects.
Request group_by_subject=0
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"questionnaires": [
{
"id": 123,
"subject": "01 Evaluatie na aanmelding",
"active": 1,
"locationid": "location id",
"organisationid": "organisation id",
"holdingid": "holding id",
"nr_reactions": 12345,
"attributes": {
"foo": "bar",
"boo": "baz"
}
},
{
"id": 456,
"subject": "02 Evaluatie na twee maanden",
"active": 1,
"locationid": "location id",
"organisationid": "organisation id",
"holdingid": "holding id",
"nr_reactions": 12345,
"attributes": {
"foo": "bar",
"boo": "baz"
}
},
{
"id": 789,
"name": "name",
"subject": "03 Evaluatie na uitschrijving",
"active": 1,
"locationid": "location id",
"organisationid": "organisation id",
"holdingid": "holding id",
"nr_reactions": 12345,
"attributes": {
"foo": "bar",
"boo": "baz"
}
},
],
"total": 3
}
Location Questionnaires
GET questionnaires/location/{locationid}?limit={limit}&offset={offset}&{attrname}={attrvalue}&group_by_subject={group_by_subject}
Example URI
GET https://api.tevreden.nl/questionnaires/location/locationid?limit=limit&offset=offset&attrname=attrvalue&group_by_subject=group_by_subject
URI Parameters
locationid
string (required)
id of a Location.
limit
int (optional) Default: 100
Limit maximum amount of questionnaires, defaults to 100 with a maximum of 1000.
offset
int (optional) Default: 0
Return Questionnaires offset from number.
attrname
string (optional)
Name of the attribute that needs to be filtered on. It’s possible to filter on multiple attributes by sending multiple key/value pairs.
attrvalue
string (optional)
Value of a supplied attribute that needs to be filtered on. This is an exact match, not a partial one.
group_by_subject
boolean (optional) Default: 0
Group Questionnaires based on subject. In this specific case a list will be returned of unique questionnaire_subjects.
Request group_by_subject=0
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"questionnaires": [
{
"id": 123,
"subject": "01 Evaluatie na aanmelding",
"active": 1,
"locationid": "location id",
"organisationid": "organisation id",
"holdingid": "holding id",
"nr_reactions": 12345,
"attributes": {
"foo": "bar",
"boo": "baz"
}
},
{
"id": 456,
"subject": "02 Evaluatie na twee maanden",
"active": 1,
"locationid": "location id",
"organisationid": "organisation id",
"holdingid": "holding id",
"nr_reactions": 12345,
"attributes": {
"foo": "bar",
"boo": "baz"
}
},
{
"id": 789,
"name": "name",
"subject": "03 Evaluatie na uitschrijving",
"active": 1,
"locationid": "location id",
"organisationid": "organisation id",
"holdingid": "holding id",
"nr_reactions": 12345,
"attributes": {
"foo": "bar",
"boo": "baz"
}
},
],
"total": 3
}
Request group_by_subject=1
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"questionnaire_subjects": [
"01 Evaluatie na aanmelding",
"02 Evaluatie na twee maanden",
"03 Evaluatie na uitschrijving"
],
"total": 3
}
Invitations
An invitation is used to invite a recipient to fill in a questionnaire. The core of an invitation is a link (url) to the questionnaire. This link can only be used once; if the questionnaire is filled in, the link will become unusable. For every invitation created in the system a recipient is also created. Attributes can be added to a recipient, for example, name, sex, city etc. Depending on the type of invitation (see below) some attributes can be required.
In this API we currently support the following types of invitations:
web: A web-reaction is a reaction given through one of the websites. In this case a recipient invites themselves by filling in data like name and emailaddress and after that recieves a email with the link to the questionnaire. This form of inviting is accessible by everyone, for all public Questionnaires.
email: An invite by mail created by a user of the platform. When using this method of inviting you invite someone else, not yourself. This is the default option.
link: This option only generates a direct link to the questionnaire. This then can be used inside an own email, webpage, app, etc.
code: This option only generates a code. By filling in this code on the public websites an respondent will be redirected to the questionnaire. This code can be used on flyers for example.
preview: This is a special type of invite, it’s a link and a code just to check and test the questionnaire. Reactions to this type of invite will not be saved.
CREATE INVITATIONS FOR A SINGLE QUESTIONNAIRE ¶
This call can be used to create (an) invitation(s) for one specific questionnaire. The id of the questionnaire is specified in the uri; you can get the id you need using the GET /questionnaires call.
Invitations can be created one at a time, or multiple in batch. For every invitation, a set of recipient fields (name/value pairs) is needed. This set must at least contain all required=1 fields from the GET /invitations/questionnaire/{questionnaireid}/fields call. The data can be sent in various formats. The response will always be in JSON format, regardless of the request format.
The JSON response will contain a key “success” with a boolean value, which will be false if no invitation at all was created. If at least one invitation was successfully created, “success” will be true. This does not necessarily mean that an invitation was created for all recipients. It is therefore recommended to inspect the content of the “not_created” array in the response.
POST array: only for a web invitation (type=web). Send all the fields in a POST array, as url encoded key/value pairs (Content-type: application/x-www-form-urlencoded). Only one recipient per request possible.
JSON format: Send the data as a JSON object (Content-type: application/json). This object should contain a “recipients” key, with an array of recipient objects. A recipient object contains name/values for at least all required fields. All (optional) url parameters except type can also be specified/overridden using keys in the JSON object; globally or per recipient.
CSV format: Send the data as a CSV (Comma Separated Values) file (Content-type: text/csv). The first row should contain the names of the recipient fields, and the following rows contain the values, one row for one recipient. All fields are separated by a comma. If the value itself contains a comma it should be enclosed by double quotes. See https://metacpan.org/pod/Text::CSV_XS#SPECIFICATION for more information about the CSV format and specification followed by the Tevreden API. All (optional) url parameters except type can also be specified/overridden per recipient.
XLS(X) format: Send the data as a Microsoft Excel spreadsheet. Both the Excel 97 - Excel 2003 (Content-type: application/vnd.ms-excel) and the OpenXML (Content-type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet) format is supported. The first row on the first workbook should contain the names of the recipient fields, and the following rows contain the values, one row for one recipient. All (optional) url parameters except type can also be specified/overridden per recipient.
POST
/invitations/questionnaire/{questionnaireid}?type={type}&send_date={send_date}&queue_reminder={queue_reminder}&reminder_date={reminder_date}&filter_duplicates={filter_duplicates}&filter_duplicates_start_date={filter_duplicates_start_date}&filter_duplicates_end_date={filter_duplicates_end_date}&dry_run={dry_run}&generate_xls={generate_xls}&xls_basename={xls_basename}
Example URI
POST https://api.tevreden.nl/invitations/questionnaire/questionnaireid?type=type&send_date=send_date&queue_reminder=queue_reminder&reminder_date=reminder_date&filter_duplicates=filter_duplicates&filter_duplicates_start_date=filter_duplicates_start_date&filter_duplicates_end_date=filter_duplicates_end_date&dry_run=dry_run&generate_xls=generate_xls&xls_basename=xls_basename
URI Parameters
questionnaireid
int (required)
id of the Questionnaire. The ids of available questionnaires can be retrieved by doing a GET /questionnaires call.
type
string (optional) Default: email
Can be one of web, email, link, code, preview. Default is email. See above for more information about the types.
send_date
string (optional) Default: now
Only for type email. The datetime when to send the email. If empty or invalid or in the past, the invitation will be created and sent as soon as possible, next round of sending.
queue_reminder
boolean (optional) Default: 0
Only applicable for type email. If true queue a reminder 5 days after the senddate of the first invitation. For a custom reminder period, use the reminder date parameter.
reminder_date
string (optional)
Only for type email. The datetime when to send the reminder email. Has to be after the send date, if left empty or invalid, no reminder will be queued.
filter_duplicates
boolean (optional) Default: 0
Only for type email. If this field is true, a check will be done if the recipient was previously invited for this questionnaire. The time period to check is configurable, see below. Filtering is done on the recipient field email.
filter_duplicates_start_date
string (optional)
Only for type email and only in combination with filter duplicates. The start date is the start date of the period that needs to be checked whether a recipient was already invited.
filter_duplicates_end_date
string (optional)
Only for type email and only in combination with filter duplicates. The end date is the end date of the period that needs to be checked whether a recipient was already invited.
dry_run
boolean (optional) Default: 0
If this argument is 1 then a dry run (test) is performed. No invitations are created, and the json response will tell you what would have happened if this was not a dry run.
generate_xls
boolean (optional) Default: 0
Optionally generate an XLS report with the results of the API call. This file will contain the same data as in the JSON response. The key “xls” in the JSON response will contain a link where the file can be downloaded. The XLS file will also be downloadable from the report library in your user portal.
xls_basename
string (optional) Default: invitations result
Custom basename for the generated xls file. Default/if not specified the name will be ‘invitations result ..xlsx’. The value of this argument may only contain letters, numbers, spaces, periods, underscores and/or hyphens. Other characters will be removed.
Request
Headers
Content-Type: application/x-www-form-urlencoded
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Body
naam%3DDhr.%20Example%26email%3Dexample%40domain.com%26geslacht%3DM%26uzovi_code%3D3328
Response 201
Headers
Tevreden-platform: {platform_name}Body
{
"success": true,
"message: "The invitation has been sent to example@domain.com.",
"send_date": "2015-02-20T15:25:43",
"reminder_date": null,
"questionnaireid": "{questionnaireid}",
"recipient": {
"naam": "Dhr. Example"
"email": "example@domain.com"
"geslacht": "M",
"uzovi_code": "3328"
}
}
Request
Headers
Content-Type: application/x-www-form-urlencoded
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Body
naam%3DDhr.%20Example
Response 400
Headers
Tevreden-platform: {platform_name}Body
{
"success": false,
"message": "Not all required fields are submitted. The missing fields are specified in the key missing_fields.",
"missing_fields": [
"email",
"uzovi_code"
],
"questionnaireid": "{questionnaireid}",
"recipient": {
"naam": "Mr. Example"
}
}
Request
Headers
Content-Type: application/json
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Body
{
"type": "email",
"send_date": "2015-03-01 12:00:00",
"queue_reminder": 1,
"filter_duplicates": 1,
"filter_duplicates_start_date": "2015-01-01",
"filter_duplicates_end_date": "today",
"recipients": [
{
"naam": "Mr. Example",
"email": "name@domain.ext",
"geslacht": "M"
},
{
"naam": "Miss Example",
"email": "name2@domain2.ext"
},
{
"naam": "Mr Robot",
"email": "elliot@allsafe.company",
"geslacht": "M",
"send_date": "2015-04-01 12:00:00",
"reminder_date": "2015-04-08 12:00:00",
"filter_duplicates": 0
},
{
"naam": "Mr. Duplicate Example",
"email": "name@domain.ext",
"geslacht": "M"
}
]
}
Response 201
Headers
Content-type: application/json
Tevreden-platform: {platform_name}
Body
{
"success": true,
"message": "Request processed successfully, 2 invitation(s) and 2 reminder(s) created.",
"created": [
{
"message": "The invitation has been queued for sending."
"send_date": "2015-03-01 12:00:00",
"reminder_date": "2015-03-06 12:00:00",
"questionnaireid": "{questionnaireid}",
"recipient": {
"naam": "Mr. Example",
"email": "name@domain.ext",
"geslacht": "M"
}
},
{
"message": "The invitation has been queued for sending."
"send_date": "2015-04-01 12:00:00",
"reminder_date": "2015-04-08 12:00:00",
"questionnaireid": "{questionnaireid}",
"recipient": {
"naam": "Mr Robot",
"email": "elliot@allsafe.company",
"geslacht": "M",
}
}
],
"not_created": [
{
"message": "Not all required fields are submitted. The missing fields are specified in the key missing_fields.",
"questionnaireid": "{questionnaireid}",
"missing_fields": [
"geslacht"
],
"recipient": {
"naam": "Miss Example",
"email": "name2@domain2.ext",
}
},
{
"message": "This email address has already been imported between 2015-01-01 and today for this questionnaire.",
"questionnaireid": "{questionnaireid}",
"recipient": {
"naam": "Mr. Duplicate Example",
"email": "name@domain.ext",
"geslacht": "M"
}
}
]
}
Request
Headers
Content-Type: text/csv
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Body
naam,email,geslacht,send_date,reminder_date Mr. Example,example@domain.ext,M,2017-01-01,2017-01-08
Response 201
Headers
Content-type: application/json
Tevreden-platform: {platform_name}
Body
{
"success": true,
"message": "Request processed successfully, 1 invitation(s) and 1 reminder(s) created.",
"created": [
{
"message": "The invitation has been queued for sending."
"send_date": "2017-01-01 00:00:00",
"reminder_date": "2017-01-08 00:00:00",
"questionnaireid": "{questionnaireid}",
"recipient": {
"naam": "Mr. Example",
"email": "name@domain.ext",
"geslacht": "M"
}
}
],
"not_created": []
}
CREATE INVITATIONS FOR MULTIPLE QUESTIONNAIRES ¶
If you want to create invitations for more than a single questionnaire, or if you don’t know the id of the questionnaire you need, you can use this call. You can specify the questionnaire using the following ways:
globally, using the uri parameter questionnaireid: this is equivalent to the single questionnaire call above;
globally, using questionnaire attributes in the uri: For example: “QuestionnaireSubject=Evaluation%20after%20three%20months”.
per recipient, using an extra column “questionnaireid”
per recipient, using one or more name/value pairs to identify a single questionnaire. To prevent ambiguity with recipient fields, you need to prefix the attributename (the column in the csv/xls) with “questionnaire.”. For example, create a column “questionnaire.QuestionnaireSubject” with the relevant values per recipient. Empty values will be skipped.
For every recipient, there must be exactly one matching questionnaire. If no questionnaire matches, or more than one questionnaire matches, no invitation is created.
Use the dry_run=1 argument to test beforehand whether the matching works like intended. You can also test the matching beforehand using a GET /questionnaires call, which works in the same way.
For every invitation, a set of recipient fields (name/value pairs) is needed. This set must at least contain all required=1 fields from the GET /invitations/questionnaire/{questionnaireid}/fields call.
The data can be sent in various formats. The response will always be in JSON format, regardless of the request format.
JSON format: Send the data as a JSON object (Content-type: application/json). This object should contain a “recipients” key, with an array of recipient objects. A recipient object contains name/values for at least all required fields, and optionally a questionnaireid or one or more questionnaire.* fields. All (optional) url parameters except type can also be specified/overridden using keys in the JSON object; globally or per recipient.
CSV format: Send the data as a CSV (Comma Separated Values) file (Content-type: text/csv). The first row should contain the names of the recipient fields and optionally a questionnaireid or one or more questionnaire.* fields. The following rows contain the values, one row for one recipient. All fields are separated by a comma. If the value itself contains a comma it should be enclosed by double quotes. See https://metacpan.org/pod/Text::CSV_XS#SPECIFICATION for more information about the CSV format and specification followed by the Tevreden API. All (optional) url parameters except type can also be specified/overridden per recipient.
XLS(X) format: Send the data as a Microsoft Excel spreadsheet. Both the Excel 97 - Excel 2003 (Content-type: application/vnd.ms-excel) and the OpenXML (Content-type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet) format is supported. The first row on the first workbook should contain the names of the recipient fields, and optionally a questionnaireid or one or more questionnaire.* fields. The following rows contain the values, one row for one recipient. All (optional) url parameters except type can also be specified/overridden per recipient.
POST (Create invitations for multiple questionnaires)
/invitations?type={type}&send_date={send_date}&queue_reminder={queue_reminder}&reminder_date={reminder_date}&filter_duplicates={filter_duplicates}&filter_duplicates_start_date={filter_duplicates_start_date}&filter_duplicates_end_date={filter_duplicates_end_date}&questionnaireid={questionnaireid}&{qnattrname}={qnattrvalue}&dry_run={dry_run}&generate_xls={generate_xls}&xls_basename={xls_basename}
Example URI
URI Parameters
type
string (optional) Default: email
Can be one of web, email, link, code, preview. Default is email. See above for more information about the types.
send_date
string (optional) Default: now
Only for type email. The datetime when to send the email. If empty or invalid or in the past, the invitation will be created and sent as soon as possible (next round of sending).
queue_reminder
boolean (optional) Default: 0
Only applicable for type email. If true queue a reminder 5 days after the senddate of the first invitation.
reminder_date
string (optional)
Only for type email. The datetime when to send the reminder email. Has to be after the send date, if left empty or invalid, no reminder will be queued.
filter_duplicates
boolean (optional) Default: 0
Only for type email. If this field is true, a check will be done if the recipient was previously invited for this questionnaire. The time period to check is configurable, see below. Filtering is done on the recipient field email.
filter_duplicates_start_date
string (optional)
Only for type email and only in combination with filter duplicates. The start date is the start date of the period that needs to be checked whether a recipient was already invited.
filter_duplicates_end_date
string (optional)
Only for type email and only in combination with filter duplicates. The end date is the end date of the period that needs to be checked whether a recipient was already invited.
questionnaireid
int (optional)
id of the Questionnaire. The ids of available questionnaires can be retrieved by doing a GET /questionnaires call.
qnattrname
string (optional)
The name of a questionnaire attribute to match one questionnaire
qnattrvalue
string (optional)
Request
Headers
Content-Type: text/csv
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Body
naam,email,questionnaire.Regio,questionnaire.OnderzoeksType
Mr. Example,example@domain.ext,Oost,KTO
Ms. Example2,example2@domain2.ext,West,MTO
Mr. Example3,example4@domain3.ext,,KTO
Ms. Example4,example5@domain4.ext,foo,bar
Response 201
Headers
Content-type: application/json
Tevreden-platform: {platform_name}
Body
{
"success": true,
"message": "Request processed successfully, 2 invitation(s) created.",
"created": [
{
"message": "The invitation has been queued for sending."
"send_date": "now",
"questionnaireid": "{questionnaireid1}",
"recipient": {
"naam": "Mr. Example",
"email": "example@domain.ext"
}
},
{
"message": "The invitation has been queued for sending."
"send_date": "now",
"questionnaireid": "{questionnaireid2}",
"recipient": {
"naam": "Ms. Example2",
"email": "example2@domain2.ext"
}
}
],
"not_created": [
{
"message": "No invitation created: more than one questionnaire found for OnderzoeksType=KTO."
"questionnaireid": undefined,
"recipient": {
"naam": "Mr. Example3",
"email": "example3@domain3.ext"
}
},
{
"message": "No invitation created: no questionnaire found for Regio=foo and OnderzoeksType=bar"
"questionnaireid": undefined,
"recipient": {
"naam": "Ms. Example4",
"email": "example4@domain4.ext"
}
},
]
}
CREATE A PREVIEW OF AN INVITATION ¶
With this endpoint you can send a preview of the invitation to an email address (like your own). The invitation will contain a functional link to the questionnaire, however, your reaction will not be saved. Along with this call you can optionally submit key/value pairs for the invitation fields (see below). The email address along with any invitation fields can be submitted as uri parameter, post parameter, or in a json object.
POST (Create a preview of an invitation)
/invitations/questionnaire/{questionnaireid}/preview?email={email}
Example URI
URI Parameters
questionnaireid
int (required)
id of the Questionnaire. The ids of available questionnaires can be retrieved by doing a GET /questionnaires call.
string (required)
the email address to send the preview to.
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Content-Type: application/json
Body
{
"email": "my@email.address",
"naam": "Mr. Preview"
}
Response 201
Headers
Tevreden-platform: {platform_name}
Body
{
"success": "1",
"message": "Preview message sent to my@email.address"
}
GET STATUS OF AN INVITATION ¶
If you use the api to create userlinks or invitation codes (type=link or type=code, see above) you can use this endpoint to get the status of an invitation; it will return a reaction object if the recipient clicked the link or used the code. This object will contain a key ‘created’ (when the recipient opened the questionnaire for the first time), ‘modified’ (when the reaction was last modified), and a boolean ‘finished’. A reaction is finished when the recipient clicks submit on the last page of the questionnaire, after which the reaction cannot be modified anymore.
If there is no reaction yet, the reaction key will be undefined. If the invitation cannot be found, a 404 Not Found status will be returned.
GET /invitations/status/{invitationcode} (Get status of an invitation)
Example URI
URI Parameters
invitationcode
string (required)
the code of the invitation, obtained by a POST /invitations call. This code is only returned for invitations of type “code” or “link” so it is not possible to get the status for email invitations. Fe: 123456-7890
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
reaction: {
created: '2017-02-03 12:34:56',
modified: '2017-02-03 12:34:56',
finished: 0
}
}
Response 404
Headers
Tevreden-platform: {platform_name}
Body
{
"message": "invitation with code {invitationcode} not found."
}
GET INVITATION FIELDS ¶
For every invitation a set of fields (name/value pairs) is needed. These can be different per platform, questionnaire or type of invitation. Use this call to get a list of all fields for a specific questionnaire. A field can have the type “text” (every value is permitted) or there can be a list of possible options (type “select” or “radio”). Fields can be required (required=1) or optional (required=0).
GET/invitations/questionnaire/{questionnaireid}/fields?type={type}
Example URI
URI Parameters
questionnaireid
int (required)
id of the Questionnaire. This ID can be requested by using a GET /questionnaires call.
type
string (optional) Default: email
the type of invitation. Possible values: “web”, “email”, “link” or “preview”.
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"fields": [
{
"desc": "aanhef",
"required": 0,
"name": "aanhef",
"type": "text"
},
{
"type": "text",
"name": "achternaam",
"required": 0,
"desc": "achternaam"
},
{
"name": "email",
"type": "text",
"desc": "email",
"required": 1
},
{
"required": 0,
"desc": "geslacht",
"type": "text",
"name": "geslacht"
},
{
"required": 0,
"desc": "leeftijd",
"type": "text",
"name": "leeftijd"
},
{
"type": "text",
"name": "woonplaats",
"required": 0,
"desc": "woonplaats"
}
]
}
Reactions
A Reaction is an individual response on a Questionnaire. A Reaction contains the following fields:
id: Unique and unchangeable identifier for this reaction (int)nr: The reactions follow number. This follow number is seperate from the id, and is mostly cosmetical; it can vary depending on the filters used. This field can not be used for filtering, use the id field for filtering.date: Date/time of the reaction in RFC3339-format (YYYY-MM-DD hh:mm:ss)questionnaire: Data of the corresponding questionnaire.recipient: Data of the corresponding recipient/respondent. The amount of data shown is dependant on what data is available and a white list which is managed by Tevreden.location: Data of the corresponding Location.status(int): Reactions go through a moderation proces and get a status.0: Not (yet) moderated. These reactions cannot be requested through this API.
1: The reaction has a grade and a approved review.
2: The reaction has a grade, but no review or the review has been rejected.
3: The whole reaction has been rejected for publication. These reactions are not (yet) requestable through the API.
moderation_date: The date/time on which the reaction was moderated for the last time (or changed status).source(string): The source of the reaction (the type of invitation). This could be: ‘email’ (through email invite), ‘web’ (through one of the public websites), ‘flyer’ (through a code/flyer), ‘import’ (imported manually), ‘webservice’ (through a link generated by the api/webservice) or ‘unknown’.summary: The summary contains the most important answer-elements of the reaction:grade: The answer on the grade question (int, between 1 and 10).recommendation: The answer on the Net Promotor Score-question (int, between 1 and 10).review: The textual review (only if status=1).question_subjects: Questionnaires containt one or more blocks of multiple choice-questions about a certainquestion subjectortheme. For example the satisfaction about the reception or the facilities. Per question subject / theme an average is returned (float, usually between 1 and 5).extra_elements: Next to the reaction elements described above, Tevreden can add one or more questions per questionnaire, which are grouped on a keyword / short description. This can be open questions as well as multiple choice-questions.
SINGLE REACTION ¶
GET/reactions/{id}?questionsubjects_rescale={questionsubjects_rescale}
Get a single Reaction based on ID.
Example URI
URI Parameters
id
int (required)
id of the Reaction
questionsubjects_rescale
string (optional)
if TRUE the returned data represents the questionsubjects in the scale indicated eg 1-10, 1-5. If not recognizable as a scale, a 1-10 scale is assumed. If empty, the questionsubjects in the data are unaltered, usually 1-5
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}Body
{
"reaction": {
"id": 123,
"nr": 12,
"date": "2014-01-02 12:34",
"questionnaire": {
"id": "123",
"subject": "questionnaire subject"
},
"recipient": {
"woonplaats": "Rotterdam",
"geslacht": "M"
},
"location": {
"id": "location id",
"name": "Location name"
}
"status": 1,
"moderation_date": "2014-01-02 12:34",
"source": "email",
"summary": {
"grade": 8,
"recommendation": 8,
"review": "review text",
"question_subjects": {
"subject1": 6.3,
"subject2": 7.4,
"subject3": 8.1
},
"extra_elements": {
"keyword1": 6.7,
"keyword2": "open answer"
}
}
}
}
Response 404
Headers
Tevreden-platform: {platform_name}
Body
{
"message": "Reaction with id {id} not found."
}
GET ALL REACTIONS
GET /reactions?start_date={start_date}&end_date={end_date}&limit={limit}&offset={offset}&dir={dir}&questionnaire_subject={questionnaire_subject}&status={status}&moderated_since={moderated_since}&source={source}&questionsubjects_rescale={questionsubjects_rescale}
URI ParametersHide
start_date
string (optional)
Only show reactions from this startdate, format YYYY-MM-DD.
end_date
string (optional)
Only show reactions up until this enddate, format YYYY-MM-DD.
offset
int (optional) Default: 0
Return reactions with an offset from number. Defaults to 0 (from the beginning).
limit
int (optional) Default: 200
Limit the maximum amount of reactions. Defaults to 200 with a maximum of 1000.
dir
string (optional) Default: desc
Order direction of the reactions, by reactiondate.
Choices: desc asc
questionnaire_subjectstring (optional)
Filter reactions on questionnairesubject.
status
int (optional)
Filter reacties with this particular status.
Choices: 1 2
moderated_since
string (optional)
Only give reactions that are moderated after this date (YYYY-MM-DD)
source string (optional)
Filter reactions based on source. This argument can be used multiple times, for example source=email&source=web.
Choices: email web flyer import webservice
questionsubjects_rescale
string (optional)
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"reactions": [
{
"id": 123,
"nr": 12,
"date": "2014-01-02 12:34",
"questionnaire": {
"id": "123",
"subject": "questionnaire subject"
},
"recipient": {
"woonplaats": "Rotterdam",
"geslacht": "M"
},
"location": {
"id": "location id",
"name": "Location name"
}
"status": 1,
"moderation_date": "2014-01-02 12:34",
"source": "email",
"summary": {
"grade": 8,
"recommendation": 8,
"review": "review text",
"question_subjects": {
"subject1": 6.3,
"subject2": 7.4,
"subject3": 8.1
}
}
},
{
"id": 456,
"nr": 11,
"date": "2014-02-02 12:34",
"questionnaire": {
"id": "123",
"subject": "questionnaire subject"
},
"recipient": {
"woonplaats": "Rotterdam",
"geslacht": "M"
},
"location": {
"id": "location id",
"name": "Location name"
}
"status": 1,
"moderation_date": "2014-01-02 12:34",
"source": "web",
"summary": {
"grade": 8,
"recommendation": 8,
"review": "review text",
"question_subjects": {
"subject1": 6.3,
"subject2": 7.4,
"subject3": 8.1
}
}
}
],
"total": 2
}
HOLDING REACTIONS ¶
GET Holding Reactions
/reactions/holding/{holdingid}?start_date={start_date}&end_date={end_date}&limit={limit}&offset={offset}&dir={dir}&questionnaire_subject={questionnaire_subject}&status={status}&moderated_since={moderated_since}&source={source}&questionsubjects_rescale={questionsubjects_rescale}
Example URI
URI Parameters
holdingid
string (required)
ID of the holding
start_date
string (optional)
Only show reactions from this startdate, format YYYY-MM-DD.
end_date
string (optional)
Only show reactions up until this enddate, format YYYY-MM-DD.
offset
int (optional) Default: 0
Return reactions with an offset from number. Defaults to 0 (from the beginning).
limit
int (optional) Default: 100
Limit the maximum amount of reactions. Defaults to 100 with a maximum of 1000.
dir
string (optional) Default: desc
Order direction of the reactions, by reactiondate. Can be desc (default, descending, newest first) or asc (ascending, oldest first).
Choices: desc asc
questionnaire_subject
string (optional)
Filter reactions on questionnairesubject.
status
int (optional)
Filter reactions with this particular status.
Choices: 1 2
moderated_since
string (optional)
Only give reactions that are moderated after this date (YYYY-MM-DD)
source
string (optional)
Filter reactions based on source. This argument can be used multiple times, for example source=email&source=web.
Choices: email web flyer import webservice
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"reactions": [
{
"id": "123",
"nr": 12,
"date": "2014-01-02 12:34",
"questionnaire": {
"id": "123",
"subject": "questionnaire subject"
},
"recipient": {
"woonplaats": "Rotterdam",
"geslacht": "M"
},
"location": {
"id": "location id",
"name": "Location name"
}
"status": 1,
"moderation_date": "2014-01-02 12:34",
"source": "email",
"summary": {
"grade": 8,
"recommendation": 8,
"review": "review text",
"question_subjects": {
"subject1": 6.3,
"subject2": 7.4,
"subject3": 8.1
}
}
},
{
"id": 456,
"nr": 11,
"date": "2014-02-02 12:34",
"questionnaire": {
"id": "123",
"subject": "questionnaire subject"
},
"recipient": {
"woonplaats": "Rotterdam",
"geslacht": "M"
},
"location": {
"id": "location id",
"name": "Location name"
}
"status": 1,
"moderation_date": "2014-01-02 12:34",
"source": "web",
"summary": {
"grade": 8,
"recommendation": 8,
"review": "review text",
"question_subjects": {
"subject1": 6.3,
"subject2": 7.4,
"subject3": 8.1
}
}
}
],
"total": 2
}
ORGANISATION REACTIONS ¶
GET /reactions/organisation/{organisationid}?start_date={start_date}&end_date={end_date}&limit={limit}&offset={offset}&dir={dir}&questionnaire_subject={questionnaire_subject}&status={status}&moderated_since={moderated_since}&source={source}&questionsubjects_rescale={questionsubjects_rescale}
Example URI
GET https://api.tevreden.nl/reactions/organisation/organisationid?start_date=start_date&end_date=end_date&limit=limit&offset=offset&dir=dir&questionnaire_subject=questionnaire_subject&status=status&moderated_since=moderated_since&source=source&questionsubjects_rescale=questionsubjects_rescale
URI Parameters
organisationid
string (required)
id of the Organisation
start_date
string (optional)
Only show reactions from this startdate, format YYYY-MM-DD.
end_date
string (optional)
Only show reactions up until this enddate, format YYYY-MM-DD.
offset
int (optional) Default: 0
Return reactions with an offset from number. Defaults to 0 (from the beginning).
limit
int (optional) Default: 100
Limit the maximum amount of reactions. Defaults to 100 with a maximum of 1000.
dir
string (optional) Default: desc
Order direction of the reactions, by reactiondate. Can be desc (default, descending, newest first) or asc (ascending, oldest first).
Choices: desc asc
questionnaire_subject
string (optional)
Filter reactions on questionnairesubject.
status
int (optional)
Filter reactions with this particular status.
Choices: 1 2
moderated_since
string (optional)
Only give reactions that are moderated after this date (YYYY-MM-DD)
source
string (optional)
Filter reactions based on source. This argument can be used multiple times, for example source=email&source=web.
Choices: email web flyer import webservice
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"reactions": [
{
"id": "123",
"nr": 12,
"date": "2014-01-02 12:34",
"questionnaire": {
"id": "123",
"subject": "questionnaire subject"
},
"recipient": {
"woonplaats": "Rotterdam",
"geslacht": "M"
},
"location": {
"id": "location id",
"name": "Location name"
}
"status": 1,
"moderation_date": "2014-01-02 12:34",
"source": "email",
"summary": {
"grade": 8,
"recommendation": 8,
"review": "review text",
"question_subjects": {
"subject1": 6.3,
"subject2": 7.4,
"subject3": 8.1
}
}
},
{
"id": 456,
"nr": 11,
"date": "2014-02-02 12:34",
"questionnaire": {
"id": "123",
"subject": "questionnaire subject"
},
"recipient": {
"woonplaats": "Rotterdam",
"geslacht": "M"
},
"location": {
"id": "location id",
"name": "Location name"
}
"status": 1,
"moderation_date": "2014-01-02 12:34",
"source": "email",
"summary": {
"grade": 8,
"recommendation": 8,
"review": "review text",
"question_subjects": {
"subject1": 6.3,
"subject2": 7.4,
"subject3": 8.1
}
}
}
],
"total": 2
}
LOCATION REACTIONS ¶
GET /reactions/location/{locationid}?start_date={start_date}&end_date={end_date}&limit={limit}&offset={offset}&dir={dir}&questionnaire_subject={questionnaire_subject}&status={status}&moderated_since={moderated_since}&source={source}&questionsubjects_rescale={questionsubjects_rescale}
Example URI
URI Parameters
locationid
string (required)
id of the Location
start_date
string (optional)
Only show reactions from this startdate, format YYYY-MM-DD.
end_date
string (optional)
Only show reactions up until this enddate, format YYYY-MM-DD.
offset
int (optional) Default: 0
Return reactions with an offset from number. Defaults to 0 (from the beginning).
limit
int (optional) Default: 100
Limit the maximum amount of reactions. Defaults to 100 with a maximum of 1000.
dir
string (optional) Default: desc
Order direction of the reactions, by reactiondate. Can be desc (default, descending, newest first) or asc (ascending, oldest first).
Choices: desc asc
questionnaire_subject
string (optional)
Filter reactions on questionnairesubject.
status
int (optional)
Filter reactions with this particular status.
Choices: 1 2
moderated_since
string (optional)
Only give reactions that are moderated after this date (YYYY-MM-DD)
source
string (optional)
Filter reactions based on source. This argument can be used multiple times, for example source=email&source=web.
Choices: email web flyer import webservice
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"reactions": [
{
"id": "123",
"nr": 12,
"date": "2014-01-02 12:34",
"questionnaire": {
"id": "123",
"subject": "questionnaire subject"
},
"recipient": {
"woonplaats": "Rotterdam",
"geslacht": "M"
},
"location": {
"id": "location id",
"name": "Location name"
}
"status": 1,
"moderation_date": "2014-01-02 12:34",
"source": "email",
"summary": {
"grade": 8,
"recommendation": 8,
"review": "review text",
"question_subjects": {
"subject1": 6.3,
"subject2": 7.4,
"subject3": 8.1
}
}
},
{
"id": 456,
"nr": 11,
"date": "2014-02-02 12:34",
"questionnaire": {
"id": "123",
"subject": "questionnaire subject"
},
"recipient": {
"woonplaats": "Rotterdam",
"geslacht": "M"
},
"location": {
"id": "location id",
"name": "Location name"
}
"status": 1,
"moderation_date": "2014-01-02 12:34",
"source": "web",
"summary": {
"grade": 8,
"recommendation": 8,
"review": "review text",
"question_subjects": {
"subject1": 6.3,
"subject2": 7.4,
"subject3": 8.1
}
}
}
],
"total": 2
}
Results
Results contain aggregated results of a Questionnaire, Location, Organisation, Holding or a complete Platform. There can be a date filter applied to these results. Optionally the results can be split further to a lower level (see the parameter expand below). Results can have the following elements:
num_reactions: number of reacties (int)start_date: start date for the result set (YYYY-MM-DD)end_date: end date for the result set (YYYY-MM-DD)grade: average grade (float)nps: Net Promotor Score (int, between -100 and +100)nps_promotors: percentage promotors (NPS answers higher than 8) (float, 0 tot 100)nps_detractors: percentage detractors (NPS answers lower than 7) (float, 0 tot 100)nps_passives: percentage passives (NPS answers 7 or 8) (float, 0 tot 100)
PLATFORM RESULTS ¶
GET /results?start_date={start_date}&end_date={end_date}&include_grades={include_grades}&include_nps={include_nps}&questionnaire_subject={questionnaire_subject}&expand={expand}
Example URI
GET https://api.tevreden.nl/results?start_date=start_date&end_date=end_date&include_grades=include_grades&include_nps=include_nps&questionnaire_subject=questionnaire_subject&expand=expand
URI Parameters
start_date
string (optional)
only show results starting from this date (YYYY-MM-DD)
end_date
string (optional)
only show results ending at this date (YYYY-MM-DD)
include_grades
boolean (optional) Default: 1
show the amount of reactions and the average grade
include_nps
boolean (optional) Default: 0
show the NPS scores including promotors, passives, detractors.
questionnaire_subject
string (optional)
filter the results based on questionnairesubject.
expand
string (optional)
split up the results to a lower level. Possible values: “holding”, “organisation”, “location”, “questionnaire_subject” or “question_subject”
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"results": {
"start_date": {start_date},
"end_date": {end_date},
"num_reactions": 1234,
"grade": 7.87,
"nps": 27,
"nps_promotors": 52.12,
"nps_passives": 12.67,
"nps_detractors": 25.21
}
}
HOLDING RESULTS
GET /results/holding/{holdingid}?start_date={start_date}&end_date={end_date}&include_grades={include_grades}&include_nps={include_nps}&questionnaire_subject={questionnaire_subject}&expand={expand}
Example URI
URI Parameters
holdingidstring (required)
id of the Holding
start_datestring (optional)
only show results starting from this date (YYYY-MM-DD)
end_datestring (optional)
only show results ending at this date (YYYY-MM-DD)
include_gradesboolean (optional) Default: 1
show the amount of reactions and the average grade
include_npsboolean (optional) Default: 0
show the NPS scores including promotors, passives, detractors.
questionnaire_subjectstring (optional)
filter the results based on questionnairesubject.
expandstring (optional)
split up the results to a lower level. Possible values: “holding”, “organisation”, “location”, “questionnaire_subject” or “question_subject”
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"results": {
"holdingid": {holdingid},
"start_date": {start_date},
"end_date": {end_date},
"num_reactions": 1234,
"grade": 7.87,
"nps": 27,
"nps_promotors": 52.12,
"nps_passives": 12.67,
"nps_detractors": 25.21
}
}
ORGANISATION RESULTS ¶
GET /results/organization/{organisationid}?start_date={start_date}&end_date={end_date}&include_grades={include_grades}&include_nps={include_nps}&questionnaire_subject={questionnaire_subject}&expand={expand}
Example URI
GET https://api.tevreden.nl/results/organisation/organisationid?start_date=start_date&end_date=end_date&include_grades=include_grades&include_nps=include_nps&questionnaire_subject=questionnaire_subject&expand=expand
URI ParametersHide
organisationidstring (required)
id of the Organisation
start_datestring (optional)
only show results starting from this date (YYYY-MM-DD)
end_datestring (optional)
only show results ending at this date (YYYY-MM-DD)
include_gradesboolean (optional) Default: 1
show the amount of reactions and the average grade
include_npsboolean (optional) Default: 0
show the NPS scores including promotors, passives, detractors.
questionnaire_subjectstring (optional)
filter the results based on questionnairesubject.
expandstring (optional)
split up the results to a lower level. Possible values: “holding”, “organisation”, “location”, “questionnaire_subject” or “question_subject”
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"results": {
"organisationid": {organisationid},
"start_date": {start_date},
"end_date": {end_date},
"num_reactions": 1234,
"grade": 7.87,
"nps": 27,
"nps_promotors": 52.12,
"nps_passives": 12.67,
"nps_detractors": 25.21
}
}
LOCATION RESULTS ¶
GET /results/location/{locationid}?start_date={start_date}&end_date={end_date}&include_grades={include_grades}&include_nps={include_nps}&questionnaire_subject={questionnaire_subject}&expand={expand}
When getting the results for the location the results are also split up by Questionnaire.
Example URI
GET https://api.tevreden.nl/results/location/locationid?start_date=start_date&end_date=end_date&include_grades=include_grades&include_nps=include_nps&questionnaire_subject=questionnaire_subject&expand=expand
URI ParametersHide
locationid
string (required)
id of the Location
start_date
string (optional)
only show results starting from this date (YYYY-MM-DD)
end_date
string (optional)
only show results ending at this date (YYYY-MM-DD)
include_grades
boolean (optional) Default: 1
show the amount of reactions and the average grade
include_nps
Boolean (optional) Default: 0
show the NPS scores including promotors, passives, detractors.
questionnaire_subject
string (optional)
filter the results based on questionnairesubject.
expand
string (optional)
split up the results to a lower level. Possible values: “holding”, “organisation”, “location”, “questionnaire_subject” or “question_subject”
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"results": {
"locationid": {locationid},
"start_date": {start_date},
"end_date": {end_date},
"num_reactions": 1234,
"grade": 7.87,
"nps": 27,
"nps_promotors": 52.12,
"nps_passives": 12.67,
"nps_detractors": 25.21,
"questionnaires": [
{
"name": "questionnaire name1",
"subject": "questionnaire subject1",
"num_reactions": 617,
"grade": 8.21,
"nps": 27,
"nps_promotors": 52.12,
"nps_passives": 12.67,
"nps_detractors": 25.21
},
{
"name": "questionnaire name2",
"subject": "questionnaire subject2",
"num_reactions": 617,
"grade": 8.21,
"nps": 27,
"nps_promotors": 52.12,
"nps_passives": 12.67,
"nps_detractors": 25.21
}
]
}
}
QUESTIONNAIRE RESULTS ¶
GET /results/questionnaire/{questionnaireid}?start_date={start_date}&end_date={end_date}&include_grades={include_grades}&include_nps={include_nps}&expand={expand}
Example URI
GET https://api.tevreden.nl/results/questionnaire/questionnaireid?start_date=start_date&end_date=end_date&include_grades=include_grades&include_nps=include_nps&expand=expand
URI Parameters
questionnaireid
int (required)
id of the questionnaire
start_date
string (optional)
only show results starting from this date (YYYY-MM-DD)
end_date
string (optional)
only show results ending at this date (YYYY-MM-DD)
include_grades
boolean (optional) Default: 1
show the amount of reactions and the average grade
include_nps
boolean (optional) Default: 0
show the NPS scores including promotors, passives, detractors.
expand
string (optional)
split up the results to a lower level. Possible values: “holding”, “organisation”, “location”, “questionnaire_subject” or “question_subject”
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"results": {
"questionnaireid": {questionnaireid},
"start_date": {start_date},
"end_date": {end_date},
"num_reactions": 1234,
"grade": 7.87,
"nps": 27,
"nps_promotors": 52.12,
"nps_passives": 12.67,
"nps_detractors": 25.21,
"question_subjects": {
"subject1": 6.3,
"subject2": 7.4,
"subject3": 8.1
}
}
}
Reports
Reports are used for complex reports like pivot tables, toplists and platform statistics.
CROSSTABS ¶
A crosstab or pivot table is a multi-dimensional table with numeric data. Structure-wise a crosstab consists of 0 or more “records” (y-as). Every record has a “name” and 1 or more “columns” (x-as). Every column has a “name” and 1 or more “operations”. An operation is based on functions like COUNT, AVG, MIN, MAX etc, and also contains a “name” and a “value”. The value is numeric but can also be empty ("-").
GET /reports/crosstab/{config}?{param1}={value1}
Example URI
GET https://api.tevreden.nl/reports/crosstab/config?param1=value1URI ParametersHide
config
string (required)
name of the crosstab-configuration, for example “website_landelijk”.
param1
string (optional)
optional parameter
value1
string (optional)
optional value of the parameter
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"reactionamounts": {
"day": 143,
"week": 628,
"month": 1312,
"quarter": 3820,
"year": 17015,
"total": 65928,
"locations": 638
}
}
MOST REACTIONS PER PERIOD PER LOCATION ¶
An overview of locations with the highest amount of reactions per period (day, week, month, quarter, year and total)
GET /reports/mostreactions
Example URI
GET https://api.tevreden.nl/reports/mostreactions
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"mostreactions": {
"day": {
"amount": 1,
"location": {
"id": "123",
"name": "Apotheek A"
}
},
"week": {
"amount": 68,
"location": {
"id": "234",
"name": "Apotheek B"
}
},
"month": {
"amount": 211,
"location": {
"id": "345",
"name": "Apotheek C"
}
},
"quarter": {
"amount": 336,
"location": {
"id": "456",
"name": "Apotheek D"
}
},
"year": {
"amount": 998,
"location": {
"id": "567",
"name": "Apotheek E"
}
},
"total": {
"amount": 1302,
"location": {
"id": "678",
"name": "Apotheek F"
}
}
}
}
TOPLIST ¶
A toplist grouped by attributes of Locations, Questionnaires or Recipients, from high to low sorted on average grade.
GET /reports/toplist?group_by={group_by}&group_by_attribute={group_by_attribute}&amount={amount}&min_reactions={min_reactions}&start_date={start_date}&end_date={end_date}
Example URI
URI Parameters
group_by
string (optional) Default: location
Possible values: location, organisation, holding, questionnaire, recipient. Default is location for a toplist per location.
group_by_attribute
string (optional)
Only used/needed if group_by = ‘recipient’. This decides on which attribute of the recipient we group on. For example “automerk” (car brand).
amount
int (optional) Default: 5
How many items should the toplist have? Defaults to 5 for a top 5.
min_reactions
int (optional) Default: 10
Minimum amount of reactions per group to be included in the toplist, defaults to 10.
start_date
string (optional)
Only reactions from this date (YYYY-MM-DD).
Request per location
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"toplist": [
{
"location": {
"id": "123",
"name": "Location 1",
"organisationid": "OrgId1"
},
"rank": 1,
"grade": 9.8,
"num_reactions": 176
},
{
"location": {
"id": "234",
"name": "Location 2",
"organisationid": "OrgId2"
},
"rank": 2,
"grade": 9.6,
"num_reactions": 32
},
{
"location": {
"id": "345",
"name": "Location 3",
"organisationid": "OrgId3"
},
"rank": 3,
"grade": 8.8,
"num_reactions": 55
},
{
"location": {
"id": "456",
"name": "Location 4",
"organisationid": "OrgId4"
},
"rank": 4,
"grade": 8.1,
"num_reactions": 234
},
{
"location": {
"id": "567",
"name": "Location 5",
"organisationid": "OrgId5"
},
"rank": 5,
"grade": 8,
"num_reactions": 33
}
]
}
Request per recipient attribute
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"toplist": [
{
"grade": "9.7",
"num_reactions": "15",
"rank": 1,
"location": {
"id": "345",
"name": "Location name",
"organisationid": "OrgId"
},
"recipient": {
"name": "automerk",
"value": "Mercedes"
}
},
{
"grade": "9.4",
"num_reactions": "19",
"rank": 2,
"location": {
"id": "345",
"name": "Location name",
"organisationid": "OrgId"
},
"recipient": {
"name": "automerk",
"value": "ROVER"
}
},
{
"grade": "9.1",
"num_reactions": "35",
"rank": 3,
"location": {
"id": "345",
"name": "Location name",
"organisationid": "OrgId"
},
"recipient": {
"name": "automerk",
"value": "Porsche"
}
},
{
"grade": "8.9",
"num_reactions": "57",
"rank": 4,
"location": {
"id": "345",
"name": "Location name",
"organisationid": "OrgId"
},
"recipient": {
"name": "automerk",
"value": "LANDROVER"
}
},
{
"grade": "8.8",
"num_reactions": "36",
"rank": 5,
"location": {
"id": "345",
"name": "Location name",
"organisationid": "OrgId"
},
"recipient": {
"name": "automerk",
"value": "SMART"
}
}
]
}
XLS EXPORT ¶
A full xlsx export containing all reactions of all questionnaires, including answers for all questions. Not aggregated, meant for further analysis in applications like SPSS. The data set can be limited using filters on recipients (f.e. recipient.provincie=Utrecht) or on questionnaire (f.e. questionnaire.OnderzoeksType=KTO). The export is prepared in the background. A POST /reports/xls will return an immediate response containing an uri from which the xls export can be downloaded when ready. See the /download endpoint for details.
POST /reports/xls?name={name}&questionnaire.{qn_attr}={qn_value}&recipient.{recp_attr}={recp_value}
Example URI
POST https://api.tevreden.nl/reports/xls?name=name&questionnaire.qn_attr=qn_value&recipient.recp_attr=recp_value
URI Parameters
name
string (optional) Default: report
The (base)name of the report. Filename will be of the form “name-YYYY.MM.DD-hh.mm.ss.xlsx”
qn_attr
string (optional)
Name of questionnaire-attribute to filter results on
qn_value
string (optional)
Value of questionnaire-attribute to filter on
recp_attr
string (optional)
Name of recipient-attribute to filter results on
recp_value
string (optional)
Value of recipient-attribute to filter on
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"uri": "https://api.tevreden.nl/download/K7dJsDWk1QbFOdYOQk1nNn5Bl2RjilL5f0jebSup4ysLOrgM",
"message": "The report will be generated in the background, and will be available for download shortly using the specified uri."
}
Statistics
Global platformstatistics.
STATISTICS ¶
Platformwide grades which show the true extent of the research and global grades. These are amount of reactions, recipients, invitations and response rates.
GET /statistics
Example URI
GET https://api.tevreden.nl/statistics
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 200
Headers
Tevreden-platform: {platform_name}
Body
{
"statistics": {
"invitations": "2530586",
"locations": "1914",
"reactions": "368729",
"recipients": "1422166",
"response_percentage": "25.9"
}
}
Downloads ¶
Download of big reports, for example full xls reports.
DOWNLOADS ¶
Download the specified file. When the specified downloadid is valid but not yet available a http status 202 (accepted but still processing) will be returned. Try again later. Invalid / not existing downloadids will generate a 404. A download link is usually obtained from a POST /reports call.
GET /downloads/{downloadid}
Example URI
GET https://api.tevreden.nl/downloads/downloadid
URI Parameters
downloadid
string (required)
Id of the download.
Request
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response 202
Headers
Tevreden-platform: {platform_name}
Content-type: text/html
Body
This download is not available yet. Try again later.
Response 200
Headers
Tevreden-platform: {platform_name}
Body
... binary data ...