Respondents | Startquestion Help Center

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 access.
`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 access.	`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 access.	`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 access.	`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 access.

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-D`D (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.