Back to top

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

Show the documentation

Show the documentation
GET/

A link to this documentation in HTML format.

Example URI

GET https://api.tevreden.nl/
Response  200
HideShow
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
HideShow
Headers
Tevreden-API-key: {api_key}
Response  200
HideShow
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

List 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
HideShow
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 (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: name 

On which field or attribute should results be sorted

dir
string (optional) Default: ASC 

Sort ascending (ASC, default) or descending (DESC)

Request
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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 single Location
GET/locations/{id}

Get a single Location, by using an ID.

Example URI

GET https://api.tevreden.nl/locations/id
URI Parameters
HideShow
id
string (required) 

id van de Location

Request
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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
HideShow
Headers
Tevreden-platform: {platform_name}
Body
{
  "message": "Location with id {id} not found."
}

Update a Location
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
HideShow
id
string (required) 

id van de Location

Request
HideShow
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
HideShow
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

List 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
HideShow
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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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 single Organisation
GET/organisations/{id}

Get a single Organisation, based on id

Example URI

GET https://api.tevreden.nl/organisations/id
URI Parameters
HideShow
id
string (required) 

id van de Organisation

Request
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
Headers
Tevreden-platform: {platform_name}
Body
{
  "organisation": {
    "id": "organisation id",
    "name": "name",
    "modified": "2013-01-01",
    "created": "2013-01-01"
  }
}
Response  404
HideShow
Headers
Tevreden-platform: {platform_name}
Body
{
  "message": "Organisation with id {id} not found."
}

Update an Organisation
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
HideShow
id
string (required) 

id van de Organisation

Request
HideShow
Headers
Content-Type: application/json
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Body
{
  "name": "Updated name"
}
Response  200
HideShow
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

List 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
HideShow
q
string (optional) 

Search term. Only Holdings matching the search term will be returned.

Request
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
Headers
Tevreden-platform: {platform_name}
Body
{
  "holdings": [
    {
      "id": "holding id",
      "name": "holding name"
    }
  ],
  "total": 1
}

Single Holding

Get single Holding
GET/holdings/{id}

Get a single Holding, based on ID.

Example URI

GET https://api.tevreden.nl/holdings/id
URI Parameters
HideShow
id
string (required) 

id of the Holding

Request
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
Headers
Tevreden-platform: {platform_name}
Body
{
    "holding": {
        "id": "holding id",
        "name": "name",
    }
}
Response  404
HideShow
Headers
Tevreden-platform: {platform_name}
Body
{
  "message": "Holding with id {id} not found."
}

Update a Holding
PATCH/holdings/{id}

Update a Holding. Only the name of a Holding can be changed, the ID cannot be changed.

Example URI

PATCH https://api.tevreden.nl/holdings/id
URI Parameters
HideShow
id
string (required) 

id of the Holding

Request
HideShow
Headers
Content-Type: application/json
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Body
{
  "name": "Updated name"
}
Response  200
HideShow
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 a single Questionnaire
GET/questionnaires/{id}

Get a single Questionnaire based on ID.

Example URI

GET https://api.tevreden.nl/questionnaires/id
URI Parameters
HideShow
id
int (required) 

id of the Questionnaire

Request
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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
HideShow
Headers
Tevreden-platform: {platform_name}
Body
{
  "message": "Questionnaire with id {id} not found."
}

Platform Questionnaires

Get 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 Parameters
HideShow
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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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 Holding Questionnaires
GET/questionnaires/holding/{holdingid}?limit={limit}&offset={offset}&{attrname}={attrvalue}&group_by_subject={group_by_subject}

Example URI

GET https://api.tevreden.nl/questionnaires/holding/holdingid?limit=limit&offset=offset&attrname=attrvalue&group_by_subject=group_by_subject
URI Parameters
HideShow
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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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 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
HideShow
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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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 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
HideShow
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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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.

Create invitations for single questionnaire
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
HideShow
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 .

Request
HideShow
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
HideShow
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
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Body
naam%3DDhr.%20Example
Response  400
HideShow
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
HideShow
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
HideShow
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
HideShow
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
HideShow
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.

Create invitations for multiple questionnaires
POST/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

POST https://api.tevreden.nl/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
URI Parameters
HideShow
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) 

