The Tevreden API
The Tevreden 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 ¶
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
Headers
Tevreden-API-key: {api_key}200Body
{
"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 ¶
List LocationsGET/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
- 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-01Only locations that have been modified since the date supplied (YYYY-MM-DD) (See date formats above)
- created_since
date(optional) Example: 2014-01-01Only locations that are made since the supplied date (YYYY-MM-DD) (See date formats above)
- offset
int(optional) Default: 0Show results back from the number supplied in this paramater. Default is
0(from the beginning)- limit
int(optional)Limit the maximum of results, this defaults to “no limit” so all results are shown.
- order_by
string(optional) Default: nameOn which field or attribute should results be sorted
- dir
string(optional) Default: ASCSort ascending (
ASC, default) or descending (DESC)
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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 single LocationGET/locations/{id}
Get a single Location, by using an ID.
Example URI
- id
string(required)id van de Location
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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",
}
}
}404Headers
Tevreden-platform: {platform_name}Body
{
"message": "Location with id {id} not found."
}Update a LocationPATCH/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
- id
string(required)id van de Location
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"
}
}200Headers
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 ¶
List OrganisationsGET/organisations?q={q}&modified_since={modified_since}&created_since={created_since}
Get a list of Organisations, could be filtered.
Example URI
- q
string(optional)Search term. Only Organisations that match the search term (the
nameis used) will be returned.- modified_since
date(optional) Example: 2014-01-01Only get Organisations that are modified since the supplied date (YYYY-MM-DD) (See date formats above)
- created_since
date(optional) Example: 2014-01-01Only get Organisations that are created since the supplied date (YYYY-MM-DD) (See date formats above)
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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 single OrganisationGET/organisations/{id}
Get a single Organisation, based on id
Example URI
- id
string(required)id van de Organisation
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
Tevreden-platform: {platform_name}Body
{
"organisation": {
"id": "organisation id",
"name": "name",
"modified": "2013-01-01",
"created": "2013-01-01"
}
}404Headers
Tevreden-platform: {platform_name}Body
{
"message": "Organisation with id {id} not found."
}Update an OrganisationPATCH/organisations/{id}
Update an Organisation. Only the name of an Organisation can be changed. The ID can not be changed.
Example URI
- id
string(required)id van de Organisation
Headers
Content-Type: application/json
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}Body
{
"name": "Updated name"
}200Headers
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 ¶
List HoldingsGET/holdings?q={q}
Get a list of Holdings, can be filtered.
Example URI
- q
string(optional)Search term. Only Holdings matching the search term will be returned.
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
Tevreden-platform: {platform_name}Body
{
"holdings": [
{
"id": "holding id",
"name": "holding name"
}
],
"total": 1
}Single Holding ¶
Get single HoldingGET/holdings/{id}
Get a single Holding, based on ID.
Example URI
- id
string(required)id of the Holding
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
Tevreden-platform: {platform_name}Body
{
"holding": {
"id": "holding id",
"name": "name",
}
}404Headers
Tevreden-platform: {platform_name}Body
{
"message": "Holding with id {id} not found."
}Update a HoldingPATCH/holdings/{id}
Update a Holding. Only the name of a Holding can be changed, the ID cannot be changed.
Example URI
- id
string(required)id of the Holding
Headers
Content-Type: application/json
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}Body
{
"name": "Updated name"
}200Headers
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 a single QuestionnaireGET/questionnaires/{id}
Get a single Questionnaire based on ID.
Example URI
- id
int(required)id of the Questionnaire
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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"
}
}
}404Headers
Tevreden-platform: {platform_name}Body
{
"message": "Questionnaire with id {id} not found."
}Platform Questionnaires ¶
Get Platform QuestionnairesGET/questionnaires?limit={limit}&offset={offset}&{attrname}={attrvalue}&group_by_subject={group_by_subject}
Example URI
- limit
int(optional) Default: 100Limit the maximum amount of questionnaires returned. Defaults to 100 and has a maximum of 1500.
- offset
int(optional) Default: 0Return Questionnaires
offsetfrom 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: 0Group Questionnaires based on subject. In this specific case a list will be returned of unique questionnaire_subjects.
group_by_subject=0Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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
}group_by_subject=1Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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 Holding QuestionnairesGET/questionnaires/holding/{holdingid}?limit={limit}&offset={offset}&{attrname}={attrvalue}&group_by_subject={group_by_subject}
Example URI
- holdingid
string(required)id of the Holding.
- limit
int(optional) Default: 100Limit maximum amount of questionnaires, defaults to 100 with a maximum of 1000.
- offset
int(optional) Default: 0Return Questionnaires
offsetfrom 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: 0Group Questionnaires based on subject. In this specific case a list will be returned of unique questionnaire_subjects.
group_by_subject=0Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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
}group_by_subject=1Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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 Organisation QuestionnairesGET/questionnaires/organisation/{organisationid}?limit={limit}&offset={offset}&{attrname}={attrvalue}&group_by_subject={group_by_subject}
Example URI
- organisationid
string(required)id of the Organisation.
- limit
int(optional) Default: 100Limit maximum amount of questionnaires, defaults to 100 with a maximum of 1000.
- offset
int(optional) Default: 0Return Questionnaires
offsetfrom 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: 0Group Questionnaires based on subject. In this specific case a list will be returned of unique questionnaire_subjects.
group_by_subject=0Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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 Location QuestionnairesGET/questionnaires/location/{locationid}?limit={limit}&offset={offset}&{attrname}={attrvalue}&group_by_subject={group_by_subject}
Example URI
- locationid
string(required)id of a Location.
- limit
int(optional) Default: 100Limit maximum amount of questionnaires, defaults to 100 with a maximum of 1000.
- offset
int(optional) Default: 0Return Questionnaires
offsetfrom 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: 0Group Questionnaires based on subject. In this specific case a list will be returned of unique questionnaire_subjects.
group_by_subject=0Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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
}group_by_subject=1Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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.
Create invitations for single questionnairePOST/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
- 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: emailCan be one of
web,email,link,code,preview. Default is email. See above for more information about the types.- send_date
string(optional) Default: nowOnly 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: 0Only 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: 0Only 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: 0If 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: 0Optionally 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 resultCustom basename for the generated xls file. Default/if not specified the name will be ‘invitations result
.
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%3D3328201Headers
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"
}
}Headers
Content-Type: application/x-www-form-urlencoded
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}Body
naam%3DDhr.%20Example400Headers
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"
}
}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"
}
]
}201Headers
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"
}
}
]
}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-08201Headers
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.
Create invitations for multiple questionnairesPOST/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
- type
string(optional) Default: emailCan be one of
web,email,link,code,preview. Default is email. See above for more information about the types.- send_date
string(optional) Default: nowOnly 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: 0Only 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: 0Only 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)The value of a questionnaire attribute to match one questionnaire.
- dry_run
boolean(optional) Default: 0If this optional argument is 1 then a dry run 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: 0Optionally 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 resultCustom basename for the generated xls file. Default/if not specified the name will be ‘invitations result
.
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,bar201Headers
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.
Create a preview of an invitationPOST/invitations/questionnaire/{questionnaireid}/preview?email={email}
Example URI
- 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.
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Content-Type: application/jsonBody
{
"email": "my@email.address",
"naam": "Mr. Preview"
}201Headers
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 status of an invitationGET/invitations/status/{invitationcode}
Example URI
- 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
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
Tevreden-platform: {platform_name}Body
{
reaction: {
created: '2017-02-03 12:34:56',
modified: '2017-02-03 12:34:56',
finished: 0
}
}404Headers
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 Invitation fieldsGET/invitations/questionnaire/{questionnaireid}/fields?type={type}
Example URI
- questionnaireid
int(required)id of the Questionnaire. This ID can be requested by using a GET /questionnaires call.
- type
string(optional) Default: emailthe type of invitation. Possible values: “web”, “email”, “link” or “preview”.
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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 single ReactionGET/reactions/{id}?questionsubjects_rescale={questionsubjects_rescale}
Get a single Reaction based on ID.
Example URI
- 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
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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"
}
}
}
}404Headers
Tevreden-platform: {platform_name}Body
{
"message": "Reaction with id {id} not found."
}Get all reactions ¶
Get Platform ReactionsGET/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}
Example URI
- 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: 0Return reactions with an offset from number. Defaults to
0(from the beginning).- limit
int(optional) Default: 200Limit the maximum amount of reactions. Defaults to 200 with a maximum of 1000.
- dir
string(optional) Default: descOrder direction of the reactions, by reactiondate.
Choices:
descasc- questionnaire_subject
string(optional)Filter reactions on questionnairesubject.
- status
int(optional)Filter reacties with this particular status.
Choices:
12- 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:
emailwebflyerimportwebservice- 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
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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 ReactionsGET/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
- 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: 0Return reactions with an offset from number. Defaults to
0(from the beginning).- limit
int(optional) Default: 100Limit the maximum amount of reactions. Defaults to 100 with a maximum of 1000.
- dir
string(optional) Default: descOrder direction of the reactions, by reactiondate. Can be
desc(default, descending, newest first) orasc(ascending, oldest first).Choices:
descasc- questionnaire_subject
string(optional)Filter reactions on questionnairesubject.
- status
int(optional)Filter reactions with this particular status.
Choices:
12- 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:
emailwebflyerimportwebservice- 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
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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 Organisation ReactionsGET/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
- 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: 0Return reactions with an offset from number. Defaults to
0(from the beginning).- limit
int(optional) Default: 100Limit the maximum amount of reactions. Defaults to 100 with a maximum of 1000.
- dir
string(optional) Default: descOrder direction of the reactions, by reactiondate. Can be
desc(default, descending, newest first) orasc(ascending, oldest first).Choices:
descasc- questionnaire_subject
string(optional)Filter reactions on questionnairesubject.
- status
int(optional)Filter reactions with this particular status.
Choices:
12- 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:
emailwebflyerimportwebservice- 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
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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 Location ReactionsGET/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
- 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: 0Return reactions with an offset from number. Defaults to
0(from the beginning).- limit
int(optional) Default: 100Limit the maximum amount of reactions. Defaults to 100 with a maximum of 1000.
- dir
string(optional) Default: descOrder direction of the reactions, by reactiondate. Can be
desc(default, descending, newest first) orasc(ascending, oldest first).Choices:
descasc- questionnaire_subject
string(optional)Filter reactions on questionnairesubject.
- status
int(optional)Filter reactions with this particular status.
Choices:
12- 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:
emailwebflyerimportwebservice- 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
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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 Platform ResultsGET/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
- 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: 1show the amount of reactions and the average grade
- include_nps
boolean(optional) Default: 0show 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”
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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 Holding ResultsGET/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
- holdingid
string(required)id of the Holding
- 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: 1show the amount of reactions and the average grade
- include_nps
boolean(optional) Default: 0show 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”
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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 Organisation ResultsGET/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}
Example URI
- organisationid
string(required)id of the Organisation
- 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: 1show the amount of reactions and the average grade
- include_nps
boolean(optional) Default: 0show 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”
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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 Location ResultsGET/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
- 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: 1show the amount of reactions and the average grade
- include_nps
boolean(optional) Default: 0show 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”
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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 Questionnaire ResultsGET/results/questionnaire/{questionnaireid}?start_date={start_date}&end_date={end_date}&include_grades={include_grades}&include_nps={include_nps}&expand={expand}
Example URI
- 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: 1show the amount of reactions and the average grade
- include_nps
boolean(optional) Default: 0show 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”
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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 crosstab dataGET/reports/crosstab/{config}?{param1}={value1}
Example URI
- 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
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
Tevreden-platform: {platform_name}Body
{
"crosstab": {
"config": {
"headers": [
{
"id": "0_0",
"name": "2013"
},
{
"id": "0_1",
"name": "2014"
}
],
"operations": [
{
"format": "%d",
"name": "N",
"type": "COUNT"
},
{
"format": "%.1f",
"name": "Score",
"type": "AVG"
}
],
"title": "Landelijke scores autobedrijf.tevreden.nl per jaar"
},
"records": [
{
"headers": [
{
"name": "2013",
"operations": [
{
"name": "N",
"value": "1216"
},
{
"name": "Score",
"value": "8.4"
}
]
},
{
"name": "2014",
"operations": [
{
"name": "N",
"value": "657"
},
{
"name": "Score",
"value": "8.7"
}
]
}
],
"name": "01 Evaluatie aanschaf nieuwe auto"
},
{
"headers": [
{
"name": "2013",
"operations": [
{
"name": "N",
"value": "2973"
},
{
"name": "Score",
"value": "8.2"
}
]
},
{
"name": "2014",
"operations": [
{
"name": "N",
"value": "1764"
},
{
"name": "Score",
"value": "8.3"
}
]
}
],
"name": "02 Evaluatie aanschaf gebruikte auto/occasion"
},
{
"headers": [
{
"name": "2013",
"operations": [
{
"name": "N",
"value": "4189"
},
{
"name": "Score",
"value": "8.3"
}
]
},
{
"name": "2014",
"operations": [
{
"name": "N",
"value": "2421"
},
{
"name": "Score",
"value": "8.4"
}
]
}
],
"name": "Totaal"
}
]
}
}Reaction amounts per period ¶
An overview of the amount of reactions on the entire platform, per day, week, month, quarter, year and total, together with the amount of Locations.
Get Reaction AmountsGET/reports/reactionamounts
Example URI
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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 most reactions per periodGET/reports/mostreactions
Example URI
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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 ToplistGET/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
- group_by
string(optional) Default: locationPossible values: location, organisation, holding, questionnaire, recipient. Default is
locationfor 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: 5How many items should the toplist have? Defaults to
5for a top 5.- min_reactions
int(optional) Default: 10Minimum 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).- end_date
string(optional)Only reactions from this date (
YYYY-MM-DD).
per locationHeaders
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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
}
]
}per recipient attributeHeaders
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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.
Create XLS exportPOST/reports/xls?name={name}&questionnaire.{qn_attr}={qn_value}&recipient.{recp_attr}={recp_value}
Example URI
- name
string(optional) Default: reportThe (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
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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 StatisticsGET/statistics
Example URI
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}200Headers
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.
Download fileGET/downloads/{downloadid}
Example URI
- downloadid
string(required)Id of the download.
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}202Headers
Tevreden-platform: {platform_name}
Content-type: text/htmlBody
This download is not available yet. Try again later.200Headers
Tevreden-platform: {platform_name}Body
... binary data ...