A respondent is used to link a contact with a survey in the user account.

A single contact can be assigned to multiple surveys on the account.

List of operations for the resource

Description of response parameters

---

List of respondents

URL

(GET) https://app.customerhero.com/api/v2/respondents/:id_survey

Optional parameters (POST)

Example 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 references a foreign resource.

• 404 Not Found – If a survey with the given :id_survey is not found.

• 404 Not Found – If no respondents are found.

• 406 Not Acceptable – If the :id_survey parameter is not passed.

---

Searching for respondents

URL

(GET) https://app.customerhero.com/api/v2/respondents/search/:id_survey

Optional parameters (POST)

Example 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 references a foreign resource.

• 404 Not Found – If a survey with the given :id_survey is not found.

• 404 Not Found – If no respondents are found.

• 406 Not Acceptable – If the :id_survey parameter is not passed.

---

Adding a respondent to a survey

URL

(GET) https://app.customerhero.com/api/v2/respondents/add

Parameters (POST)

Example response

{ 
"id_respondent":"101019" 
}

Returned errors

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

• 404 Not Found – If a survey with the given :id_survey is not found.

• 404 Not Found – If a contact with the given :id_contact is not found.

• 406 Not Acceptable – If the :id_survey parameter is not passed.

• 406 Not Acceptable – If the :id_contact parameter is not passed.

• 409 Conflict – If the contact was previously added to the survey.

---

Updating a respondent

• The endpoint supports only respondents from email sending.

• Update processing takes place in an offline process, so changes may not be visible immediately.

• We accept a maximum of 100 respondent records per request.
  
  

URL

(POST) https://app.customerhero.com/api/v2/respondents/:surveyId/update

(POST) https://app.customerhero.com/api/v3/respondents/:surveyId/update

Parameters (GET)

Parameters (BODY)

{
    "respondents":[
        {
            "id": 142042042,
            "email": „najnowszy@webankieta.pl",
            "labels": [
                {"id": 1, "value":"archive"},
                {"id": 2, "value":"archive"},
                {"id": 3, "value":"archive"}
            ]
        },
        {
            "id": 142042043,
            "email": „nowy@webankieta.pl",
            "labels": [
                {"id": 3, "value":"null"},
                {"id": 2, "value":"null"},
                {"id": 1, "value":"null"}
            ]
        },
        {
            "id": 142042044,
            "email": „j,kowalski@webankieta.pl",
            "labels": [
                {"id": 15, "value":"test value"},
                {"id": 2, "value":"poland"},
                {"id": 3, "value": null}
            ]
        }
    ]
}

Response codes
202 - the update was accepted for processing.

---

Anonymizing a respondent

• The endpoint supports respondents from email sending and own distribution

• Update processing takes place offline, so changes may not be visible immediately.

• If you want to anonymize respondents by batchId, you must remember it on your side beforehand to use it in the request.
  
  

URLs

Anonymization of all respondents in the survey

(POST) https://app.customerhero.com/api/v2/respondents/:surveyId/anonymize

Anonymization of all respondents from a given import (batchId)

(POST) https://app.customerhero.com/api/v2/respondents/:surveyId/batch/:batchId/anonymize

Anonymization of all respondents from the specified mailing.

(POST) https://app.customerhero.com/api/v2/respondents/:surveyId/mailing/:mailingId/anonymize

Parameters (BODY) - version for e-mail sending

{
   "fields": [ 
      "email", 1, 2, 3, 5
   ] 
}

Parameters (BODY) - version for own distribution

{
   "fields": [ 
      1, 3, 5
   ] 
}

In the fields array, we pass the fields that are to be anonymized.

The consecutive numbers are the attribute numbers you want to anonymize.

If you want to anonymize attributes 1, 3, and 5, you pass only these numbers to the fields array.

After anonymization:

• the e-mail value is changed to anonymous@xyz.abc

• the value of the attributes is changed to xyzabc

---

Deleting a respondent

URL

(GET) https://app.customerhero.com/api/v2/respondents/delete

Parameters (POST)

Example response

{ 
"status":"ok" 
}

Returned errors

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

• 404 Not Found – If a survey with the given :id_survey is not found.

• 404 Not Found – If a respondent with the given :id_respondent is not found.

Batch upload of respondents

The process is intended to enable the sending of respondents in grouped batches, for which a single mailing can be created at the end. The entire process briefly looks as follows:

We create a new so-called batch (POST webankieta.pl/api/v2/respondents/batch). After successfully creating the batch, we will receive its id under which we will group individual batches (patches) of respondents.

1. CREATION - POST

(POST) customerhero.com/api/v2/respondents/batch

Parameters (POST)

Example response

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

2. RETRIEVING - GET

(GET) customerhero.com/api/v2/respondents/batch

Parameters (GET)

Returned values in json:

Returned errors

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

• 400 An error occurred – If the operation fails
  
  

Troubleshooting:

• We know of cases where many of the same e-mail addresses are imported in a single batch. When sending a mailing using the created batch, all messages are sent at once - it may happen that the mail server blocks these messages due to potential SPAM (many of the same messages in one second). We suggest minimizing the existence of multiple identical email addresses in a batch within a single sending.

We add subsequent packages (patches) of respondents to the previously created batch (POST webankieta.pl/api/v2/respondents/patch). Each package must be sent with the batch_id parameter equal to the previously created one, the recommended number of respondents in one package is 20 pieces.

3. SENDING A PACKAGE OF RESPONDENTS - POST

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

Parameters:

Body (x-www-form-urlencoded):

Returned values:

Example of use:

A JSON data portion must be converted into a format for passing parameters via URL. 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"
       ]
   }
   ]
}

It should be converted to this 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

We pass this portion of data in the request as x-www-form-urlencoded in a POST request.

If a GET request is executed - the system will try to perform another operation.

cURL example:

curl --location 'https://www.webankieta.pl/api/v2/respondents/patch?survey_id=XYZ&batch_id=xxxxxxx' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer xxxxx' \
--data-urlencode 'respondents%5B0%5D%5Bemail%5D=test@test.pl' \
--data-urlencode 'respondents%5B0%5D%5Blabels%5D%5B0%5D=hr' \
--data-urlencode 'respondents%5B0%5D%5Blabels%5D%5B1%5D=wrocław'

JSON conversion to this format can be done, for example, using 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( {OBJECT} ));

In place of {OBJECT}, we must insert the JSON object that we want to convert into the format we need.

4. RETRIEVING RESPONDENTS - GET

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

Parameters (GET)

Returned json values:

Returned errors

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

• 400 An error occurred – If the operation fails

If we have already added all respondents, we can order the sending of invitations for all of them by providing the earlier batch_id (POST customerhero.com/api/v2/mailing/batch). Documentation regarding this step can be found here.