Respondent do powiązanie kontaktu z ankietą na koncie użytkownika.

Jeden kontakt może być przypisany do wielu ankiet na koncie.

Nazwa	URL	Opis
Lista respondentów	`/respondents/:id_survey`	Zwraca listę wszystkich respondentów z ankiety określonej parametrem `:id_survey`. Respondenci posortowani są wg. adresu email w kolejności alfabetycznej.
Wyszukiwanie respondentów	`/respondents/search/:id_survey`	Wyszukuje respondentów wg. kryteriów przekazanych w tablicy `POST`
Dodanie respondenta do ankiety	`/respondents/add`	Przypisuje kontakt do ankiety
Aktualizacja respondenta	`/respondents/:surveyId/update`	Aktualizacja danych respondentów
Anonimizacja respondenta	`/respondents/:params/anonymize`	Anonimizacja danych respondenta
Usunięcie respondenta	`/respondents/delete`	Usuwa kontakt z ankiety
Batch upload respondentów	`/respondents/batch`	Przesyłanie respondentów zgrupowanymi paczkami, dla których można stworzyć na końcu jeden mailing

Lista operacji dla zasobu

Opis parametrów odpowiedzi

Nazwa/ścieżka	Opis	Możliwe wartości
`id`	ID respondenta
`token`	Unikalny token jednoznacznie identyfikujący respondenta. Używany do jednorazowego wypełniania ankiety przez respondenta. Parametr aktywny tylko ustawieniu dostępu z linkiem indywidualnym dla respondenta.
`offline_distribution`	Informacja o tym, czy zaproszenie do wypełnienia ankiety realizowane jest przez webankieta.pl czy ze strony autora ankiety. Przekazywanie user_tokena w linku do wypełnienia ankiety jest traktowane również jako dystrybucja ze strony autora.	`0` – Link do ankiety wysyłany z webankieta.pl `1` – Link do ankiety wysyłany przez autora (dystrybucja tokenów offline)
`date_generate`	Data dodania respondenta do ankiety
`date_invitaion_send`	Data i godzina wysyłki zaproszenia	`null` – Nie wysyłano zaproszenia do respondenta `0000-00-00 00:00:00` – Zaproszenie oczekuje na wysyłkę `2012-12-06 12:00:00` – Data i godzina wysyłki zaproszenia
`date_survey_open`	Data i godzina pierwszego otwarcia ankiety. Parametr aktywny tylko przy ustawieniu dostępu z linkiem indywidualnym dla respondenta.	`null` – Ankieta nie była otwierana przez respondenta `2012-12-06 12:00:00` – Data i godzina otwarcia ankiety
`date_survey_answer`	Data i godzina wypełnienia ankiety. Parametr aktywny tylko przy ustawieniu dostępu z linkiem indywidualnym dla respondenta.	`null` – Ankieta nie była wypełniana przez respondenta `2012-12-06 12:00:00` – Data i godzina otwarcia ankiety
`answer_postponed`	Czy odpowiedź respondenta odłożona na później w trakcie wypełniania. Parametr aktywny tylko przy ustawieniu dostępu z linkiem indywidualnym dla respondenta.	`null` – Ankieta nie wypełniona `0` – Wypełnianie nie odkładane `1` – Wypełnianie odłożone na później
`email`	Adres e-mail respondenta
`label1`	Wartość pierwszego opcjonalnego atrybutu. Atrybut aktywny, jeśli respondent jest dodany z kontaktów użytkownika.
`label2`	Wartość drugiego opcjonalnego atrybutu. Atrybut aktywny, jeśli respondent jest dodany z kontaktów użytkownika.
`label3`	Wartość trzeciego opcjonalnego atrybutu. Atrybut aktywny, jeśli respondent jest dodany z kontaktów użytkownika.
`label4`	Wartość czwartego opcjonalnego atrybutu. Atrybut aktywny, jeśli respondent jest dodany z kontaktów użytkownika.
`label5`	Wartość piątego opcjonalnego atrybutu. Atrybut aktywny, jeśli respondent jest dodany z kontaktów użytkownika.
`label6`	Wartość szóstego opcjonalnego atrybutu. Atrybut aktywny, jeśli respondent jest dodany z kontaktów użytkownika.
`label7`	Wartość siódmego opcjonalnego atrybutu. Atrybut aktywny, jeśli respondent jest dodany z kontaktów użytkownika.
`label8`	Wartość ósmego opcjonalnego atrybutu. Atrybut aktywny, jeśli respondent jest dodany z kontaktów użytkownika.
`label9`	Wartość dziewiątego opcjonalnego atrybutu. Atrybut aktywny, jeśli respondent jest dodany z kontaktów użytkownika.
`label10`	Wartość dziesiątego opcjonalnego atrybutu. Atrybut aktywny, jeśli respondent jest dodany z kontaktów użytkownika.
`label11`	Wartość jedenastego opcjonalnego atrybutu. Atrybut aktywny, jeśli respondent jest dodany z kontaktów użytkownika.
`label12`	Wartość dwunastego opcjonalnego atrybutu. Atrybut aktywny, jeśli respondent jest dodany z kontaktów użytkownika.
`label13`	Wartość trzynastego opcjonalnego atrybutu. Atrybut aktywny, jeśli respondent jest dodany z kontaktów użytkownika.
`label14`	Wartość czternastego opcjonalnego atrybutu. Atrybut aktywny, jeśli respondent jest dodany z kontaktów użytkownika.
`label15`	Wartość piętnastego opcjonalnego atrybutu. Atrybut aktywny, jeśli respondent jest dodany z kontaktów użytkownika.
`survey_link`	Unikalny link do ankiety przeznaczony dla danego respondenta. Parametr aktywny tylko ustawieniu dostępu z linkiem indywidualnym dla respondenta.

