Respondent is an association of a contact with a survey in the user account.

One contact can be assigned to multiple surveys in an account.

List of operations for a resource

Name

URL

Description

Respondent list

/respondents/:id_survey

Returns a list of all respondents from the survey specified by the parameter: id_survey. The respondents are sorted by email address in alphabetical order.

Searching respondents

/respondents/search/:id_survey

Searches for respondents by criteria passed in the POST table

Adding a respondent to the survey

/respondents/add

Assigns a contact to the survey

Deleting a respondent

/respondents/delete

Assigns a contact to the survey

Batch upload of respondents

/respondents/batch

Sending respondents in grouped packages, for which one mailing can be created at the end

Description of response parameters

Name/path

Description

Possible values

id

Respondent ID

token

A unique token that identifies the respondent. Used for one-time survey completion by the respondent. The parameter is active only with the highest level of survey security.

offline_distribution

Information on whether the invitation to complete the survey is carried out by startquestion.com or by the author of the survey. Providing the user_token in the link to complete the survey is also treated as distribution by the author.

0 – Link to the survey sent from startquestion.com
1 – Link to the survey sent by the author (offline token distribution)

date_generate

Date of adding a respondent to the survey

date_invitaion_send

Date and time of sending the invitation

null – An invitation was not sent to the respondent
0000-00-00 00:00:00 – Invitation awaiting mailing
2012-12-06 12:00:00 – Date and time of sending the invitation

date_survey_open

Date and time of first opening of the survey The parameter is active only with the highest level of survey security.

null – The survey was not opened by the respondent
2012-12-06 12:00:00 – Date and time of opening the invitation

date_survey_answer

Date and time of filling out the survey. The parameter is active only with the highest level of survey security.

null – The survey was not filled out by the respondent
2012-12-06 12:00:00 – Date and time of opening the invitation

answer_postponed

Is the answer of the respondent postponed when filling out? The parameter is active only with the highest level of survey security.

null – Survey not filled out
0 – Filling out not postponed
1 – Filling out postponed

email

Email address of the respondent

label1

Value of the first optional label. Label active if the respondent was added from user contact.

label2

Value of the second optional label. Label active if the respondent was added from user contact.

label3

Value of the third optional label. Label active if the respondent was added from user contact.

label4

Value of the fourth optional label. Label active if the respondent was added from user contact.

label5

Value of the fifth optional label. Label active if the respondent was added from user contact.

label6

Value of the sixth optional label. Label active if the respondent was added from user contact.

label7

Value of the seventh optional label. Label active if the respondent was added from user contact.

label8

Value of the eighth optional label. Label active if the respondent was added from user contact.

label9

Value of the ninth optional label. Label active if the respondent was added from user contact.

label10

Value of the tenth optional label. Label active if the respondent was added from user contact.

label11

Value of the eleventh optional label. Label active if the respondent was added from user contact.

label12

Value of the twelfth optional label. Label active if the respondent was added from user contact.

label13

Value of the thirteenth optional label. Label active if the respondent was added from user contact.

label14

Value of the fourteenth optional label. Label active if the respondent was added from user contact.

label15

Value of the fifteenth optional label. Label active if the respondent was added from user contact.

survey_link

Unique link to the survey intended for a given respondent. The parameter is active only with the highest level of survey security.

Respondent list

URL

(GET) https://www.startquestion.com/api/v2/respondents/:id_survey

Optional parameters (POST)

Name

Description

limit

Limit for the number of filled out surveys

offset

Offset for the list

Sample response

{
"total":"20",
"list":[{
"id":100824,
"token":"549E56",
"date_token_generate":"2011-11-25 22:27:42",
"date_invitaion_send":null,
"date_survey_open":null,
"date_survey_answer":null,
"email":"jan@kowalski.pl",
"label1":"Jan",
"label2":"Kowalski",
"label3":"600 700 800",
"label4":"",
"label5":"",
"answer_postponed":null
},{
...
}]
}

