Panel API¶

All API calls have the following in common:

there is an endpoint, which is basically a URL you can call

calling this endpoint requires authentication

each endpoint has its own parameters

depending on the type of API, the call either consists of one call, or allows follow-up action

Authentication¶

Authentiation is done by setting the headers of the request. See API Authentication for more detailed information

Data export API¶

The data export API is used to automate initiation and download of a data file of your project.

The Panel API¶

Introduction¶

The panel API is used to register members, set and retrieve data of members, and unsubscribe members.

For readability purposes the API for the panel is defined in XML format. Using this API you can have your website create members, retrieve and set their data and remove members.

Keys¶

For accessing your panel, you need:

a client key that identifies you, in this documentation we will use key d51c1577-27ab-4e0c-9581-e5d68ae620ae. Note that this is an example key that does not actually exist

a panel-key that identifies the panel you want to interact with. In this documentation we will use key eebb16ed-176a-40c6-b341-7a8211d212f9. Not that this is an example key that does not actually exist

The keys are provided to you by dotData.

Call structure¶

Each action is done by sending a snippet of XML to the dotData servers using a http POST call. The POST needs to be done to the following URL:

https://api.dotdata.nl/dotdata/panelapi/xml

Each type of action is sent to this same URL, the nature of the action is directed by the content of your XML.

The use of the https protocol is recommended but not required, you can use the http:// protocol instead of https:// but this will make the data transfer less secure.

Calls by example¶

Registering a member¶

Below is the most basic variation of an XML call that is used to register a member:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<doc>
        <clientkey>d51c1577-27ab-4e0c-9581-e5d68ae620ae</clientkey>
        <function>subscribe</function>
        <data>
                <panelid>eebb16ed-176a-40c6-b341-7a8211d212f9</panelid>
                <emailaddress>example@gmail.com</emailaddress>
                <importid>123456</importid>
        </data>
</doc>

The minimally required data for a person to be registered are email address and import id. The importid field is an ID that you assign, for instance the ID this person has in your own database.

Process flow¶

Typically, registration of a member is a two-step process:

The member registers

The member goes through a minimal of one profile survey that asks about their background data. You can define this profile survey yourself, so you are not bound to a limited number of predefined fields. For instance, for a business panel you might want to include a datapoint of company size and company role. For a consumer you might want to record interests and income level

Only after a member goes through the profile questionnaire he or she should become an active member that is eligible to receive survey invitations

Note

This means that initially a member is registered as ‘not active yet’. A member needs to be activated either explicitely in the registration call or in a separate call described in Update a members data.

Update a members data¶

Activate a member¶

The usual way to activate a member is by issuing a member.activate() script within a questionnaire. However you can also activate the member using the API.

The call below will activate the member. After this call, the member will be eligible to receive invitations by the system to participate in surveys.

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<doc>
        <object>member</object>
        <function>setdata</function>
        <clientkey>363c1199-dc78-422c-bff4-e225508e178c</clientkey>
        <data>
                <panelid>eebb16ed-176a-40c6-b341-7a8211d212f9</panelid>
                <importid>123456</importid>
                <active>1</active>
        </data>
</doc>

Basic update of a member¶

The call below shows how you can update the email address and name of the respondent. Also you can activate the person.

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<doc>
        <object>member</object>
        <function>setdata</function>
        <clientkey>363c1199-dc78-422c-bff4-e225508e178c</clientkey>
        <data>
                <panelid>eebb16ed-176a-40c6-b341-7a8211d212f9</panelid>
                <importid>123456</importid>
                <emailaddress>example@gmail.com</emailaddress>
                <name>Robert van Geel</name>
        </data>
</doc>

Set profile info¶

As described in Update a members data you can set any variable you like on top of the basic variables like email address. An example is given below. Note that variables ‘age’, ‘gender’, ‘region’ and ‘segmentationvalue’ are not pre-existing in the system. These variables can be freely defined by you in the profile questionnaire.

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<doc>
        <object>member</object>
        <function>setdata</function>
        <clientkey>363c1199-dc78-422c-bff4-e225508e178c</clientkey>
        <data>
                <panelid>eebb16ed-176a-40c6-b341-7a8211d212f9</panelid>
                <importid>123456</importid>
                <emailaddress>example@gmail.com</emailaddress>
                <name>Robert van Geel</name>
                <active>1</active>
                <profile>
                        <age>1</age>
                        <gender>2</gender>
                        <income>3</income>
                        <region>3</region>
                        <segmentationvalue>123.4567</segmentationvalue>
                </profile>
        </data>