Lista respondentów

URL

(GET) https://www.webankieta.pl/api/v2/respondents/:id_survey

Parametry opcjonalne (POST)

Nazwa	Opis
`limit`	Limit na liczbę wypełnień
`offset`	Offset na listę

Przykładowa odpowiedź

{
	"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":"[email protected]",
		"label1":"Jan",
		"label2":"Kowalski",
		"label3":"600 700 800",
		"label4":"",
		"label5":"",
		"answer_postponed":null
	},{
		...
	}]
}

Zwracane błędy

401 Unauthorized – Jeżeli użytkownik odwołuje się do obcego zasobu.
404 Not Found – Jeżeli nie znaleziono ankiety o podanym :id_survey.
404 Not Found – Jeżeli nie znaleziono respondentów.
406 Not Acceptable – Jeżeli nie przekazano parametru :id_survey.

Wyszukiwanie respondentów

URL

(GET) https://www.webankieta.pl/api/v2/respondents/search/:id_survey

Parametry opcjonalne (POST)

Nazwa	Opis
`limit`	Limit na liczbę wypełnień
`offset`	Offset na listę
`token`	Wyszukiwanie respondenta po tokenie
`email`	Wyszukiwanie respondenta po adresie email
`date_generate`	Wyszukiwanie respondenta po dacie dodania go do ankiety. Data musi być przekazana w formacie `YYYY-MM-DD` (np. 2011-11-20). Zostaną wyszukani wszyscy respondenci dodani tego dnia.
`date_invitaion_send`	Wyszukiwanie respondenta po dacie wysyłki zaproszenia. Data musi być przekazana w formacie `YYYY-MM-DD` (np. 2011-11-20). Zostaną wyszukani wszyscy respondenci, do których wysłano zaproszenie tego dnia.
`date_survey_open`	Wyszukiwanie respondenta po dacie pierwszego otwarcia ankiety. Data musi być przekazana w formacie `YYYY-MM-DD` (np. 2011-11-20). Zostaną wyszukani wszyscy respondenci, którzy otworzyli ankietę tego dnia.
`date_survey_answer`	Wyszukiwanie respondenta po dacie pierwszego wypełnienia ankiety. Data musi być przekazana w formacie `YYYY-MM-DD` (np. 2011-11-20). Zostaną wyszukani wszyscy respondenci, którzy otworzyli ankietę tego dnia.
`label1`	Wyszukiwanie respondenta po wartości atrybutu 1
`labelx`	Wyszukiwanie respondenta po wartości atrybutu x

Przykładowa odpowiedź

{
	"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":"[email protected]",
		"label1":"Jan",
		"label2":"Kowalski",
		"label3":"600 700 800",
		"label4":"",
		"label5":"",
		"answer_postponed":null
	},{
		...
	}]
}

Zwracane błędy

401 Unauthorized – Jeżeli użytkownik odwołuje się do obcego zasobu.
404 Not Found – Jeżeli nie znaleziono ankiety o podanym :id_survey.
404 Not Found – Jeżeli nie znaleziono respondentów.
406 Not Acceptable – Jeżeli nie przekazano parametru :id_survey.

Dodanie respondenta do ankiety

URL

(GET) https://www.webankieta.pl/api/v2/respondents/add

Parametry (POST)