Returned errors

  • 401 Unauthorized – If the user refers to a foreign resource.

  • 404 Not Found – If a survey with the specified :id_survey was not found.

  • 404 Not Found – If respondents were not found.

  • 406 Not Acceptable – If the :id_survey parameter was not provided.

Searching respondents

URL

(GET)https://www.startquestion.com/api/v2/respondents/search/:id_survey

Optional parameters (POST)

Name

Description

limit

Limit for the number of filled out surveys

offset

Offset for the list

token

Searching for a respondent by the token

email

Searching for a respondent by the email address

date_generate

Searching for a respondent by the date of adding them to the survey. The date must be provided in the following format: YYYY-MM-DD (e.g. 2011-11-20). All respondents added on that date will be searched through.

date_invitaion_send

Searching for a respondent by the date of sending the invitation. The date must be provided in the following format: YYYY-MM-DD (e.g. 2011-11-20). All respondents to whom an invitation was sent on that date will be searched through.

date_survey_open

Searching for a respondent by the date first opening of the survey. The date must be provided in the following format: YYYY-MM-DD (e.g. 2011-11-20). All respondents who opened the survey on that date will be searched through.

date_survey_answer

Searching for a respondent by the date first filling out of the survey. The date must be provided in the following format: YYYY-MM-DD (e.g. 2011-11-20). All respondents who opened the survey on that date will be searched through.

label1

Searching for a respondent by the value of label 1

label2

Searching for a respondent by the value of label 2

label3

Searching for a respondent by the value of label 3

label4

Searching for a respondent by the value of label 4

label5

Searching for a respondent by the value of label 5

label6

Searching for a respondent by the value of label 6

label7

Searching for a respondent by the value of label 7

label8

Searching for a respondent by the value of label 8

label9

Searching for a respondent by the value of label 9

label10

Searching for a respondent by the value of label 10

Sample response

{
"total":"20",
"list":[{
"id":100824,
"token":"549E56",
"date_token_generate":"2011-11-25 22:27:42",
"date_invitaion_send":null,
"date_survey_open":null,
"date_survey_answer":null,
"email":"jan@kowalski.pl",
"label1":"Jan",
"label2":"Kowalski",
"label3":"600 700 800",
"label4":"",
"label5":"",
"answer_postponed":null
},{
...
}]
}

Returned errors

  • 401 Unauthorized – If the user refers to a foreign resource.

  • 404 Not Found – If a survey with the specified :id_survey was not found.

  • 404 Not Found – If respondents were not found.

  • 406 Not Acceptable – If the :id_survey parameter was not provided.

Adding a respondent to the survey

URL

(GET) https://www.startquestion.com/api/v2/respondents/add

Parameters (POST)

Name

Description

id_survey

ID of the survey to which the contact is assigned

id_contact

ID of the contact which is assigned to the survey

date_invitation_send

Date of sending an invitation to the respondent (mailing was done by the customer’s application).
Optional parameter

Sample response

{ 
"id_respondent":"101019"
}

Returned errors

  • 401 Unauthorized – If the user refers to a foreign resource (survey/contact).

  • 404 Not Found – If a survey with the specified :id_survey was not found.

  • 404 Not Found – If a contact with the specified :id_contact was not found.

  • 406 Not Acceptable – If the :id_survey parameter was not provided.

  • 406 Not Acceptable – If the :id_contact parameter was not provided.

  • 409 Conflict – If the contact has already been added to the survey.

Deleting a respondent

URL

(GET) https://www.startquestion.com/api/v2/respondents/delete

Parameters (POST)

Name

Description

id_survey

ID of the survey to which the contact belongs

id_respondent

Respondent ID

Sample response

{ 
"status":"ok"
}

Returned errors

  • 401 Unauthorized – If the user refers to a foreign resource (survey/contact).

  • 404 Not Found – If a survey with the specified :id_survey was not found.

  • 404 Not Found – If a respondent with the specified :id_respondent was not found.

Batch upload of respondents

The process is to enable sending respondents in grouped packages, for which one mailing can be created at the end The whole process is as follows:

