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ę 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
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ń, domyślna wartość to 500
`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ń, domyślna wartość to 500
`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/v2/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/v2/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.

Respondenci

Lista operacji dla zasobu

Lista respondentów

URL

Parametry opcjonalne (POST)

Przykładowa odpowiedź

Zwracane błędy

Wyszukiwanie respondentów

URL

Parametry opcjonalne (POST)

Przykładowa odpowiedź

Zwracane błędy

Dodanie respondenta do ankiety

URL

Parametry (POST)

Przykładowa odpowiedź

Zwracane błędy

Aktualizacja respondenta

Anonimizacja respondenta

Usuwanie respondenta

Batch upload respondentów

1. TWORZENIE - POST

Parametry (POST)

Przykładowa odpowiedź

2. POBIERANIE - GET

Parametry (GET)

Zwracane wartości w json:

Zwracane błędy

3. PRZESYŁANIE PACZKI RESPONDENTÓW - POST

Parametry :

Body (x-www-form-urlencoded):

Zwracane wartości:

4. POBIERANIE RESPONDENTÓW - GET

Parametry (GET)

Zwracana wartości json:

Zwracane błędy