The value of a questionnaire attribute to match one questionnaire.

dry_run
boolean (optional) Default: 0 

If 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: 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 .

Request
HideShow
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
HideShow
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.

Create a preview of an invitation
POST/invitations/questionnaire/{questionnaireid}/preview?email={email}

Example URI

POST https://api.tevreden.nl/invitations/questionnaire/questionnaireid/preview?email=email
URI Parameters
HideShow
questionnaireid
int (required) 

id of the Questionnaire. The ids of available questionnaires can be retrieved by doing a GET /questionnaires call.

email
string (required) 

the email address to send the preview to.

Request
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Content-Type: application/json
Body
{
  "email": "my@email.address",
  "naam": "Mr. Preview"
}
Response  201
HideShow
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 status of an invitation
GET/invitations/status/{invitationcode}

Example URI

GET https://api.tevreden.nl/invitations/status/invitationcode
URI Parameters
HideShow
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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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
HideShow
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 Invitation fields
GET/invitations/questionnaire/{questionnaireid}/fields?type={type}

Example URI

GET https://api.tevreden.nl/invitations/questionnaire/questionnaireid/fields?type=type
URI Parameters
HideShow
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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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 certain question subject or theme. 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 Reaction
GET/reactions/{id}?questionsubjects_rescale={questionsubjects_rescale}

Get a single Reaction based on ID.

Example URI

GET https://api.tevreden.nl/reactions/id?questionsubjects_rescale=questionsubjects_rescale
URI Parameters
HideShow
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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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
HideShow
Headers
Tevreden-platform: {platform_name}
Body
{
  "message": "Reaction with id {id} not found."
}

Get all reactions

Get Platform 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}

Example URI

GET https://api.tevreden.nl/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 Parameters
HideShow
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_subject
string (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) 

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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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
GET/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

GET https://api.tevreden.nl/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
URI Parameters
HideShow
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

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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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 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
HideShow
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

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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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 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

GET https://api.tevreden.nl/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
URI Parameters
HideShow
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

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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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 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
HideShow
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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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 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

GET https://api.tevreden.nl/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
URI Parameters
HideShow
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: 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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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 Organisation Results
GET/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

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 Parameters
HideShow
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: 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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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 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 Parameters
HideShow
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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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 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
HideShow
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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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 crosstab data
GET/reports/crosstab/{config}?{param1}={value1}

Example URI

GET https://api.tevreden.nl/reports/crosstab/config?param1=value1
URI Parameters
HideShow
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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
Headers
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 Amounts
GET/reports/reactionamounts

Example URI

GET https://api.tevreden.nl/reports/reactionamounts
Request
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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 most reactions per period
GET/reports/mostreactions

Example URI

GET https://api.tevreden.nl/reports/mostreactions
Request
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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 Toplist
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

GET https://api.tevreden.nl/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
URI Parameters
HideShow
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).

end_date
string (optional) 

Only reactions from this date (YYYY-MM-DD).

Request  per location
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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.

Create XLS export
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
HideShow
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
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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
GET/statistics

Example URI

GET https://api.tevreden.nl/statistics
Request
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  200
HideShow
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.

Download file
GET/downloads/{downloadid}

Example URI

GET https://api.tevreden.nl/downloads/downloadid
URI Parameters
HideShow
downloadid
string (required) 

Id of the download.

Request
HideShow
Headers
Tevreden-API-key: {api_key}
Tevreden-platform: {platform_name}
Response  202
HideShow
Headers
Tevreden-platform: {platform_name}
Content-type: text/html
Body
This download is not available yet. Try again later.
Response  200
HideShow
Headers
Tevreden-platform: {platform_name}
Body
... binary data ...

Generated by aglio on 12 Apr 2018