Respondenci
Artur Zbiejcik avatar
Napisane przez Artur Zbiejcik
Zaktualizowano ponad tydzień temu

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

/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.

/respondents/search/:id_survey

Wyszukuje respondentów wg. kryteriów przekazanych w tablicy POST

/respondents/add

Przypisuje kontakt do ankiety

/respondents/:surveyId/update

Aktualizacja danych respondentów

/respondents/:params/anonymize

Anonimizacja danych respondenta

/respondents/delete

Usuwa kontakt z ankiety

/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 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 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 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 przy najwyższym poziomie bezpieczeństwa ankiety.


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.


Czy to odpowiedziało na twoje pytanie?