</doc>

Profile info using texts¶

In addition to the ability to work with numeric values for profile variables (eg gender=1) you can use string variables (eg genderstring=Male):

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<doc>
        <object>member</object>
        <function>setdata</function>
        <clientkey>363c1199-dc78-422c-bff4-e225508e178c</clientkey>
        <data>
                <panelid>eebb16ed-176a-40c6-b341-7a8211d212f9</panelid>
                <importid>123456</importid>
                <emailaddress>example@gmail.com</emailaddress>
                <name>Robert van Geel</name>
                <active>1</active>
                <profile>
                        <agestring>middle</agestring>
                        <genderstring>male</genderstring>
                        <income>3</income>
                        <region>South</region>
                </profile>
        </data>
</doc>

Get a members data¶

The call below fetches data of a member.

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
        <doc>
        <object>member</object>
        <currentdate>2016-06-18 15:24:56</currentdate>
        <function>getdata</function>
        <clientkey>363c1199-dc78-422c-bff4-e225508e178c</clientkey>
        <data>
                <panelid>eebb16ed-176a-40c6-b341-7a8211d212f9</panelid>
                <importid>123456</importid>
                <mysurveys>1</mysurveys>
                <showintake>1</showintake>
                <profile>2</profile>
                <dividendjournal>0</dividendjournal>
        </data>
        </doc>

Within the data segment of the above XML there are a few directives as to which type of data should be returned by the system:

mysurveys: return the list of surveys that this member has been selected or invited for, or that this member started or completed otherwise. This can be convenient for display at ‘my page’. Per questionnaire you can see the complete status

showintake: return a link to the profile questionnaire. It is recommended to check the status of the profile questionnaire. When the profile questionnaire has an unqualified status, or has not been completed yet, we suggest you do an immedate redirect to that questionnaire so people can not actually log in until they finish their profile questionnaire. The example Joomla plugin code shows an example of how to do this in php

profile: this parameter can have two different values:

when the value is 1, this return the answers in numeric form from the profile questionnaire. These are the same variables as in section Set profile info

When the value is 2, it will return the values in string form. These are the same variables as in section Profile info using texts.

dividendjournal: return a full history of incentives for this member

The return value of this call could look like below. Note that the variables in the ‘profile’ section are defined by you, so the below just shows an example:

<?xml version="1.0" encoding="utf-8" standalone="no" ?>
<doc>
        <result>1</result>
        <emailaddress>example@gmail.com</emailaddress>
        <subpanelid>1</subpanelid>
        <firstname>Robert</firstname>
        <sourceflag></sourceflag>
        <middlename></middlename>
        <lastname>van Geel</lastname>
        <importid>123456</importid>
        <activationdate>2016-05-19 20:14:39</activationdate>
        <custprops></custprops>
        <gender></gender>
        <active>1</active>
        <unsubscribedate></unsubscribedate>
        <guid>CC940AA9-A96D-4BC2-8F9A-59683839FE71</guid>
        <mysurveys>
                <survey id="6114" title="dotData panel" description="This is the questionnaire you filled out as part of the Panel registration process" divearn="" tickets="0" estimatedtime="5" closing="" bootstrapscreener="1" additionalscreener="1" condition="Q" finished="2016-05-19 20:14:39" lastfinished="2016-05-19 20:35:49" duration="C" opened="1" closed="0">http://www.dotdata.nl/start?d=1234567890&amp;k=e6c56633c916486a8de57810386e9761</survey>
        </mysurveys>
        <profile guid="CE940AA9-A96D-4BC2-8F9A-59683839FE71">
                <Genderstring>Male</Genderstring>
                <YearBorn>1989</YearBorn>
                <Sizestring>11-25 employees</Sizestring>
        </profile>
</doc>

Unsubscribe a member¶

The call below will deactivate the member by setting the active flag to 0. Also, it will set the ‘unsubscribedate’ variable if it is not set yet. Note that due to regulation concerning privacy rules, this call will also remove the email address. Questionnaire data related to the members record will remain intact, so if this contains information that can be used to identify an individual it is your own responsibility to clean up that information.

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<doc>
        <object>member</object>
        <function>setdata</function>
        <clientkey>363c1199-dc78-422c-bff4-e225508e178c</clientkey>
        <data>
                <panelid>eebb16ed-176a-40c6-b341-7a8211d212f9</panelid>
                <importid>123456</importid>
                <active>0</active>
        </data>
</doc>

Full example¶

See PanelAPI php example for more detailed information

Reporting API¶

The reporting API is under construction. Information about this API is at request.