Create a new batch (POST webankieta.pl/api/v2/respondents/batch) after successful batch creation, you will receive its id under which you will group individual respondent batches.

1. CREATING - POST

(POST) startquestion.com/api/respondents/batch

Parameters (POST)

Name

Description

survey_id

ID of the survey to which respondents will be imported.

Sample response

{    
"batch_id":"89f7fcdb-c8c9-4414-8ec7-423780f66901"
}

2. DOWNLOADING - GET

(GET) startquestion.com/api/respondents/batch

Parameters (GET)

Name

Description

batch_id

ID of the batch

Returned values in json:

Name

Description

id

ID of the batch

account_id

Account ID

survey_id

Survey ID

patches

ID list of assigned patches

Returned errors

  • 401 Unauthorized – If the user refers to a foreign resource (survey/contact).

  • 400 An error occurred – If the operation is unsuccessful

Troubleshooting:

  • we know of cases where many of the same email addresses are imported in one batch. When sending mailings using the created batch, all messages are sent at once. It may happen that the mail server will block these messages due to a potential SPAM (sending many identical messages in one second). We suggest to limit the existence of many identical email addresses in the batch as much as possible within one mailing process.

Add new respondents batches to the previously created batch (POST webankieta.pl/api/v2/respondents/patch). Each batch must be sent with the batch_id parameter equal to the one created earlier. The recommended number of respondents in one package is 20.

3. SENDING RESPONDENT BATCH - POST

(POST) startquestion.com/api/v2/respondents/patch

Parameters (POST)

Name

Description

batch_id

ID of the batch

respondents

respondent table (recommended up to 20)

respondents

email

labels

table of respondent label value (max 15)

Returned json values:

Name

Description

patch_id

Patch ID

Sample use:

In API operations, the required format of the data provided in the request parameters is application/x-www-form-urlencoded.

A data portion in the form of JSON should be converted to the above-mentioned format. For example:

{
"batch_id": "example_batch_id",
"respondents": [
{
"email": "jan.kowalski@webankieta.pl",
"labels": [
"Warszawa",
"Support"
]
},
{
"email": "tomasz.nowak@webankieta.pl",
"labels": [
"Łódź",
"IT"
]
},
{
"email": "zenon.martyniuk@webankieta.pl",
"labels": [
"Warszawa",
"IT"
]
}
]
}

Convert it to the following form:

batch_id=example_batch_id&respondents[0][email]=jan.kowalski%40webankieta.pl&respondents[0][labels][0]=Warszawa&respondents[0][labels][1]=Support&respondents[1][email]=tomasz.nowak%40webankieta.pl&respondents[1][labels][0]=%C5%81%C3%B3d%C5%BA&respondents[1][labels][1]=IT&respondents[2][email]=zenon.martyniuk%40webankieta.pl&respondents[2][labels][0]=Warszawa&respondents[2][labels][1]=IT

You can do that using the sample Javascript code:

function jsonToUrlEncoded(element,key,list) {
list = list || [];
if(typeof(element)=='object'){
for (var idx in element)
jsonToUrlEncoded(element[idx],key?key+'['+idx+']':idx,list);
} else {
list.push(key+'='+encodeURIComponent(element));
}
return list.join('&');
}

console.log(jsonToUrlEncoded( {OBIEKT} ));

In the {OBIEKT} place, enter the object you want to convert to the format of your choice.

4. DOWNLOADING RESPONDENTS- GET

(GET) startquestion.com/api/v2/respondents/patch

Parameters (GET)

Name

Description

patch_id

Patch ID

Returned json values:

Name

Description

respondents

ID list of respondents created as part of one patch

Returned errors

  • 401 Unauthorized – If the user refers to a foreign resource (survey/contact).

  • 400 An error occurred – If the operation is unsuccessful

Once you have already added all respondents, you can send them all invitations by providing the previous batch_id (POST webankieta.pl/api/v2/mailing/batch). The documentation relating to this step can be found here.

Did this answer your question?