Nazwa	Opis
`id_survey`	ID ankiety do której przypisujemy kontakt
`id_contact`	ID kontaktu, który przypisujemy do ankiety
`date_invitaion_send`	Data wysyłki zaproszenia do respondenta (wysyłka nastąpiła po stronie aplikacji klienckiej). Parametr opcjonalny

Przykładowa odpowiedź

{ 
"id_respondent":"101019" 
}

Zwracane błędy

401 Unauthorized – Jeżeli użytkownik odwołuje się do obcego zasobu (ankiety/kontaktu).
404 Not Found – Jeżeli nie znaleziono ankiety o podanym :id_survey.
404 Not Found – Jeżeli nie znaleziono kontaktu o podanym :id_contact.
406 Not Acceptable – Jeżeli nie przekazano parametru :id_survey.
406 Not Acceptable – Jeżeli nie przekazano parametru :id_contact.
409 Conflict – Jeżeli kontakt został dodany już wcześniej do ankiety.

Aktualizacja respondenta

Endpoint obsługuje tylko respondentów z wysyłki na email.
Procesowanie update-u odbywa się w procesie offline dlatego zmiany mogą nie być widoczne od razu.
Przyjmujemy maksymalnie 100 rekordów respondentów per request.

URL

(POST) https://www.webankieta.pl/api/v2/respondents/:surveyId/update

(POST) https://www.webankieta.pl/api/v3/respondents/:surveyId/update

Parametry (GET)

Nazwa	Opis
`surveyId`	ID ankiety do której należy respondent

Parametry (BODY)

{
    "respondents":[
        {
            "id": 142042042,
            "email": „[email protected]",
            "labels": [
                {"id": 1, "value":"archiwum"},
                {"id": 2, "value":"archiwum"},
                {"id": 3, "value":"archiwum"}
            ]
        },
        {
            "id": 142042043,
            "email": „[email protected]",
            "labels": [
                {"id": 3, "value":"null"},
                {"id": 2, "value":"null"},
                {"id": 1, "value":"null"}
            ]
        },
        {
            "id": 142042044,
            "email": „j,[email protected]",
            "labels": [
                {"id": 15, "value":"testowa wartość"},
                {"id": 2, "value":"polska"},
                {"id": 3, "value": null}
            ]
        }
    ]
}

Kody odpowiedzi
202 - update został przyjęty do procesowania.

Anonimizacja respondenta

Endpoint obsługuje respondentów z wysyłki na email oraz dystrybucji własnej
Procesowanie update-u odbywa się offline dlatego zmiany mogą nie być widoczne od razu.
Jeżeli chcesz zanonimizować respondentów po batchId musisz wcześniej zapamiętać po swojej stronie, aby użyć go w requeście

URLe

Anonimizacja wszystkich respondentów w ankiecie

(POST) https://www.webankieta.pl/api/v2/respondents/:surveyId/anonymize

Anonimizacja wszystkich respondentów z danego importu (batchId)

(POST) https://www.webankieta.pl/api/v2/respondents/:surveyId/batch/:batchId/anonymize

Anonimizacja wszystkich respondentów ze wskazanego mailingu.

(POST) https://www.webankieta.pl/api/v2/respondents/:surveyId/mailing/:mailingId/anonymize

Parametry (BODY) - wersja dla wysyłki na e-mail

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

Parametry (BODY) - wersja dla dystrybucji własnej

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

W tabeli fields, przekazujemy pola, które mają zostać zanonimizowane.

Kolejne numerki to numery atrybutów, które chcesz zanonimizować.

Jeżeli chcesz zanonimizować atrybuty 1, 3 i 5 przekazujesz tylko te numery do tablicy fields.

Po zanonimizowaniu:

wartość emaila jest zmieniana na [email protected]
wartość atrybutów jest zmieniana na xyzabc

Usuwanie respondenta

URL

(GET) https://www.webankieta.pl/api/v2/respondents/delete

Parametry (POST)

Nazwa	Opis
`id_survey`	ID ankiety do której należy respondent
`id_respondent`	ID respondenta

Przykładowa odpowiedź

{ 
"status":"ok" 
}

Zwracane błędy

401 Unauthorized – Jeżeli użytkownik odwołuje się do obcego zasobu (ankiety/kontaktu).
404 Not Found – Jeżeli nie znaleziono ankiety o podanym :id_survey.
404 Not Found – Jeżeli nie znaleziono respondenta o podanym :id_respondent.

Batch upload respondentów

Proces ma umożliwić przesyłanie respondentów zgrupowanymi paczkami, dla których można stworzyć na końcu jeden mailing. Cały proces wygląda w skrócie następująco:

Tworzymy nowy tzw. batch (POST webankieta.pl/api/v2/respondents/batch) po sukcesywnym utworzeniu batcha odtrzymamy jego id pod którym będziemy grupować poszczególne paczki respondentów.

1. TWORZENIE - POST

(POST) webankieta.pl/api/respondents/batch

Parametry (POST)

Nazwa	Opis
`survey_id`	ID ankiety do której będziemy importować respondentów

Przykładowa odpowiedź

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

2. POBIERANIE - GET

(GET) webankieta.pl/api/respondents/batch

Parametry (GET)

Nazwa	Opis
`batch_id`	ID batch’a

Zwracane wartości w json:

Nazwa	Opis
`id`	ID batch’a
`account_id`	ID konta
`survey_id`	ID ankiety
`patches`	lista ID przynależnych patchów

Zwracane błędy

401 Unauthorized – Jeżeli użytkownik odwołuje się do obcego zasobu (ankiety/kontaktu).
400 An error ocured – Jeżeli opracja skończy się niepowodzeniem

Troubleshooting:

znane są nam przypadki, gdzie w jednym batchu importowanych jest wiele takich samych adresów e-mail. Przy wysyłce mailingu z użyciem stworzonego batcha wszystkie wiadomości są wysyłane w jednej chwili - może się zdarzyć, że serwer pocztowy zablokuje te wiadomości ze względu na potencjalny SPAM (wiele takich samych wiadomości w jednej sekundzie). Proponujemy, aby w ramach jednej wysyłki maksymalnie ograniczyć istnienie wielu takich samych adresów mailowych w batchu.

Dodajemy do wcześniej utworzonego batcha kolejne paczki respondentów (POST webankieta.pl/api/v2/respondents/patch). Każda paczka musi zostać wysłana z parametrem batch_id równym utworzonemu wcześniej, zalecana ilość respondentów w jednej paczce to 20 sztuk.

3. PRZESYŁANIE PACZKI RESPONDENTÓW - POST

(POST) webankieta.pl/api/v2/respondents/patch

Parametry :

Nazwa	Opis
`batch_id`	ID batch’a
`respondents`	tablica respondentów (zalecana ilość do 20 sztuk)

Body (x-www-form-urlencoded):

respondents[0,1,...,n]	0,1,...,n - liczba porządkowa respondenta w żądaniu
`email`	e-mail respondenta
`labels`	tablica wartości atrybutów respondenta (max 15)

Zwracane wartości:

Nazwa	Opis
`patch_id`	ID patch’a

Przykład zastosowania:

Porcję danych w postaci JSON należy przekonwertować na format do przekazania parametrów poprzez URL. Przykładowo:

{
"batch_id": "example_batch_id",
"respondents": [
   {
      "email": "[email protected]",
      "labels": [
         "Warszawa",
         "Support"
      ]
   },
   {
      "email": "[email protected]",
      "labels": [
         "Łódź",
         "IT"
      ]
   },
   {
      "email": "[email protected]",
      "labels": [
          "Warszawa",
          "IT"
       ]
   }
   ]
}

Należy przekonwertować do takiej postaci:

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

Taką porcję danych przekazujemy w żądaniu jako x-www-form-urlencoded w żądaniu POST.

W przypadku wykonania żądania GET - system będzie usiłował wykonać inną operację.

Przykład cURL:

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%[email protected]' \
--data-urlencode 'respondents%5B0%5D%5Blabels%5D%5B0%5D=hr' \
--data-urlencode 'respondents%5B0%5D%5Blabels%5D%5B1%5D=wrocław'

Konwersję JSON do tego formatu można dokonać np. z użyciem przykładowego kodu Javascript:

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} ));

W miejscu {OBIEKT} musimy wstawić obiekt JSON, który chcemy przekonwertować na

potrzebny nam format.

4. POBIERANIE RESPONDENTÓW - GET

(GET) webankieta.pl/api/v2/respondents/patch

Parametry (GET)

Nazwa	Opis
`patch_id`	ID patch’a

Zwracana wartości json:

Nazwa	Opis
`respondents`	lista ID respondentów utworzonych w ramach danego patcha

Zwracane błędy

401 Unauthorized – Jeżeli użytkownik odwołuje się do obcego zasobu (ankiety/kontaktu).
400 An error ocured – Jeżeli opracja skończy się niepowodzeniem

Jeśli dodaliśmy już wszystkich respondentów, możemy dla nich wszystkich zlecić wysyłkę zaproszeń podając wcześniejsze batch_id (POST webankieta.pl/api/v2/mailing/batch). Dokumentacja dotycząca tego kroku znajduje się tutaj.