Dokumentacja REST API

PhishSpot udostępnia REST API w formacie JSON pod adresem https://platform.phishspot.com/api/v1. Obejmuje ono praktycznie wszystko, co można zrobić w aplikacji administracyjnej: budować, planować i analizować kampanie, zarządzać odbiorcami/grupami/szablonami/kursami/mediami/domenami/autopilotami oraz przesyłać wyniki do własnych narzędzi.

Ten rozdział dokumentuje szczegółowo każdy punkt końcowy — parametry, treści żądań, pola odpowiedzi i kody statusu — abyś mógł zintegrować się bez czytania kodu źródłowego. Model zdarzeń oparty na powiadomieniach push opisano w Rozdziale 26 Webhooki; interfejs AI w języku naturalnym oferujący te same możliwości opisano w Rozdziale 29 Serwer MCP.

Jak czytać ten rozdział

§27.1 i §27.2 opisują uwierzytelnianie, formaty identyfikatorów, stronicowanie oraz odpowiedzi błędów wspólne dla wszystkich punktów końcowych — sekcje poszczególnych punktów końcowych poniżej wymieniają tylko ich dodatkowe kody statusu. Każdy punkt końcowy zawiera swoje parametry (path / query / body), gotowy do uruchomienia przykład curl, pola odpowiedzi oraz przykładową odpowiedź.

27.1 Uwierzytelnianie

Każde uwierzytelnione żądanie musi przesyłać token API jako nagłówek bearer:

Authorization: Bearer <token>

Token można uzyskać na jeden z dwóch sposobów:

Z interfejsu administracyjnego (zalecane). Ustawienia konta → Tokeny API → Nowy token (zobacz Rozdział 14). Skopiuj wartość — jest ona wyświetlana tylko raz. Przechowuj ją w menedżerze sekretów.

Z API. Wyślij metodą POST email + password (oraz otp_attempt, jeśli włączone jest uwierzytelnianie dwuskładnikowe) na adres /auth:

curl -X POST https://platform.phishspot.com/api/v1/auth \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"secret"}'

{ "token": "abc123…", "user": { "id": 2, "email": "admin@example.com" } }

Pole	Typ	Opis
email	string	Wymagane. Adres e-mail użytkownika.
password	string	Wymagane. Hasło użytkownika.
otp_attempt	string	Wymagane tylko wtedy, gdy użytkownik ma włączone uwierzytelnianie dwuskładnikowe.

Token należy do pojedynczego użytkownika i dziedziczy jego przynależności do kont. Traktuj go jak hasło. Wszystkie poniższe przykłady zakładają, że $TOKEN zawiera prawidłowy token.

27.2 Konwencje

• Bazowy URL: https://platform.phishspot.com/api/v1. Wszystkie poniższe ścieżki są względne wobec niego.
• Typ treści: wysyłaj Content-Type: application/json; treści żądań i odpowiedzi są w formacie JSON.
• Czasy: ISO-8601 (2026-05-20T14:22:33.000Z), UTC, o ile nie zaznaczono inaczej. Wartość wejściowa kampanii scheduled_at jest interpretowana w strefie czasowej konta.
• Identyfikatory w ścieżkach: wszędzie tam, gdzie ścieżka przyjmuje :id, możesz przekazać albo całkowity klucz główny (/campaigns/42), albo prefiksowany identyfikator rekordu (/campaigns/camp_0u1k…). Odpowiedzi zawsze udostępniają całkowite id; niektóre udostępniają również prefiksowany identyfikator.
• account_id: trasy zagnieżdżone przyjmują account_id w ścieżce; akceptuje on całkowity identyfikator lub prefiksowany identyfikator acct_…. Swój znajdziesz przez GET /accounts.
• Zakres konta: token może działać tylko na kontach, do których należy jego użytkownik. Żądanie rekordu z innego konta zwraca 404 — API nigdy nie potwierdza, że dane innego najemcy istnieją.
• Role: punkty końcowe odczytu wymagają dowolnej roli (w tym member). Punkty końcowe zapisu (POST/PATCH/PUT/DELETE oraz akcje zmieniające stan) wymagają roli admin lub editor; token z rolą member otrzymuje 403. Akcje administracyjne zespołu/rozliczeń oraz domen platformy wymagają roli admin.
• Stronicowanie: punkty końcowe obsługujące stronicowanie przyjmują ?page=N (liczone od 1), a czasem ?per_page=M lub ?limit=M; wartości domyślne są podane przy każdym punkcie końcowym. Listy bez stronicowania zwracają pełny uporządkowany zbiór.

Wspólne odpowiedzi błędów

O ile punkt końcowy nie stanowi inaczej, dotyczą one każdego wywołania (poniżej powtarzane są tylko kody specyficzne dla danego punktu końcowego):

Kod	Treść	Kiedy
401 Unauthorized	(puste)	Brak lub nieprawidłowy token Authorization.
403 Forbidden	{"error":"You are not authorized to perform this action"}	Token prawidłowy, ale rola użytkownika jest niewystarczająca dla tej akcji.
404 Not Found	{"error":"Resource not found"}	Brak takiego rekordu lub rekord należy do konta, do którego token nie ma dostępu.
422 Unprocessable Content	{"errors":{"field":["message"]}} (lub {"errors":["message"]} dla punktów końcowych akcji)	Walidacja nie powiodła się; sprawdź errors.
429 Too Many Requests	(różne)	Przekroczono limit żądań; zobacz §27.17. Nagłówek Retry-After wskazuje, kiedy ponowić próbę.

27.3 Tożsamość i konta

GET /me

Zwraca użytkownika stojącego za tokenem.

Parametry: brak (tylko token bearer).

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/me

Odpowiedź 200 OK

Pole	Typ	Opis
id	integer	Identyfikator użytkownika.
email	string	Adres e-mail użytkownika.
name	string	Nazwa wyświetlana.
locale	string	Ustawienia językowe interfejsu (en / pl).
accounts	array	Konta, na których token może działać (zobacz GET /accounts).

GET /accounts

Wyświetla wszystkie konta, do których użytkownik tokenu ma dostęp. Użyj tego, aby znaleźć account_id dla tras zagnieżdżonych.

Parametry: brak.

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/accounts

Odpowiedź 200 OK — tablica obiektów:

Pole	Typ	Opis
id	integer	Identyfikator konta (używany w ścieżkach zagnieżdżonych).
prefix_id	string	Prefiksowany identyfikator (acct_…).
name	string	Nazwa konta.
locale	string	Domyślne ustawienia językowe konta.

[{ "id": 11, "name": "Cydefen Tests", "locale": "pl", "prefix_id": "acct_3kf…" }]

27.4 Kampanie

Zarządzaj kampaniami symulacji phishingu: twórz i edytuj wersje robocze, prowadź kampanię przez jej cykl życia (start, pauza, zatrzymanie, anulowanie), zaplanuj przyszłą wysyłkę, duplikuj oraz odczytuj wyniki, postęp odbiorców, odpowiedzi i oś czasu zdarzeń dla pojedynczego kontaktu.

Autoryzacja jest egzekwowana per konto: kampania jest dostępna tylko wtedy, gdy należy do jednego z kont, których członkiem jest użytkownik tokenu (bearer) — każda rola w ramach członkostwa może odczytywać i zapisywać; nie ma akcji kampanii dostępnych wyłącznie dla administratorów. Punkty końcowe zmieniające stan dodatkowo wymagają, aby kampania znajdowała się w zgodnym stanie (np. zapauzować można tylko kampanię w stanie in_progress), w przeciwnym razie zwracają 403.

Uwaga

POST /campaigns/:id/start oraz POST /campaigns/:id/schedule wysyłają prawdziwe wiadomości phishingowe do odbiorców kampanii (natychmiast lub o zaplanowanej godzinie). Nie są to przebiegi próbne. Traktuj je jako destrukcyjne, nieodwracalne wysyłki.

Obiekt kampanii zwracany przez show, create, update oraz wszystkie punkty końcowe zmieniające stan jest identyczny i opisany jednokrotnie w sekcji GET /campaigns/:id.

GET /accounts/:account_id/campaigns

Wyświetla listę wszystkich kampanii na koncie, od najnowszych. Użyj go, aby wyliczyć kampanie przed przejściem do szczegółów jednej z nich. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita). Musi być kontem, do którego należy użytkownik tokenu.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/accounts/11/campaigns

Odpowiedź 200 OK — tablica JSON obiektów kampanii (lista pól dla pojedynczego obiektu znajduje się w GET /campaigns/:id), uporządkowana malejąco według created_at.

[
  {
    "id": 42,
    "account_id": 11,
    "name": "Q2 Invoice Lure",
    "state": "in_progress",
    "delivery_mode": "immediate",
    "delivery_schedule": null,
    "created_at": "2026-05-01T09:00:00.000Z",
    "updated_at": "2026-05-02T14:12:00.000Z",
    "email_subject": "Your April invoice is ready",
    "email_content": "<p>Hello {{first_name}}…</p>",
    "landing_html": "<form>…</form>",
    "domain": "officelogin.in",
    "course_id": 7,
    "groups": [{ "id": 3, "name": "Finance" }],
    "statistics": {
      "total_contacts": 120,
      "total_deliverables": 120,
      "completion_percentage": 100.0
    },
    "can_start": false,
    "can_pause": true,
    "can_cancel": true
  }
]

Kody statusu

Kod	Kiedy
200	Kampanie wyświetlone (pusta tablica, jeśli konto nie ma żadnych).
403	Użytkownik tokenu nie jest uprawniony do wyświetlenia konta.
404	account_id nie jest kontem, do którego należy użytkownik tokenu.

POST /accounts/:account_id/campaigns

Tworzy nową roboczą kampanię na koncie. Wszystkie pola treści są opcjonalne przy tworzeniu — wymagane jest tylko name — dzięki czemu możesz utworzyć pustą wersję roboczą i uzupełnić ją za pomocą PATCH. Uwierzytelnianie: Bearer; rola: dowolna rola.

Parametry

Wszystkie parametry treści żądania są opakowane w obiekt campaign.

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita).
campaign[name]	body	string	tak	Nazwa kampanii. Musi być unikalna w obrębie konta (bez uwzględniania wielkości liter).
campaign[delivery_mode]	body	string	nie	Jedna z wartości immediate, scheduled, staggered. Domyślnie immediate.
campaign[delivery_schedule]	body	string	nie	Dowolny ciąg harmonogramu używany wyłącznie, gdy delivery_mode to scheduled (data i czas ISO8601 lub 5-polowy cron). Zamiast tego preferuj punkt końcowy /schedule.
campaign[email_subject]	body	string	nie	Temat wiadomości. Może zawierać znaczniki scalania wiadomości (np. {{first_name}}); nieznane znaczniki nie przejdą walidacji.
campaign[email_content]	body	string	nie	Treść HTML wiadomości. Musi być poprawnym HTML i używać wyłącznie dozwolonych znaczników scalania wiadomości.
campaign[landing_html]	body	string	nie	HTML strony docelowej. Musi być poprawnym HTML i używać wyłącznie dozwolonych znaczników scalania strony docelowej.
campaign[landing_css]	body	string	nie	CSS strony docelowej. Musi być poprawnym CSS.
campaign[landing_page_enabled]	body	boolean	nie	Czy strona docelowa jest serwowana. Domyślnie false.
campaign[platform_domain_id]	body	integer	nie	Identyfikator domeny PlatformDomain (domeny atakującego) używanej do wysyłki i strony docelowej. Wymagany, zanim kampania może wystartować.
campaign[course_id]	body	integer	nie	Identyfikator kursu e-learningowego, do którego przekierowywane są ofiary (używany, gdy end_action_type to redirect_to_course).
campaign[from_email]	body	string	nie	Adres e-mail nadawcy. Wymagany, zanim kampania może wystartować.
campaign[from_name]	body	string	nie	Wyświetlana nazwa nadawcy.
campaign[end_action_type]	body	string	nie	Co dzieje się po działaniu ofiary. Jedna z wartości nothing, redirect_to_course, message_page, redirect_to_url. Domyślnie message_page.
campaign[end_action_url]	body	string	nie	Zewnętrzny adres URL do przekierowania. Wymagany (i musi być http/https, nie może zapętlać się z powrotem do domeny platformy), gdy end_action_type to redirect_to_url.
campaign[end_action_html]	body	string	nie	Niestandardowa strona z komunikatem HTML. Wymagana, gdy end_action_type to message_page (uzupełniana automatycznie wartością domyślną, jeśli pominięta).
campaign[group_ids]	body	array of integer	nie	Identyfikatory grup kontaktów, na które jest kierowana kampania.

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
        "campaign": {
          "name": "Q2 Invoice Lure",
          "delivery_mode": "immediate",
          "email_subject": "Your April invoice is ready",
          "email_content": "<p>Hello {{first_name}}…</p>",
          "from_email": "billing@officelogin.in",
          "from_name": "Accounts Payable",
          "platform_domain_id": 5,
          "end_action_type": "redirect_to_course",
          "course_id": 7,
          "group_ids": [3]
        }
      }' \
  https://platform.phishspot.com/api/v1/accounts/11/campaigns

Odpowiedź 201 Created — nowo utworzony obiekt kampanii (taki sam kształt jak GET /campaigns/:id).

Kody statusu

Kod	Kiedy
201	Kampania utworzona.
400	Obiekt campaign brakuje w treści żądania (ParameterMissing).
403	Użytkownik tokenu nie jest uprawniony do tworzenia kampanii na koncie.
404	account_id nie jest kontem, do którego należy użytkownik tokenu.
422	Walidacja nie powiodła się — np. puste/zduplikowane name, nieprawidłowa wartość enum delivery_mode/end_action_type, niepoprawny HTML/CSS, niedozwolony znacznik scalania lub brakujące end_action_url/end_action_html dla wybranego end_action_type. Treść: { "errors": { "<field>": ["…"] } }.

GET /campaigns/:id

Pobiera pojedynczą kampanię po identyfikatorze (płytka trasa, nie zagnieżdżona pod kontem). Użyj go, aby odczytać pełną treść kampanii oraz flagi akcji informujące, które przejścia są obecnie dozwolone. Uwierzytelnianie: Bearer; rola: dowolna rola.

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator kampanii (camp_… lub liczba całkowita). Musi należeć do konta, którego członkiem jest użytkownik tokenu.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/campaigns/42

Odpowiedź 200 OK — obiekt kampanii.

Pole	Typ	Opis
id	integer	Identyfikator kampanii.
account_id	integer	Identyfikator konta właściciela.
name	string	Nazwa kampanii.
state	string	Stan cyklu życia: draft, in_progress, paused, cancelled, done lub scheduled.
delivery_mode	string	immediate, scheduled lub staggered.
delivery_schedule	string | null	Surowy ciąg harmonogramu dostarczania (znaczący tylko dla trybu scheduled).
created_at	string	Znacznik czasu ISO8601.
updated_at	string	Znacznik czasu ISO8601.
email_subject	string | null	Temat wiadomości.
email_content	string | null	Treść HTML wiadomości.
landing_html	string | null	HTML strony docelowej.
domain	string | null	Nazwa powiązanej domeny PlatformDomain (np. officelogin.in) lub null, jeśli żadna nie jest ustawiona.
course_id	integer | null	Identyfikator powiązanego kursu lub null.
groups	array	Grupy docelowe, każda w postaci { "id": integer, "name": string }.
statistics	object	Obecne tylko wtedy, gdy state to in_progress, paused lub done. Obiekt z total_contacts (integer), total_deliverables (integer), completion_percentage (float).
can_start	boolean	Czy start/schedule jest teraz dozwolone (true dla draft/scheduled).
can_pause	boolean	Czy pause jest teraz dozwolone (true tylko gdy in_progress).
can_cancel	boolean	Czy cancel jest teraz dozwolone (true dla in_progress/paused/scheduled).

{
  "id": 42,
  "account_id": 11,
  "name": "Q2 Invoice Lure",
  "state": "draft",
  "delivery_mode": "immediate",
  "delivery_schedule": null,
  "created_at": "2026-05-01T09:00:00.000Z",
  "updated_at": "2026-05-01T09:00:00.000Z",
  "email_subject": "Your April invoice is ready",
  "email_content": "<p>Hello {{first_name}}…</p>",
  "landing_html": "<form>…</form>",
  "domain": "officelogin.in",
  "course_id": 7,
  "groups": [{ "id": 3, "name": "Finance" }],
  "can_start": true,
  "can_pause": false,
  "can_cancel": false
}

Kody statusu

Kod	Kiedy
200	Kampania zwrócona.
404	Brak kampanii o tym identyfikatorze na jakimkolwiek koncie, do którego należy użytkownik tokenu (obejmuje próby dostępu między kontami).

PATCH /campaigns/:id

Aktualizuje istniejącą kampanię. Edycja jest dozwolona tylko wtedy, gdy kampania znajduje się w stanie draft lub scheduled (polityka autoryzacji odrzuca edycję uruchomionych/zakończonych kampanii). Uwierzytelnianie: Bearer; rola: dowolna rola.

Parametry

Parametry treści żądania są opakowane w obiekt campaign; obowiązują te same dozwolone klucze co przy POST (wszystkie opcjonalne przy aktualizacji — wyślij tylko te pola, które chcesz zmienić).

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator kampanii (camp_… lub liczba całkowita).
campaign[…]	body	—	nie	Dowolny podzbiór kluczy wymienionych w POST /accounts/:account_id/campaigns (name, delivery_mode, delivery_schedule, email_subject, email_content, landing_html, landing_css, landing_page_enabled, platform_domain_id, course_id, from_email, from_name, end_action_type, end_action_url, end_action_html, group_ids[]).

Żądanie

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "campaign": { "email_subject": "Action required: invoice overdue" } }' \
  https://platform.phishspot.com/api/v1/campaigns/42

Odpowiedź 200 OK — zaktualizowany obiekt kampanii (taki sam kształt jak GET /campaigns/:id).

Kody statusu

Kod	Kiedy
200	Kampania zaktualizowana.
400	Obiekt campaign brakuje w treści żądania (ParameterMissing).
403	Kampania nie jest w stanie draft/scheduled (edycja zablokowana) lub użytkownik nie jest uprawniony.
404	Kampania nie została znaleziona na kontach użytkownika.
422	Walidacja nie powiodła się (te same walidacje co przy POST). Treść: { "errors": { … } }.

DELETE /campaigns/:id

Trwale usuwa kampanię i jej rekordy zależne (odbiorców, przesyłki, zdarzenia, odpowiedzi). Dozwolone w dowolnym stanie. Uwierzytelnianie: Bearer; rola: dowolna rola.

Brak parametrów poza tokenem bearer i identyfikatorem w ścieżce.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator kampanii (camp_… lub liczba całkowita).

Żądanie

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/campaigns/42

Odpowiedź 204 No Content — pusta treść.

Kody statusu

Kod	Kiedy
204	Kampania usunięta.
403	Użytkownik nie jest uprawniony do usunięcia kampanii.
404	Kampania nie została znaleziona na kontach użytkownika.

POST /campaigns/:id/start

Ważne

Uruchamia kampanię i wysyła prawdziwe wiadomości phishingowe do wszystkich odbiorców docelowych (partiami w trybie immediate lub zgodnie z harmonogramem dostarczania w pozostałych trybach). Jest to nieodwracalne — po uruchomieniu wiadomości zostają wysłane.

Przenosi kampanię w stanie draft lub scheduled do in_progress i kolejkuje zadania wysyłki. Przed wysłaniem serwer wykonuje kontrolę wstępną gotowości i odrzuca żądanie, jeśli kampania jest niekompletna. Uwierzytelnianie: Bearer; rola: dowolna rola.

Brak parametrów poza tokenem bearer i identyfikatorem w ścieżce.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator kampanii (camp_… lub liczba całkowita).

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/campaigns/42/start

Odpowiedź 200 OK — obiekt kampanii z state: "in_progress".

Kody statusu

Kod	Kiedy
200	Kampania uruchomiona; wysyłki zakolejkowane.
403	Kampania nie jest w stanie umożliwiającym uruchomienie (draft/paused/scheduled).
404	Kampania nie została znaleziona na kontach użytkownika.
422	Kontrola wstępna gotowości nie powiodła się. Treść: { "errors": ["…", "…"] } (płaska tablica czytelnych dla człowieka komunikatów). Przyczyny obejmują: brakujący temat wiadomości, brakującą treść wiadomości, brakujący adres e-mail nadawcy, brak ustawionej domeny platformy, nieaktywną lub zablokowaną do wysyłki domenę platformy, brak odbiorców docelowych oraz braki w akcji końcowej (brakujący kurs dla redirect_to_course, brakujący URL dla redirect_to_url, brakujący HTML dla message_page).

POST /campaigns/:id/stop

Oznacza trwającą kampanię jako done (zakończoną). Użyj go, aby wcześniej zakończyć działającą kampanię; oczekujące wysyłki nie są ponownie kolejkowane. Uwierzytelnianie: Bearer; rola: dowolna rola.

Brak parametrów poza tokenem bearer i identyfikatorem w ścieżce.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator kampanii (camp_… lub liczba całkowita).

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/campaigns/42/stop

Odpowiedź 200 OK — obiekt kampanii z state: "done".

Kody statusu

Kod	Kiedy
200	Kampania oznaczona jako zakończona.
403	Kampania nie jest w stanie in_progress.
404	Kampania nie została znaleziona na kontach użytkownika.
422	Przejście stanu odrzucone przez model. Treść: { "errors": { … } }.

POST /campaigns/:id/pause

Pauzuje trwającą kampanię (stan → paused), wstrzymując dalsze zaplanowane wysyłki. Wznów, wywołując ponownie start. Uwierzytelnianie: Bearer; rola: dowolna rola.

Brak parametrów poza tokenem bearer i identyfikatorem w ścieżce.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator kampanii (camp_… lub liczba całkowita).

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/campaigns/42/pause

Odpowiedź 200 OK — obiekt kampanii z state: "paused".

Kody statusu

Kod	Kiedy
200	Kampania zapauzowana.
403	Kampania nie jest w stanie in_progress.
404	Kampania nie została znaleziona na kontach użytkownika.
422	Przejście stanu odrzucone przez model. Treść: { "errors": { … } }.

POST /campaigns/:id/cancel

Anuluje kampanię (stan → cancelled). Dozwolone ze stanu in_progress, paused lub scheduled (nie ze stanu draft ani z już zakończonych kampanii). Uwierzytelnianie: Bearer; rola: dowolna rola.

Brak parametrów poza tokenem bearer i identyfikatorem w ścieżce.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator kampanii (camp_… lub liczba całkowita).

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/campaigns/42/cancel

Odpowiedź 200 OK — obiekt kampanii z state: "cancelled".

Kody statusu

Kod	Kiedy
200	Kampania anulowana.
403	Kampania nie jest w stanie umożliwiającym anulowanie (in_progress/paused/scheduled).
404	Kampania nie została znaleziona na kontach użytkownika.
422	Przejście stanu odrzucone przez model. Treść: { "errors": { … } }.

POST /campaigns/:id/duplicate

Klonuje kampanię do nowej wersji draft (z nazwą z numerowanym sufiksem, np. "Q2 Invoice Lure (1)"), kopiując treść, grupy docelowe i odbiorców, ale resetując stan, harmonogram i migawkę. Użyj go, aby ponownie uruchomić lub rozgałęzić kampanię. Uwierzytelnianie: Bearer; rola: dowolna rola.

Brak parametrów poza tokenem bearer i identyfikatorem w ścieżce.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator kampanii (camp_… lub liczba całkowita) kampanii źródłowej.

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/campaigns/42/duplicate

Odpowiedź 201 Created — nowy obiekt roboczej kampanii (taki sam kształt jak GET /campaigns/:id), z nowym id i state: "draft".

Kody statusu

Kod	Kiedy
201	Duplikat utworzony.
403	Użytkownik nie jest uprawniony.
404	Kampania źródłowa nie została znaleziona na kontach użytkownika.
422	Zapisanie duplikatu nie powiodło się (walidacja). Treść: { "errors": { … } }.

POST /campaigns/:id/schedule

Ważne

Planuje kampanię tak, aby wysłała prawdziwe wiadomości phishingowe o podanej przyszłej godzinie. Gdy nadejdzie zaplanowany czas, wiadomości zostaną wysłane automatycznie.

Planuje roboczą kampanię (draft) na przyszłą wysyłkę (stan → scheduled). Wykonuje tę samą kontrolę wstępną gotowości co start, a dodatkowo sprawdza poprawność czasu. Uwierzytelnianie: Bearer; rola: dowolna rola.

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator kampanii (camp_… lub liczba całkowita).
scheduled_at	body	string	tak	Docelowy czas wysyłki jako lokalna data i czas (w strefie czasowej konta), bez przesunięcia — np. 2026-06-10T09:00 (wartość produkowana przez pole datetime-local). Jest interpretowany w strefie czasowej konta (z fallbackiem do UTC, jeśli konto jej nie ma) i konwertowany na UTC po stronie serwera. Musi przypadać w przyszłości i co najmniej 5 minut od teraz. Nie jest opakowany w obiekt campaign — wysyłany jako klucz najwyższego poziomu w treści żądania.

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-06-10T09:00" }' \
  https://platform.phishspot.com/api/v1/campaigns/42/schedule

Odpowiedź 200 OK — obiekt kampanii z state: "scheduled".

Kody statusu

Kod	Kiedy
200	Kampania zaplanowana.
403	Kampania nie jest w stanie umożliwiającym uruchomienie (musi być draft).
404	Kampania nie została znaleziona na kontach użytkownika.
422	Planowanie nie powiodło się. Treść: { "errors": ["…"] } (płaska tablica). Przyczyny: puste scheduled_at, niemożliwa do sparsowania data i czas, czas w przeszłości, czas mniej niż 5 minut od teraz lub niepowodzenie kontroli wstępnej gotowości do startu (te same kontrole treści/nadawcy/domeny/odbiorcy/akcji końcowej co przy start).

POST /campaigns/:id/cancel_schedule

Anuluje oczekujący harmonogram, przywracając kampanię do stanu draft i usuwając jej zakolejkowane zadanie wysyłki. Ważne tylko dla kampanii w stanie scheduled. Uwierzytelnianie: Bearer; rola: dowolna rola.

Brak parametrów poza tokenem bearer i identyfikatorem w ścieżce.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator kampanii (camp_… lub liczba całkowita).

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/campaigns/42/cancel_schedule

Odpowiedź 200 OK — obiekt kampanii (stan przywrócony do draft).

Kody statusu

Kod	Kiedy
200	Harmonogram anulowany.
403	Użytkownik nie jest uprawniony (polityka wymaga stanu scheduled).
404	Kampania nie została znaleziona na kontach użytkownika.
422	Kampania nie jest obecnie w stanie scheduled. Treść: { "error": "Campaign is not scheduled (state: <state>); nothing to cancel." } (zwróć uwagę na klucz error w liczbie pojedynczej w tym przypadku).

GET /campaigns/:id/results

Zwraca zagregowane statystyki kampanii: ogólny lejek zaangażowania oraz zestawienia per grupa i per dział. Użyj go do renderowania pulpitów i raportów. Uwierzytelnianie: Bearer; rola: dowolna rola.

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator kampanii (camp_… lub liczba całkowita).

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/campaigns/42/results

Odpowiedź 200 OK — obiekt statystyk.

Pole	Typ	Opis
campaign_id	integer	Identyfikator kampanii.
name	string	Nazwa kampanii.
funnel	object	Ogólny lejek zaangażowania (liczby + współczynniki). Zobacz podpola poniżej.
groups	array	Zestawienie per grupa. Pusta tablica, jeśli kampania nie jest kierowana na żadne grupy. Zobacz podpola poniżej.
departments	array	Zestawienie per dział (kontakty pogrupowane według ich department). Puste, jeśli brak działów. Te same podpola liczbowe co wpis grupy, z name, ale bez id.

Podpola funnel:

Pole	Typ	Opis
sent	integer	Liczba unikalnych kontaktów, do których wiadomość została pomyślnie wysłana.
opened	integer	Liczba unikalnych kontaktów, które otworzyły wiadomość.
clicked	integer	Liczba unikalnych kontaktów, które kliknęły.
submitted	integer	Liczba unikalnych kontaktów, które przesłały dane na stronie docelowej.
trained	integer	Przesyłki, które osiągnęły stan educated (ukończone szkolenie).
replied	integer	Liczba unikalnych kontaktów, które odpowiedziały na wiadomość phishingową (sygnał z bocznego kanału, niewchodzący w skład lejka kliknięć/przesłań).
open_rate	float	opened / sent jako wartość procentowa (1 miejsce po przecinku).
click_rate	float	clicked / sent w procentach.
submit_rate	float	submitted / sent w procentach.
train_rate	float	trained / sent w procentach.
reply_rate	float	replied / sent w procentach.

Każdy wpis groups[]: name (string), id (integer), total_contacts (integer), sent, opened, clicked, submitted, trained (integers) oraz open_rate, click_rate, submit_rate, train_rate (floats).

{
  "campaign_id": 42,
  "name": "Q2 Invoice Lure",
  "funnel": {
    "sent": 120,
    "opened": 84,
    "clicked": 37,
    "submitted": 12,
    "trained": 9,
    "replied": 3,
    "open_rate": 70.0,
    "click_rate": 30.8,
    "submit_rate": 10.0,
    "train_rate": 7.5,
    "reply_rate": 2.5
  },
  "groups": [
    {
      "name": "Finance",
      "id": 3,
      "total_contacts": 60,
      "sent": 60,
      "opened": 45,
      "clicked": 22,
      "submitted": 8,
      "trained": 6,
      "open_rate": 75.0,
      "click_rate": 36.7,
      "submit_rate": 13.3,
      "train_rate": 10.0
    }
  ],
  "departments": [
    {
      "name": "Accounting",
      "total_contacts": 40,
      "sent": 40,
      "opened": 30,
      "clicked": 15,
      "submitted": 5,
      "trained": 4,
      "open_rate": 75.0,
      "click_rate": 37.5,
      "submit_rate": 12.5,
      "train_rate": 10.0
    }
  ]
}

Kody statusu

Kod	Kiedy
200	Statystyki zwrócone.
404	Kampania nie została znaleziona na kontach użytkownika.

GET /campaigns/:id/recipients

Zwraca stronicowaną, filtrowalną listę odbiorców kampanii wraz z ich etapem dostarczenia, statusem szkolenia i flagą odpowiedzi dla pojedynczego kontaktu. Odbiorcy są uporządkowani według nazwiska kontaktu, a następnie imienia. Uwierzytelnianie: Bearer; rola: dowolna rola.

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator kampanii (camp_… lub liczba całkowita).
page	query	integer	nie	Numer strony liczony od 1; wartości poniżej 1 są przycinane do 1. Domyślnie 1. Rozmiar strony jest ustalony na 25.
stage	query	string	nie	Filtruj według etapu lejka: sent, opened, clicked, submitted lub trained. all (lub pominięcie) zwraca wszystkich. Filtry są kumulatywne względem etapu (np. opened obejmuje tych, którzy później kliknęli/przesłali/zostali przeszkoleni).
replied	query	boolean	nie	Gdy prawdziwe (true/1), ogranicza do kontaktów, które odpowiedziały na wiadomość.
group_id	query	integer	nie	Ogranicza do kontaktów w tej grupie (musi należeć do konta kampanii).
department	query	string	nie	Ogranicza do kontaktów, których department dokładnie odpowiada tej wartości.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  "https://platform.phishspot.com/api/v1/campaigns/42/recipients?stage=clicked&page=1"

Odpowiedź 200 OK — stronicowani odbiorcy.

Pole	Typ	Opis
campaign_id	integer	Identyfikator kampanii.
page	integer	Bieżący numer strony.
per_page	integer	Rozmiar strony (zawsze 25).
total	integer	Łączna liczba odbiorców pasujących do filtrów (na wszystkich stronach).
recipients	array	Wiersze odbiorców (zobacz podpola).

Każdy wpis recipients[]:

Pole	Typ	Opis
id	integer	Identyfikator kontaktu.
contact_id	integer	Identyfikator kontaktu (ta sama wartość co id).
email	string	Adres e-mail kontaktu.
full_name	string	Pełna nazwa kontaktu.
status	string	Stan dostarczenia: pending, sent, delivered, bounced, opened, clicked, submitted lub educated.
stage	string	Ta sama wartość co status (alias).
training_status	string	not_started, in_progress lub completed.
replied	boolean	Czy kontakt odpowiedział na wiadomość phishingową.

{
  "campaign_id": 42,
  "page": 1,
  "per_page": 25,
  "total": 37,
  "recipients": [
    {
      "id": 901,
      "contact_id": 901,
      "email": "jane.doe@victimco.com",
      "full_name": "Jane Doe",
      "status": "clicked",
      "stage": "clicked",
      "training_status": "in_progress",
      "replied": false
    }
  ]
}

Kody statusu

Kod	Kiedy
200	Odbiorcy zwróceni.
404	Kampania nie została znaleziona na kontach użytkownika lub wyszukiwanie group_id/department odwołuje się do rekordu spoza konta kampanii.

GET /campaigns/:id/replies

Zwraca stronicowaną listę przychodzących odpowiedzi, które odbiorcy odesłali na wiadomość phishingową, od najnowszych. Użyj go, aby uwidocznić zaangażowane cele i przejrzeć treść odpowiedzi. Uwierzytelnianie: Bearer; rola: dowolna rola.

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator kampanii (camp_… lub liczba całkowita).
page	query	integer	nie	Numer strony liczony od 1; przycinany do minimum 1. Domyślnie 1. Rozmiar strony jest ustalony na 25.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  "https://platform.phishspot.com/api/v1/campaigns/42/replies?page=1"

Odpowiedź 200 OK — stronicowane odpowiedzi.

Pole	Typ	Opis
campaign_id	integer	Identyfikator kampanii.
page	integer	Bieżący numer strony.
per_page	integer	Rozmiar strony (zawsze 25).
total	integer	Łączna liczba odpowiedzi dla kampanii.
replies	array	Wiersze odpowiedzi (zobacz podpola).

Każdy wpis replies[]:

Pole	Typ	Opis
id	integer	Identyfikator odpowiedzi.
from_email	string	Adres e-mail nadawcy (odbiorcy).
received_at	string	Znacznik czasu ISO8601 momentu otrzymania odpowiedzi.
subject	string	Temat odpowiedzi.
excerpt	string	Tekstowy fragment treści odpowiedzi (skrócony).
attachments_count	integer	Liczba załączników w odpowiedzi.

{
  "campaign_id": 42,
  "page": 1,
  "per_page": 25,
  "total": 3,
  "replies": [
    {
      "id": 5501,
      "from_email": "jane.doe@victimco.com",
      "received_at": "2026-05-02T11:24:00Z",
      "subject": "Re: Your April invoice is ready",
      "excerpt": "Is this really from accounting? I don't recognize…",
      "attachments_count": 0
    }
  ]
}

Kody statusu

Kod	Kiedy
200	Odpowiedzi zwrócone.
404	Kampania nie została znaleziona na kontach użytkownika.

GET /campaigns/:id/timeline

Zwraca chronologiczną oś czasu zdarzeń dla pojedynczego kontaktu w ramach kampanii (sent → opened → clicked → submitted → szkolenie itd.). Użyj go, aby zbadać pełną historię interakcji jednej ofiary. Uwierzytelnianie: Bearer; rola: dowolna rola.

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator kampanii (camp_… lub liczba całkowita).
contact_id	query	integer	tak	Identyfikator kontaktu, którego oś czasu należy zwrócić. Musi należeć do konta kampanii.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  "https://platform.phishspot.com/api/v1/campaigns/42/timeline?contact_id=901"

Odpowiedź 200 OK — lista zdarzeń kontaktu, uporządkowana od najstarszych.

Pole	Typ	Opis
campaign_id	integer	Identyfikator kampanii.
contact_id	integer	Identyfikator kontaktu.
events	array	Zdarzenia dla tego kontaktu (zobacz podpola).

Każdy wpis events[]:

Pole	Typ	Opis
genre	string	Typ zdarzenia: sent, delivered, bounced, opened, clicked, submitted_data, started_training, completed_training, failed_quiz, passed_quiz lub replied.
created_at	string	Znacznik czasu ISO8601 zdarzenia.
metadata	object | null	Dowolne metadane zdarzenia (np. user agent, IP, szczegóły quizu), w zapisanej postaci.

{
  "campaign_id": 42,
  "contact_id": 901,
  "events": [
    { "genre": "sent", "created_at": "2026-05-01T09:05:00Z", "metadata": {} },
    { "genre": "opened", "created_at": "2026-05-01T09:41:00Z", "metadata": { "ua": "Mozilla/5.0" } },
    { "genre": "clicked", "created_at": "2026-05-01T09:42:00Z", "metadata": { "ip": "203.0.113.7" } }
  ]
}

Kody statusu

Kod	Kiedy
200	Oś czasu zwrócona.
404	Kampania nie została znaleziona na kontach użytkownika lub contact_id nie odwołuje się do kontaktu na koncie kampanii (brakujący/nieprawidłowy contact_id powoduje błąd nieznalezienia).

27.5 Szablony phishingowe

Biblioteka szablonów phishingowych to katalog gotowych scenariuszy phishingowych (e-mail + strona docelowa + akcja po kliknięciu), które konto może wdrożyć w rzeczywistej kampanii. Szablony występują w dwóch wariantach: kuratorowane (dostarczane przez platformę, współdzielone z każdym kontem, tylko do odczytu) oraz niestandardowe (utworzone przez konto, widoczne wyłącznie dla tego konta). Szablony są zorganizowane w drzewo kategorii (do trzech poziomów zagnieżdżenia). Wdrożenie szablonu tworzy nową roboczą kampanię wstępnie wypełnioną treścią szablonu — nigdy nie wysyła żadnego e-maila.

GET /accounts/:account_id/phishing_templates

Zwraca listę szablonów widocznych dla konta, stronicowaną po 12 na stronę. Użyj parametru tab, aby przełączać się między współdzieloną biblioteką kuratorowaną a własnymi szablonami niestandardowymi konta, oraz category/search, aby zawęzić wyniki. Zwraca tylko metadane (bez bloków HTML) — wywołaj punkt końcowy show, aby uzyskać pełną treść. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita). Musi być kontem, do którego należy użytkownik tokenu.
tab	query	string	nie	Która biblioteka ma zostać wyświetlona. custom zwraca własne szablony tego konta; każda inna wartość (lub jej pominięcie) zwraca współdzieloną bibliotekę curated. Domyślnie: curated.
category	query	string lub tablica	nie	Jeden lub więcej identyfikatorów kategorii (identyfikatory z prefiksem tcat_… lub liczby całkowite) do filtrowania. Dopasowuje szablony przypisane do danej kategorii lub dowolnego z jej potomków. Wiele wartości przekaż jako powtórzone parametry category[]. Nierozpoznane identyfikatory są ignorowane.
search	query	string	nie	Dopasowanie podciągu (bez rozróżniania wielkości liter) względem name i description szablonu.
page	query	integer	nie	Numer strony liczony od 1. Wartości poniżej 1 są zaokrąglane do 1. Domyślnie: 1. Rozmiar strony jest ustalony na 12.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  "https://platform.phishspot.com/api/v1/accounts/11/phishing_templates?tab=curated&category=tcat_abc123&search=invoice&page=1"

Odpowiedź 200 OK — koperta stronicowania plus tablica templates z metadanymi szablonów.

Pole	Typ	Opis
tab	string	Rozwiązana zakładka: "curated" lub "custom".
page	integer	Bieżący numer strony.
per_page	integer	Rozmiar strony (zawsze 12).
total	integer	Łączna liczba szablonów pasujących do filtrów (na wszystkich stronach).
templates	array	Tablica obiektów szablonów (zobacz pola poniżej).
templates[].id	integer	Surowy numeryczny identyfikator szablonu.
templates[].name	string	Nazwa szablonu.
templates[].description	string | null	Opis w dowolnej formie tekstowej.
templates[].curated	boolean	true dla szablonów dostarczanych przez platformę, false dla należących do konta.
templates[].draft	boolean	true, jeśli szablon jest nieopublikowaną wersją roboczą (brak wymaganej treści). Wersji roboczych nie można wdrażać.
templates[].email_subject	string | null	Temat phishingowej wiadomości e-mail.
templates[].landing_page_enabled	boolean	Czy szablon zawiera hostowaną stronę docelową.
templates[].created_at	string (ISO 8601)	Znacznik czasu utworzenia.
templates[].updated_at	string (ISO 8601)	Znacznik czasu ostatniej aktualizacji.
templates[].template_id	string	Identyfikator z prefiksem (tmpl_…). Użyj go w ścieżkach show/deploy.
templates[].categories	array	Kategorie, do których przypisany jest ten szablon.
templates[].categories[].id	integer	Surowy numeryczny identyfikator kategorii.
templates[].categories[].category_id	string	Identyfikator kategorii z prefiksem (tcat_…).
templates[].categories[].name	string	Zlokalizowana nazwa kategorii (bieżąca lokalizacja żądania, z odwołaniem do angielskiego).

{
  "tab": "curated",
  "page": 1,
  "per_page": 12,
  "total": 37,
  "templates": [
    {
      "id": 84,
      "name": "Unpaid Invoice Reminder",
      "description": "Spoofed accounts-payable invoice with a credential-harvesting login page.",
      "curated": true,
      "draft": false,
      "email_subject": "Action required: invoice #44021 is overdue",
      "landing_page_enabled": true,
      "created_at": "2026-01-14T09:12:00.000Z",
      "updated_at": "2026-03-02T16:40:11.000Z",
      "template_id": "tmpl_8x2k9q",
      "categories": [
        { "id": 5, "category_id": "tcat_abc123", "name": "Finance" }
      ]
    }
  ]
}

Kody statusu

Kod	Kiedy
200	Szablony wyświetlone (tablica może być pusta).
404	account_id nie jest kontem, do którego należy użytkownik tokenu. Treść: {"error":"Account not found"}.

GET /accounts/:account_id/phishing_template_categories

Zwraca pełne drzewo kategorii (korzenie z zagnieżdżonymi elementami podrzędnymi, do trzech poziomów) na potrzeby interfejsu filtrowania biblioteki szablonów. Przydatne do zbudowania selektora kategorii przed wywołaniem listy szablonów z parametrem category=. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita). Musi być kontem, do którego należy użytkownik tokenu.

(Kategorie są globalne, a nie ograniczone do konta — account_id jedynie kontroluje dostęp. Brak innych parametrów.)

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/accounts/11/phishing_template_categories

Odpowiedź 200 OK — tablica categories kategorii głównych, z których każda rekurencyjnie osadza swoje elementy podrzędne.

Pole	Typ	Opis
categories	array	Kategorie główne, uporządkowane według position.
categories[].id	integer	Surowy numeryczny identyfikator kategorii.
categories[].category_id	string	Identyfikator kategorii z prefiksem (tcat_…).
categories[].name	string	Zlokalizowana nazwa kategorii (lokalizacja żądania, z odwołaniem do angielskiego).
categories[].slug	string	Slug bezpieczny dla adresów URL (unikalny, wyprowadzony z angielskiej nazwy).
categories[].depth	integer	Głębokość drzewa: 0 dla korzeni, 1 dla elementów podrzędnych, 2 dla wnuków.
categories[].is_leaf	boolean	true, gdy kategoria nie ma elementów podrzędnych.
categories[].children	array	Zagnieżdżone kategorie podrzędne o tym samym kształcie (pusta tablica dla liści).

{
  "categories": [
    {
      "id": 1,
      "category_id": "tcat_root01",
      "name": "Finance",
      "slug": "finance",
      "depth": 0,
      "is_leaf": false,
      "children": [
        {
          "id": 5,
          "category_id": "tcat_abc123",
          "name": "Invoices",
          "slug": "invoices",
          "depth": 1,
          "is_leaf": true,
          "children": []
        }
      ]
    }
  ]
}

Kody statusu

Kod	Kiedy
200	Zwrócono drzewo kategorii (może być pustą tablicą).
404	account_id nie jest kontem, do którego należy użytkownik tokenu. Treść: {"error":"Account not found"}.

GET /phishing_templates/:id

Zwraca pojedynczy szablon z jego pełną treścią — treścią wiadomości e-mail, kodem HTML/CSS strony docelowej oraz konfiguracją akcji po kliknięciu (akcji końcowej). Użyj tego, aby wyrenderować podgląd lub sprawdzić, co wdrożenie skopiuje do kampanii. Ta ścieżka jest płytka (bez account_id w ścieżce); użytkownik tokenu musi mieć możliwość zobaczenia szablonu (własne szablony niestandardowe oraz wszystkie kuratorowane). Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator szablonu (tmpl_… lub liczba całkowita).

Brak parametrów poza tokenem bearer.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/phishing_templates/tmpl_8x2k9q

Odpowiedź 200 OK — pełny obiekt szablonu.

Pole	Typ	Opis
id	integer	Surowy numeryczny identyfikator szablonu.
name	string	Nazwa szablonu.
description	string | null	Opis w dowolnej formie tekstowej.
curated	boolean	true dla szablonów dostarczanych przez platformę, false dla należących do konta.
draft	boolean	true, jeśli nieopublikowany. Wersji roboczych nie można wdrażać.
email_subject	string | null	Temat phishingowej wiadomości e-mail (może zawierać merge tagi).
email_content	string | null	Pełna treść HTML phishingowej wiadomości e-mail.
landing_html	string | null	Kod HTML strony docelowej.
landing_css	string | null	Kod CSS strony docelowej.
landing_page_enabled	boolean	Czy dołączona jest hostowana strona docelowa.
end_action_type	string	Co dzieje się po przesłaniu strony docelowej przez ofiarę. Jedna z wartości nothing, redirect_to_course, message_page, redirect_to_url.
end_action_url	string | null	Docelowy adres URL, gdy end_action_type ma wartość redirect_to_url (musi być http/https).
end_action_html	string | null	Kod HTML wyświetlany, gdy end_action_type ma wartość message_page (np. strona uświadamiająca).
created_at	string (ISO 8601)	Znacznik czasu utworzenia.
updated_at	string (ISO 8601)	Znacznik czasu ostatniej aktualizacji.
template_id	string	Identyfikator z prefiksem (tmpl_…).
course_id	integer | null	Identyfikator powiązanego kursu e-learningowego (używany, gdy end_action_type ma wartość redirect_to_course).
publishable	boolean	true, gdy obecne są wszystkie wymagane pola (nazwa, temat, treść e-maila, HTML strony docelowej).
categories	array	Przypisane kategorie: każda z id (liczba całkowita), category_id (tcat_…) oraz name.

{
  "id": 84,
  "name": "Unpaid Invoice Reminder",
  "description": "Spoofed accounts-payable invoice with a credential-harvesting login page.",
  "curated": true,
  "draft": false,
  "email_subject": "Action required: invoice #44021 is overdue",
  "email_content": "<html><body><p>Dear {{first_name}}, your invoice is overdue…</p></body></html>",
  "landing_html": "<form action=\"#\">…</form>",
  "landing_css": "body { font-family: sans-serif; }",
  "landing_page_enabled": true,
  "end_action_type": "message_page",
  "end_action_url": null,
  "end_action_html": "<h1>You've been phished by a simulation.</h1>",
  "created_at": "2026-01-14T09:12:00.000Z",
  "updated_at": "2026-03-02T16:40:11.000Z",
  "template_id": "tmpl_8x2k9q",
  "course_id": null,
  "publishable": true,
  "categories": [
    { "id": 5, "category_id": "tcat_abc123", "name": "Finance" }
  ]
}

Kody statusu

Kod	Kiedy
200	Zwrócono szablon.
403	Szablon nie jest widoczny dla użytkownika tokenu (niestandardowy szablon innego konta). Treść: {"error":"You are not authorized to perform this action"}.
404	Żaden szablon nie pasuje do id. Treść: {"error":"Resource not found"}.

POST /phishing_templates/:id/deploy

Tworzy nową roboczą kampanię na koncie docelowym, wstępnie wypełnioną treścią szablonu (temat/treść e-maila, HTML/CSS strony docelowej, akcja końcowa, kurs). Ta ścieżka jest płytka, więc wdrażające konto jest przekazywane w treści żądania jako account_id. Przy quick_launch=true dodatkowo dodaje wszystkich odbiorców z kontaktów konta jako odbiorców i przenosi kampanię do kroku przeglądu. Ten punkt końcowy nigdy nie wysyła żadnego e-maila — kampanię uruchamia człowiek z interfejsu PhishSpot. Wersji roboczych nie można wdrażać. Uwierzytelnianie: Bearer; rola: dowolny członek konta docelowego.

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator szablonu do wdrożenia (tmpl_… lub liczba całkowita). Nie może być szablonem roboczym.
account_id	body	string	tak	Konto, na którym ma zostać utworzona kampania (acct_… lub liczba całkowita). Musi być kontem, do którego należy użytkownik tokenu.
quick_launch	body	boolean	nie	Gdy wartość jest prawdziwa (true, "1" itp.), masowo dodaje każdy kontakt konta jako odbiorcę i oznacza kroki kreatora 1–5 jako ukończone, dzięki czemu kampania trafia do kroku przeglądu. Wymaga aktywnej domeny wysyłkowej i co najmniej jednego kontaktu. Domyślnie: false.

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "account_id": "acct_4f8a2c", "quick_launch": true }' \
  https://platform.phishspot.com/api/v1/phishing_templates/tmpl_8x2k9q/deploy

Odpowiedź 201 Created — nowo utworzona kampania (taki sam kształt jak punkt końcowy show kampanii). Świeżo wdrożona kampania jest w stanie draft, więc blok statistics jest pomijany (pojawia się dopiero, gdy kampania jest w toku, wstrzymana lub zakończona).

Pole	Typ	Opis
id	integer	Surowy numeryczny identyfikator kampanii.
account_id	integer	Identyfikator konta będącego właścicielem.
name	string	Automatycznie wygenerowana nazwa: "<Template name> - YYYY-MM-DD HH:MM:SS" (z numerycznym sufiksem w razie kolizji).
state	string	Stan cyklu życia — draft natychmiast po wdrożeniu. Jedna z wartości draft, in_progress, paused, cancelled, done, scheduled.
delivery_mode	string | null	immediate, scheduled lub staggered (nie ustawiane przy wdrożeniu).
delivery_schedule	object | null	Konfiguracja harmonogramu dostarczania (nie ustawiana przy wdrożeniu).
created_at	string (ISO 8601)	Znacznik czasu utworzenia.
updated_at	string (ISO 8601)	Znacznik czasu ostatniej aktualizacji.
email_subject	string | null	Skopiowane z szablonu.
email_content	string | null	Skopiowane z szablonu.
landing_html	string | null	Skopiowane z szablonu.
domain	string | null	Nazwa domeny platformy wysyłkowej/docelowej (automatycznie wybrana spośród dostępnych domen konta, może być null).
course_id	integer | null	Identyfikator powiązanego kursu (kurs szablonu lub domyślny kurs konta).
groups	array	Grupy kontaktów w kampanii — puste tuż po wdrożeniu. Każda: id, name.
can_start	boolean	Czy kampania może przejść do uruchomienia.
can_pause	boolean	Czy kampania może zostać wstrzymana.
can_cancel	boolean	Czy kampania może zostać anulowana.

{
  "id": 512,
  "account_id": 11,
  "name": "Unpaid Invoice Reminder - 2026-06-02 14:30:07",
  "state": "draft",
  "delivery_mode": null,
  "delivery_schedule": null,
  "created_at": "2026-06-02T14:30:07.000Z",
  "updated_at": "2026-06-02T14:30:07.000Z",
  "email_subject": "Action required: invoice #44021 is overdue",
  "email_content": "<html><body><p>Dear {{first_name}}…</p></body></html>",
  "landing_html": "<form action=\"#\">…</form>",
  "domain": "officelogin.in",
  "course_id": null,
  "groups": [],
  "can_start": false,
  "can_pause": false,
  "can_cancel": false
}

Kody statusu

Kod	Kiedy
201	Kampania utworzona z szablonu.
403	Szablon jest wersją roboczą (wersji roboczych nie można wdrażać) lub nie jest widoczny dla użytkownika tokenu. Treść: {"error":"You are not authorized to perform this action"}.
404	Żaden szablon nie pasuje do id, lub account_id w treści żądania nie jest kontem, do którego należy użytkownik tokenu. Treść: {"error":"Resource not found"} (szablon) / {"error":"Account not found"} (konto).
422	quick_launch=true, ale konto nie ma aktywnej domeny wysyłkowej ("Quick launch needs an active sending domain for this account.") lub nie ma kontaktów ("Quick launch needs at least one contact in the account."). Treść: {"error":"<message>"}.

27.6 Odbiorcy i grupy

Odbiorcy to pracownicy, których obierasz za cel symulacji phishingowych; grupy to nazwane zbiory służące do zawężania kampanii. Oba zasoby są ograniczone do konta: akcje kolekcji są zagnieżdżone pod /accounts/:account_id/…, natomiast odczyty/zapisy na pojedynczym rekordzie korzystają z płytkich ścieżek /contacts/:id i /groups/:id. Członkostwo w koncie jest wymagane dla każdego punktu końcowego — wszystkie sprawdzenia uprawnień przechodzą dla dowolnego członka konta (zarówno odczyt, jak i zapis), więc nie ma tu rozróżnienia admin/edytor. Jedynym ograniczeniem zapisu jest to, że grupa biorąca udział w aktywnej kampanii (in_progress lub paused) jest zablokowana i nie można jej zaktualizować, usunąć ani zmienić jej członkostwa.

GET /accounts/:account_id/contacts

Zwraca listę wszystkich odbiorców w koncie, posortowanych według nazwiska, a następnie imienia, z grupami każdego odbiorcy umieszczonymi w treści. Użyj go do stronicowania lub synchronizacji listy. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita).

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/accounts/11/contacts

Odpowiedź 200 OK — tablica JSON obiektów odbiorców (zobacz pola odbiorcy poniżej).

Pole	Typ	Opis
id	integer	Klucz główny odbiorcy.
account_id	integer	Identyfikator konta będącego właścicielem.
first_name	string	Imię.
last_name	string|null	Nazwisko.
email	string	Adres e-mail (unikalny w obrębie konta).
telephone	string|null	Numer telefonu.
created_at	string	Znacznik czasu ISO 8601.
updated_at	string	Znacznik czasu ISO 8601.
full_name	string	Wygodne: "first_name last_name" po przycięciu.
groups	array	Grupy, do których należy ten odbiorca; każda { id, name }.
groups[].id	integer	Identyfikator grupy.
groups[].name	string	Nazwa grupy (znormalizowana, snake_case dla grup ręcznych).

[
  {
    "id": 501,
    "account_id": 11,
    "first_name": "Ada",
    "last_name": "Kowalska",
    "email": "ada.kowalska@example.com",
    "telephone": "+48 600 123 456",
    "created_at": "2026-05-01T09:30:00.000Z",
    "updated_at": "2026-05-12T14:02:11.000Z",
    "full_name": "Ada Kowalska",
    "groups": [
      { "id": 90, "name": "finance" }
    ]
  }
]

Kody statusu

Kod	Kiedy
200	Zwrócono odbiorców (być może pustą tablicę).
404	account_id nie jest kontem, do którego należy użytkownik tokenu.

POST /accounts/:account_id/contacts

Tworzy pojedynczego odbiorcę w koncie. Do masowego ładowania użyj zamiast tego punktu końcowego importu. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Parametry treści żądania są opakowane w obiekt contact.

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita).
first_name	body	string	tak	Imię (maks. 255). Wymagane przez model.
email	body	string	tak	Adres e-mail. Musi odpowiadać standardowemu formatowi e-mail i być unikalny w obrębie konta (bez rozróżniania wielkości liter). Maks. 255.
last_name	body	string	nie	Nazwisko (maks. 255).
telephone	body	string	nie	Numer telefonu (maks. 50). Musi odpowiadać formatom typu +CC (NNN) NNN-NNNN; dozwolona wartość pusta.
group_ids	body	array	nie	Tablica identyfikatorów grup, do których odbiorca ma zostać dołączony przy tworzeniu.

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "contact": { "first_name": "Ada", "last_name": "Kowalska", "email": "ada.kowalska@example.com", "telephone": "+48 600 123 456", "group_ids": [90] } }' \
  https://platform.phishspot.com/api/v1/accounts/11/contacts

Odpowiedź 201 Created — utworzony odbiorca, z tymi samymi polami co punkt końcowy listy powyżej.

{
  "id": 501,
  "account_id": 11,
  "first_name": "Ada",
  "last_name": "Kowalska",
  "email": "ada.kowalska@example.com",
  "telephone": "+48 600 123 456",
  "created_at": "2026-05-01T09:30:00.000Z",
  "updated_at": "2026-05-01T09:30:00.000Z",
  "full_name": "Ada Kowalska",
  "groups": [
    { "id": 90, "name": "finance" }
  ]
}

Kody statusu

Kod	Kiedy
201	Odbiorca utworzony.
400	W treści brakuje klucza najwyższego poziomu contact.
404	account_id nie jest kontem, do którego należy użytkownik tokenu.
422	Walidacja nie powiodła się (np. brak first_name, brakujący/nieprawidłowy email lub zduplikowany adres e-mail w obrębie konta). Treść to { "errors": { … } }.

POST /accounts/:account_id/contacts/import

Masowo importuje odbiorców do konta z pliku CSV. Istniejący odbiorcy (dopasowani po adresie e-mail) są aktualizowani niepustymi wartościami; nowi są tworzeni; grupy nazwane w danych są tworzone, a powiązania są ustanawiane. Podaj albo surowy tekst CSV w csv, albo tablicę JSON w contacts — tablica jest konwertowana na CSV po stronie serwera przy użyciu kanonicznej kolejności nagłówków. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Kanoniczna kolejność nagłówków CSV to: first_name, last_name, email, telephone, groups, department, title, location. W kolumnie groups wiele grup rozdziela się znakiem | (pionowa kreska). Przy korzystaniu z formy JSON contacts pole groups każdego wiersza może być tablicą (np. ["finance","exec"]), która jest automatycznie łączona znakiem |.

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita).
csv	body	string	warunkowo	Surowy tekst CSV z kanonicznym wierszem nagłówka. Wymagane, jeśli pominięto contacts. Ma pierwszeństwo, jeśli podano oba.
contacts	body	array	warunkowo	Tablica obiektów wierszy z kluczami zgodnymi z kanonicznymi nagłówkami. Wymagane, jeśli pominięto csv. Pole groups każdego wiersza może być ciągiem znaków lub tablicą nazw grup.

Notatka

Musisz podać dokładnie jedno z csv lub contacts. Jeśli oba są puste/nieobecne, żądanie kończy się niepowodzeniem z kodem 422.

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "contacts": [
        { "first_name": "Ada", "last_name": "Kowalska", "email": "ada.kowalska@example.com", "telephone": "+48600123456", "groups": ["finance"], "department": "Finance", "title": "Analyst", "location": "Warsaw" },
        { "first_name": "Jan", "email": "jan.nowak@example.com", "groups": ["finance", "exec"] }
      ] }' \
  https://platform.phishspot.com/api/v1/accounts/11/contacts/import

Odpowiedź 200 OK — podsumowanie sposobu przetworzenia wierszy.

Pole	Typ	Opis
created	integer	Liczba wstawionych nowych odbiorców.
updated	integer	Liczba istniejących odbiorców (dopasowanych po adresie e-mail) zaktualizowanych nowymi niepustymi wartościami.
failed	integer	Liczba wierszy odrzuconych jako nieprawidłowe. (Do konta dołączany jest możliwy do pobrania raport CSV z nieudanymi wierszami.)

{
  "created": 1,
  "updated": 1,
  "failed": 0
}

Kody statusu

Kod	Kiedy
200	Import wykonany; zwraca podsumowanie {created, updated, failed}.
404	account_id nie jest kontem, do którego należy użytkownik tokenu.
422	Nie podano ani csv, ani contacts. Treść to { "error": "Provide either csv or contacts." }.

GET /contacts/:id

Pobiera pojedynczego odbiorcę po identyfikatorze, ograniczonego do kont użytkownika tokenu. Użyj go do odczytania jednego odbiorcy bez wyświetlania całego konta. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator odbiorcy (cont_… lub liczba całkowita).

Brak parametrów poza tokenem bearer i identyfikatorem ścieżki.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/contacts/cont_abc123

Odpowiedź 200 OK — odbiorca, z tymi samymi polami co punkt końcowy listy.

{
  "id": 501,
  "account_id": 11,
  "first_name": "Ada",
  "last_name": "Kowalska",
  "email": "ada.kowalska@example.com",
  "telephone": "+48 600 123 456",
  "created_at": "2026-05-01T09:30:00.000Z",
  "updated_at": "2026-05-12T14:02:11.000Z",
  "full_name": "Ada Kowalska",
  "groups": [
    { "id": 90, "name": "finance" }
  ]
}

Kody statusu

Kod	Kiedy
200	Odbiorca znaleziony.
404	Brak odbiorcy o tym identyfikatorze w jakimkolwiek koncie, do którego należy użytkownik tokenu.

PATCH /contacts/:id

Aktualizuje pojedynczego odbiorcę. Wyślij tylko te pola, które chcesz zmienić, opakowane w obiekt contact. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Parametry treści żądania są opakowane w obiekt contact.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator odbiorcy (cont_… lub liczba całkowita).
first_name	body	string	nie	Imię (maks. 255). Nie można wyczyścić do wartości pustej — jest wymagane.
last_name	body	string	nie	Nazwisko (maks. 255).
email	body	string	nie	Adres e-mail. Musi pozostać prawidłowy i unikalny w obrębie konta (bez rozróżniania wielkości liter). Maks. 255.
telephone	body	string	nie	Numer telefonu (maks. 50, walidowany formatowo; dozwolona wartość pusta).
group_ids	body	array	nie	Zastępuje członkostwo grupowe odbiorcy dokładnie tym zestawem identyfikatorów grup.

Żądanie

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "contact": { "title": "Senior Analyst", "group_ids": [90, 91] } }' \
  https://platform.phishspot.com/api/v1/contacts/cont_abc123

Notatka

title, department i location istnieją w modelu, ale nie znajdują się wśród dozwolonych parametrów API, więc są ignorowane przy tworzeniu/aktualizacji za pośrednictwem tego punktu końcowego — ustaw je zamiast tego przez import CSV. Powyższy przykład pokazuje group_ids, które jest honorowane; title zostałoby po cichu odrzucone.

Odpowiedź 200 OK — zaktualizowany odbiorca, z tymi samymi polami co punkt końcowy listy.

{
  "id": 501,
  "account_id": 11,
  "first_name": "Ada",
  "last_name": "Kowalska",
  "email": "ada.kowalska@example.com",
  "telephone": "+48 600 123 456",
  "created_at": "2026-05-01T09:30:00.000Z",
  "updated_at": "2026-05-20T08:15:00.000Z",
  "full_name": "Ada Kowalska",
  "groups": [
    { "id": 90, "name": "finance" },
    { "id": 91, "name": "exec" }
  ]
}

Kody statusu

Kod	Kiedy
200	Odbiorca zaktualizowany.
400	W treści brakuje klucza najwyższego poziomu contact.
404	Brak odbiorcy o tym identyfikatorze w jakimkolwiek koncie, do którego należy użytkownik tokenu.
422	Walidacja nie powiodła się (pusty first_name, nieprawidłowy/zduplikowany email, błędny format telephone). Treść to { "errors": { … } }.

DELETE /contacts/:id

Trwale usuwa odbiorcę oraz jego członkostwa w grupach, dostarczalne elementy, zdarzenia i wyniki. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator odbiorcy (cont_… lub liczba całkowita).

Brak parametrów poza tokenem bearer i identyfikatorem ścieżki.

Żądanie

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/contacts/cont_abc123

Odpowiedź 204 No Content — pusta treść.

Kody statusu

Kod	Kiedy
204	Odbiorca usunięty.
404	Brak odbiorcy o tym identyfikatorze w jakimkolwiek koncie, do którego należy użytkownik tokenu.

GET /accounts/:account_id/groups

Zwraca listę wszystkich grup w koncie, posortowanych według nazwy, z odbiorcami każdej grupy umieszczonymi w treści. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita).

Odpowiedź 200 OK — tablica JSON obiektów grup (zobacz pola grupy poniżej).

Pole	Typ	Opis
id	integer	Klucz główny grupy.
account_id	integer	Identyfikator konta będącego właścicielem.
name	string	Nazwa grupy. Dla grup ręcznych jest ona normalizowana do snake_case (spacje → podkreślenia, znaki niealfanumeryczne usuwane, małe litery).
contact_count	integer	Zbuforowana liczba odbiorców w grupie.
created_at	string	Znacznik czasu ISO 8601.
updated_at	string	Znacznik czasu ISO 8601.
contacts	array	Członkowie grupy.
contacts[].id	integer	Identyfikator odbiorcy.
contacts[].email	string	Adres e-mail odbiorcy.
contacts[].first_name	string	Imię odbiorcy.
contacts[].last_name	string|null	Nazwisko odbiorcy.
contacts[].full_name	string	"first_name last_name" po przycięciu.

[
  {
    "id": 90,
    "account_id": 11,
    "name": "finance",
    "contact_count": 2,
    "created_at": "2026-04-10T11:00:00.000Z",
    "updated_at": "2026-05-20T08:15:00.000Z",
    "contacts": [
      { "id": 501, "email": "ada.kowalska@example.com", "first_name": "Ada", "last_name": "Kowalska", "full_name": "Ada Kowalska" }
    ]
  }
]

Kody statusu

Kod	Kiedy
200	Zwrócono grupy (być może pustą tablicę).
404	account_id nie jest kontem, do którego należy użytkownik tokenu.

POST /accounts/:account_id/groups

Tworzy grupę w koncie. Nazwy grup ręcznych są normalizowane do snake_case po stronie serwera. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Parametry treści żądania są opakowane w obiekt group.

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita).
name	body	string	tak	Nazwa grupy (maks. 255). Normalizowana do snake_case; musi być unikalna w obrębie konta (bez rozróżniania wielkości liter, porównywana po normalizacji).
description	body	string	nie	Dowolny opis tekstowy. Dozwolony przez kontroler (model nie ma kolumny description, więc jest akceptowany, ale nieutrwalany/niezwracany).
contact_ids	body	array	nie	Tablica identyfikatorów odbiorców do dodania jako członkowie przy tworzeniu.

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "group": { "name": "Finance Team", "contact_ids": [501, 502] } }' \
  https://platform.phishspot.com/api/v1/accounts/11/groups

Odpowiedź 201 Created — utworzona grupa, z tymi samymi polami co punkt końcowy listy powyżej. Zwróć uwagę, że "Finance Team" jest zapisywane i zwracane jako "finance_team".

{
  "id": 90,
  "account_id": 11,
  "name": "finance_team",
  "contact_count": 2,
  "created_at": "2026-04-10T11:00:00.000Z",
  "updated_at": "2026-04-10T11:00:00.000Z",
  "contacts": [
    { "id": 501, "email": "ada.kowalska@example.com", "first_name": "Ada", "last_name": "Kowalska", "full_name": "Ada Kowalska" },
    { "id": 502, "email": "jan.nowak@example.com", "first_name": "Jan", "last_name": "Nowak", "full_name": "Jan Nowak" }
  ]
}

Kody statusu

Kod	Kiedy
201	Grupa utworzona.
400	W treści brakuje klucza najwyższego poziomu group.
404	account_id nie jest kontem, do którego należy użytkownik tokenu.
422	Walidacja nie powiodła się (pusta name lub nazwa, która po normalizacji jest duplikatem w obrębie konta). Treść to { "errors": { … } }.

GET /groups/:id

Pobiera pojedynczą grupę po identyfikatorze, ograniczoną do kont użytkownika tokenu. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator grupy (grp_… lub liczba całkowita).

Brak parametrów poza tokenem bearer i identyfikatorem ścieżki.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/groups/grp_xyz789

Odpowiedź 200 OK — grupa, z tymi samymi polami co punkt końcowy listy.

{
  "id": 90,
  "account_id": 11,
  "name": "finance",
  "contact_count": 1,
  "created_at": "2026-04-10T11:00:00.000Z",
  "updated_at": "2026-05-20T08:15:00.000Z",
  "contacts": [
    { "id": 501, "email": "ada.kowalska@example.com", "first_name": "Ada", "last_name": "Kowalska", "full_name": "Ada Kowalska" }
  ]
}

Kody statusu

Kod	Kiedy
200	Grupa znaleziona.
404	Brak grupy o tym identyfikatorze w jakimkolwiek koncie, do którego należy użytkownik tokenu.

PATCH /groups/:id

Aktualizuje nazwę grupy (i opcjonalnie zastępuje jej członkostwo). Zablokowane, jeśli grupa jest zablokowana przez aktywną kampanię. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Parametry treści żądania są opakowane w obiekt group.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator grupy (grp_… lub liczba całkowita).
name	body	string	nie	Nowa nazwa grupy (maks. 255). Normalizowana do snake_case; musi pozostać unikalna w obrębie konta.
description	body	string	nie	Akceptowana, ale nieutrwalana (brak kolumny w modelu).
contact_ids	body	array	nie	Zastępuje członkostwo grupy dokładnie tym zestawem identyfikatorów odbiorców.

Żądanie

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "group": { "name": "Finance and Ops", "contact_ids": [501, 503] } }' \
  https://platform.phishspot.com/api/v1/groups/grp_xyz789

Odpowiedź 200 OK — zaktualizowana grupa, z tymi samymi polami co punkt końcowy listy.

{
  "id": 90,
  "account_id": 11,
  "name": "finance_and_ops",
  "contact_count": 2,
  "created_at": "2026-04-10T11:00:00.000Z",
  "updated_at": "2026-05-21T10:00:00.000Z",
  "contacts": [
    { "id": 501, "email": "ada.kowalska@example.com", "first_name": "Ada", "last_name": "Kowalska", "full_name": "Ada Kowalska" },
    { "id": 503, "email": "ola.wisniewska@example.com", "first_name": "Ola", "last_name": "Wisniewska", "full_name": "Ola Wisniewska" }
  ]
}

Kody statusu

Kod	Kiedy
200	Grupa zaktualizowana.
400	W treści brakuje klucza najwyższego poziomu group.
403	Grupa jest zablokowana (używana w kampanii in_progress/paused), więc nie można jej zmodyfikować.
404	Brak grupy o tym identyfikatorze w jakimkolwiek koncie, do którego należy użytkownik tokenu.
422	Walidacja nie powiodła się (pusta name lub nazwa, która po normalizacji jest duplikatem). Treść to { "errors": { … } }.

DELETE /groups/:id

Trwale usuwa grupę oraz jej powiązania odbiorca-grupa / kampania-grupa (sami odbiorcy nie są usuwani). Zablokowane, jeśli grupa jest zablokowana przez aktywną kampanię. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator grupy (grp_… lub liczba całkowita).

Brak parametrów poza tokenem bearer i identyfikatorem ścieżki.

Żądanie

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/groups/grp_xyz789

Odpowiedź 204 No Content — pusta treść.

Kody statusu

Kod	Kiedy
204	Grupa usunięta.
403	Grupa jest zablokowana (używana w kampanii in_progress/paused), więc nie można jej usunąć.
404	Brak grupy o tym identyfikatorze w jakimkolwiek koncie, do którego należy użytkownik tokenu.

POST /groups/:id/add_contacts

Dodaje jednego lub więcej odbiorców do grupy. Identyfikatory odbiorców są rozwiązywane względem własnego konta grupy — identyfikatory należące do innego konta lub nieistniejące są po cichu odrzucane. Odbiorcy już znajdujący się w grupie są pomijani. Zablokowane, jeśli grupa jest zablokowana. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator grupy (grp_… lub liczba całkowita).
contact_ids	body	array	tak	Identyfikatory odbiorców (cont_… lub liczby całkowite) do dodania. Identyfikatory spoza konta grupy lub nieistniejące są ignorowane.

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "contact_ids": [501, "cont_def456"] }' \
  https://platform.phishspot.com/api/v1/groups/grp_xyz789/add_contacts

Odpowiedź 200 OK — zaktualizowana grupa (po przeładowaniu), z tymi samymi polami co punkt końcowy listy. Odpowiedź nie zawiera osobnej liczby dodanych elementów; porównaj contact_count / contacts przed i po.

{
  "id": 90,
  "account_id": 11,
  "name": "finance",
  "contact_count": 2,
  "created_at": "2026-04-10T11:00:00.000Z",
  "updated_at": "2026-05-22T09:00:00.000Z",
  "contacts": [
    { "id": 501, "email": "ada.kowalska@example.com", "first_name": "Ada", "last_name": "Kowalska", "full_name": "Ada Kowalska" },
    { "id": 540, "email": "marek.zielinski@example.com", "first_name": "Marek", "last_name": "Zielinski", "full_name": "Marek Zielinski" }
  ]
}

Kody statusu

Kod	Kiedy
200	Zwraca zaktualizowaną grupę (nawet jeśli każdy podany identyfikator został odrzucony/już był obecny — po prostu nic się nie zmieni).
403	Grupa jest zablokowana (używana w kampanii in_progress/paused).
404	Brak grupy o tym identyfikatorze w jakimkolwiek koncie, do którego należy użytkownik tokenu.

DELETE /groups/:id/remove_contacts

Usuwa jednego lub więcej odbiorców z grupy. Identyfikatory odbiorców są rozwiązywane względem konta grupy; identyfikatory spoza grupy (lub spoza konta) są ignorowane. Zablokowane, jeśli grupa jest zablokowana. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator grupy (grp_… lub liczba całkowita).
contact_ids	body	array	tak	Identyfikatory odbiorców (cont_… lub liczby całkowite) do usunięcia z grupy.

Żądanie

curl -X DELETE -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "contact_ids": [540] }' \
  https://platform.phishspot.com/api/v1/groups/grp_xyz789/remove_contacts

Odpowiedź 200 OK — zaktualizowana grupa (po przeładowaniu), z tymi samymi polami co punkt końcowy listy.

{
  "id": 90,
  "account_id": 11,
  "name": "finance",
  "contact_count": 1,
  "created_at": "2026-04-10T11:00:00.000Z",
  "updated_at": "2026-05-22T09:10:00.000Z",
  "contacts": [
    { "id": 501, "email": "ada.kowalska@example.com", "first_name": "Ada", "last_name": "Kowalska", "full_name": "Ada Kowalska" }
  ]
}

Kody statusu

Kod	Kiedy
200	Zwraca zaktualizowaną grupę (identyfikatory spoza grupy są po prostu ignorowane).
403	Grupa jest zablokowana (używana w kampanii in_progress/paused).
404	Brak grupy o tym identyfikatorze w jakimkolwiek koncie, do którego należy użytkownik tokenu.

27.7 Dostarczenia, zdarzenia i wyniki

Te trzy zasoby rejestrują telemetrię kampanii per odbiorca. Dostarczenie (deliverable) to powiązanie kampanii z kontaktem (jeden wiersz na odbiorcę) i śledzi jego pozycję w lejku zaangażowania poprzez state. Zdarzenie (event) to w zasadzie niezmienny wpis na osi czasu (sent, opened, clicked, …) identyfikowany przez genre. Wynik (result) przechowuje odpowiedź/punktację kontaktu dla pojedynczego bloku block szkolenia e-learning.

Wszystkie punkty końcowe w tej sekcji autoryzują za pomocą polityki Pundit danego zasobu, która zezwala każdemu członkowi zespołu (każdej roli) na odczyt, tworzenie, aktualizację i usuwanie. Nie ma bramki admin/edytor. Listowanie i tworzenie są zagnieżdżone w koncie (/accounts/:account_id/…); show/update/destroy są płytkie (/deliverables/:id itd.) i ograniczone do kont, do których należy użytkownik tokena — żądanie rekordu spoza tych kont zwraca 404, nigdy danych innego najemcy.

GET /api/v1/accounts/:account_id/deliverables

Listuje wszystkie dostarczenia dla konta, od najnowszych, opcjonalnie ograniczone do jednej kampanii. Użyj go, aby pobrać listę odbiorców i stan lejka kampanii. Uwierzytelnianie: Bearer; rola: odczyt (każda rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita).
campaign_id	query	string	nie	Ograniczenie do jednej kampanii (camp_… lub liczba całkowita). Po pominięciu zwracane są wszystkie dostarczenia dla konta.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  "https://platform.phishspot.com/api/v1/accounts/11/deliverables?campaign_id=42"

Odpowiedź 200 OK — tablica JSON obiektów dostarczenia.

Pole	Typ	Opis
id	integer	Identyfikator dostarczenia.
campaign_id	integer	Kampania będąca właścicielem.
contact_id	integer	Kontakt będący celem.
state	string	Stan lejka (zobacz enum poniżej).
user_agent	string | null	User-agent przechwycony przy otwarciu/kliknięciu, jeśli istnieje.
ip_address	string | null	Adres IP przechwycony przy otwarciu/kliknięciu, jeśli istnieje.
created_at	string	Znacznik czasu ISO 8601.
updated_at	string	Znacznik czasu ISO 8601.
campaign	object | null	Obecne, gdy kampania się załaduje: { id, name, account_id }.
contact	object | null	Obecne, gdy kontakt się załaduje: { id, email, first_name, last_name, full_name }.
events	array	Obecne tylko wtedy, gdy kontakt ma zdarzenia w tej kampanii; każdy element to { id, genre, created_at }.

state przyjmuje jedną z wartości: pending (jeszcze niewysłane), sent, delivered, bounced, opened, clicked, submitted (dane wprowadzone na stronie docelowej), educated (ukończono szkolenie).

[
  {
    "id": 5012,
    "campaign_id": 42,
    "contact_id": 880,
    "state": "clicked",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "ip_address": "203.0.113.7",
    "created_at": "2026-05-30T09:12:44.000Z",
    "updated_at": "2026-05-30T10:01:08.000Z",
    "campaign": { "id": 42, "name": "Q2 Invoice Lure", "account_id": 11 },
    "contact": { "id": 880, "email": "jan.kowalski@acme.test", "first_name": "Jan", "last_name": "Kowalski", "full_name": "Jan Kowalski" },
    "events": [
      { "id": 9001, "genre": "sent", "created_at": "2026-05-30T09:12:44.000Z" },
      { "id": 9044, "genre": "opened", "created_at": "2026-05-30T09:58:21.000Z" },
      { "id": 9051, "genre": "clicked", "created_at": "2026-05-30T10:01:08.000Z" }
    ]
  }
]

Kody statusu

Kod	Kiedy
200	Zwrócono dostarczenia.
403	Użytkownik tokena nie jest uprawniony do wyświetlenia konta (account.show? odmówiono).
404	account_id nie należy do użytkownika tokena.

POST /api/v1/accounts/:account_id/deliverables

Tworzy dostarczenie, łącząc kontakt z kampanią. account_id jest pobierane automatycznie z kampanii (podany segment ścieżki account_id wybiera kontekst konta). Uwierzytelnianie: Bearer; rola: odczyt (każda rola).

Parametry

Wszystkie parametry treści żądania są opakowane w obiekt deliverable.

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita).
deliverable.campaign_id	body	integer	tak	Kampania, do której ma zostać dołączone. Walidowane presence.
deliverable.contact_id	body	integer	tak	Kontakt będący celem. Walidowane presence.
deliverable.state	body	string	nie	Stan lejka; domyślnie pending. Jedna z wartości enuma state. Walidowane presence.
deliverable.name	body	string	nie	Akceptowane przez strong params, ale niezapisywane (brak kolumny name).

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "deliverable": { "campaign_id": 42, "contact_id": 880, "state": "pending" } }' \
  https://platform.phishspot.com/api/v1/accounts/11/deliverables

Odpowiedź 201 Created — utworzone dostarczenie (taki sam kształt jak obiekt show/index powyżej).

{
  "id": 5099,
  "campaign_id": 42,
  "contact_id": 880,
  "state": "pending",
  "user_agent": null,
  "ip_address": null,
  "created_at": "2026-06-02T08:00:00.000Z",
  "updated_at": "2026-06-02T08:00:00.000Z",
  "campaign": { "id": 42, "name": "Q2 Invoice Lure", "account_id": 11 },
  "contact": { "id": 880, "email": "jan.kowalski@acme.test", "first_name": "Jan", "last_name": "Kowalski", "full_name": "Jan Kowalski" }
}

Kody statusu

Kod	Kiedy
201	Utworzono dostarczenie.
404	account_id nie należy do użytkownika tokena.
422	Walidacja nie powiodła się (brak campaign_id/contact_id/state lub nieprawidłowa wartość state). Treść: { "errors": { … } }.

GET /api/v1/deliverables/:id

Pobiera pojedyncze dostarczenie wraz z jego kampanią, kontaktem i osią czasu zdarzeń. Uwierzytelnianie: Bearer; rola: odczyt (każda rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator dostarczenia (delv_… lub liczba całkowita).

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/deliverables/5012

Odpowiedź 200 OK — pojedynczy obiekt dostarczenia (te same pola co element listy powyżej).

{
  "id": 5012,
  "campaign_id": 42,
  "contact_id": 880,
  "state": "clicked",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
  "ip_address": "203.0.113.7",
  "created_at": "2026-05-30T09:12:44.000Z",
  "updated_at": "2026-05-30T10:01:08.000Z",
  "campaign": { "id": 42, "name": "Q2 Invoice Lure", "account_id": 11 },
  "contact": { "id": 880, "email": "jan.kowalski@acme.test", "first_name": "Jan", "last_name": "Kowalski", "full_name": "Jan Kowalski" },
  "events": [
    { "id": 9001, "genre": "sent", "created_at": "2026-05-30T09:12:44.000Z" }
  ]
}

Kody statusu

Kod	Kiedy
200	Zwrócono dostarczenie.
404	Brak dostarczenia o tym identyfikatorze w koncie, do którego należy użytkownik tokena.

PATCH /api/v1/deliverables/:id

Aktualizuje dostarczenie — zazwyczaj w celu przesunięcia jego state lub ponownego powiązania kampanii/kontaktu. Uwierzytelnianie: Bearer; rola: odczyt (każda rola).

Parametry

Parametry treści żądania są opakowane w obiekt deliverable; wyślij tylko te pola, które chcesz zmienić.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator dostarczenia (delv_… lub liczba całkowita).
deliverable.state	body	string	nie	Nowy stan lejka (jedna z wartości enuma state).
deliverable.campaign_id	body	integer	nie	Zmiana przypisania kampanii (presence nadal wymuszane — nie można wyczyścić).
deliverable.contact_id	body	integer	nie	Zmiana przypisania kontaktu (presence nadal wymuszane).
deliverable.name	body	string	nie	Akceptowane, ale niezapisywane (brak kolumny).

Żądanie

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "deliverable": { "state": "submitted" } }' \
  https://platform.phishspot.com/api/v1/deliverables/5012

Odpowiedź 200 OK — zaktualizowany obiekt dostarczenia (taki sam kształt jak show).

Kody statusu

Kod	Kiedy
200	Zaktualizowano dostarczenie.
404	Brak dostarczenia o tym identyfikatorze w koncie, do którego należy użytkownik tokena.
422	Walidacja nie powiodła się (np. nieprawidłowy state lub wyczyszczony campaign_id/contact_id). Treść: { "errors": { … } }.

DELETE /api/v1/deliverables/:id

Trwale usuwa dostarczenie (oraz zależne campaign_replies). Uwierzytelnianie: Bearer; rola: odczyt (każda rola).

Brak parametrów poza tokenem bearer i identyfikatorem w ścieżce.

Żądanie

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/deliverables/5012

Odpowiedź 204 No Content — pusta treść po sukcesie.

Kody statusu

Kod	Kiedy
204	Usunięto dostarczenie.
404	Brak dostarczenia o tym identyfikatorze w koncie, do którego należy użytkownik tokena.

GET /api/v1/accounts/:account_id/events

Listuje zdarzenia konta od najnowszych, z opcjonalnym filtrowaniem według kampanii, kontaktu i rodzaju (genre). Użyj go, aby zrekonstruować oś czasu zaangażowania. Uwierzytelnianie: Bearer; rola: odczyt (każda rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita).
campaign_id	query	string	nie	Ograniczenie do jednej kampanii (camp_… lub liczba całkowita).
contact_id	query	string	nie	Ograniczenie do jednego kontaktu (cont_… lub liczba całkowita).
genre	query	string	nie	Ograniczenie do jednego rodzaju (zobacz enum poniżej).

genre przyjmuje jedną z wartości: sent, delivered, bounced, opened, clicked, submitted_data (dane przesłane na stronie docelowej), started_training, completed_training, failed_quiz, passed_quiz, replied (odbiorca odpowiedział na e-mail phishingowy).

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  "https://platform.phishspot.com/api/v1/accounts/11/events?campaign_id=42&genre=clicked"

Odpowiedź 200 OK — tablica JSON obiektów zdarzeń.

Pole	Typ	Opis
id	integer	Identyfikator zdarzenia.
account_id	integer	Konto będące właścicielem.
campaign_id	integer	Kampania, do której należy zdarzenie.
contact_id	integer	Kontakt, do którego należy zdarzenie.
genre	string	Rodzaj zdarzenia (zobacz enum powyżej).
metadata	object	Dowolny JSON (np. ip_address, user_agent, przesłane pola, dane quizu). Domyślnie {}.
created_at	string	Znacznik czasu ISO 8601.
updated_at	string	Znacznik czasu ISO 8601.
genre_display_name	string	Czytelna nazwa rodzaju (np. "Submitted data"); obecne tylko gdy genre jest ustawione.
ip_address	string	Wygodna kopia metadata.ip_address; obecne tylko gdy ustawione.
user_agent	string	Wygodna kopia metadata.user_agent; obecne tylko gdy ustawione.

[
  {
    "id": 9051,
    "account_id": 11,
    "campaign_id": 42,
    "contact_id": 880,
    "genre": "clicked",
    "metadata": { "ip_address": "203.0.113.7", "user_agent": "Mozilla/5.0" },
    "created_at": "2026-05-30T10:01:08.000Z",
    "updated_at": "2026-05-30T10:01:08.000Z",
    "genre_display_name": "Clicked",
    "ip_address": "203.0.113.7",
    "user_agent": "Mozilla/5.0"
  }
]

Kody statusu

Kod	Kiedy
200	Zwrócono zdarzenia.
404	account_id nie należy do użytkownika tokena.

POST /api/v1/accounts/:account_id/events

Rejestruje nowe zdarzenie. account zdarzenia jest ustawiane na podstawie konta ze ścieżki, a przy zapisie model nadpisuje je tak, aby pasowało do konta kampanii. Uwierzytelnianie: Bearer; rola: odczyt (każda rola).

Parametry

Parametry treści żądania są opakowane w obiekt event.

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita).
event.campaign_id	body	integer	tak	Kampania dla tego zdarzenia. Walidowane presence.
event.contact_id	body	integer	tak	Kontakt dla tego zdarzenia. Walidowane presence.
event.genre	body	string	nie	Rodzaj zdarzenia; domyślnie sent. Jedna z wartości enuma genre. Walidowane presence.
event.metadata	body	object	nie	Dowolny hash JSON (dozwolony jako metadata: {}). Domyślnie {}.
event.name	body	string	nie	Akceptowane przez strong params, ale niezapisywane (brak kolumny name).

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "event": { "campaign_id": 42, "contact_id": 880, "genre": "opened", "metadata": { "ip_address": "203.0.113.7", "user_agent": "Mozilla/5.0" } } }' \
  https://platform.phishspot.com/api/v1/accounts/11/events

Odpowiedź 201 Created — utworzony obiekt zdarzenia (taki sam kształt jak element listy powyżej).

{
  "id": 9044,
  "account_id": 11,
  "campaign_id": 42,
  "contact_id": 880,
  "genre": "opened",
  "metadata": { "ip_address": "203.0.113.7", "user_agent": "Mozilla/5.0" },
  "created_at": "2026-05-30T09:58:21.000Z",
  "updated_at": "2026-05-30T09:58:21.000Z",
  "genre_display_name": "Opened",
  "ip_address": "203.0.113.7",
  "user_agent": "Mozilla/5.0"
}

Kody statusu

Kod	Kiedy
201	Utworzono zdarzenie.
404	account_id nie należy do użytkownika tokena.
422	Walidacja nie powiodła się (brak campaign_id/contact_id/genre lub nieprawidłowy genre). Treść: { "errors": { … } }.

GET /api/v1/events/:id

Pobiera pojedyncze zdarzenie. Uwierzytelnianie: Bearer; rola: odczyt (każda rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator zdarzenia (evt_… lub liczba całkowita).

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/events/9044

Odpowiedź 200 OK — pojedynczy obiekt zdarzenia (te same pola co element listy powyżej).

{
  "id": 9044,
  "account_id": 11,
  "campaign_id": 42,
  "contact_id": 880,
  "genre": "opened",
  "metadata": { "ip_address": "203.0.113.7" },
  "created_at": "2026-05-30T09:58:21.000Z",
  "updated_at": "2026-05-30T09:58:21.000Z",
  "genre_display_name": "Opened",
  "ip_address": "203.0.113.7"
}

Kody statusu

Kod	Kiedy
200	Zwrócono zdarzenie.
404	Brak zdarzenia o tym identyfikatorze w koncie, do którego należy użytkownik tokena. Treść: { "error": "Event not found" }.

PATCH /api/v1/events/:id

Aktualizuje rodzaj (genre) lub metadane zdarzenia. Uwierzytelnianie: Bearer; rola: odczyt (każda rola).

Parametry

Parametry treści żądania są opakowane w obiekt event; wyślij tylko te pola, które chcesz zmienić.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator zdarzenia (evt_… lub liczba całkowita).
event.genre	body	string	nie	Nowy rodzaj (jedna z wartości enuma genre; presence nadal wymuszane).
event.metadata	body	object	nie	Zastępczy hash metadanych.
event.campaign_id	body	integer	nie	Zmiana przypisania kampanii (presence wymuszane).
event.contact_id	body	integer	nie	Zmiana przypisania kontaktu (presence wymuszane).
event.name	body	string	nie	Akceptowane, ale niezapisywane.

Żądanie

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "event": { "metadata": { "note": "manual correction" } } }' \
  https://platform.phishspot.com/api/v1/events/9044

Odpowiedź 200 OK — zaktualizowany obiekt zdarzenia (taki sam kształt jak show).

Kody statusu

Kod	Kiedy
200	Zaktualizowano zdarzenie.
404	Brak zdarzenia o tym identyfikatorze w koncie, do którego należy użytkownik tokena. Treść: { "error": "Event not found" }.
422	Walidacja nie powiodła się (np. nieprawidłowy/pusty genre). Treść: { "errors": { … } }.

DELETE /api/v1/events/:id

Trwale usuwa zdarzenie. Uwierzytelnianie: Bearer; rola: odczyt (każda rola).

Brak parametrów poza tokenem bearer i identyfikatorem w ścieżce.

Żądanie

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/events/9044

Odpowiedź 204 No Content — pusta treść po sukcesie.

Kody statusu

Kod	Kiedy
204	Usunięto zdarzenie.
404	Brak zdarzenia o tym identyfikatorze w koncie, do którego należy użytkownik tokena. Treść: { "error": "Event not found" }.

GET /api/v1/accounts/:account_id/results

Listuje wyniki e-learningu konta od najnowszych. Ten punkt końcowy nie ma filtrów query. Uwierzytelnianie: Bearer; rola: odczyt (każda rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita).

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/accounts/11/results

Odpowiedź 200 OK — tablica JSON obiektów wyników.

Pole	Typ	Opis
id	integer	Identyfikator wyniku.
block_id	integer	Blok kursu, którego dotyczy ten wynik.
contact_id	integer	Kontakt, który wytworzył wynik.
account_id	integer	Konto będące właścicielem.
metadata	object	Dowolny JSON (np. answer, correct, score, time_spent, completed). Domyślnie {}.
created_at	string	Znacznik czasu ISO 8601.
updated_at	string	Znacznik czasu ISO 8601.
block	object | null	Obecne, gdy blok się załaduje: { id, name }.
contact	object | null	Obecne, gdy kontakt się załaduje: { id, email, first_name, last_name, full_name }.

[
  {
    "id": 7100,
    "block_id": 320,
    "contact_id": 880,
    "account_id": 11,
    "metadata": { "answer": "B", "correct": true, "score": 100, "completed": true },
    "created_at": "2026-05-31T14:20:00.000Z",
    "updated_at": "2026-05-31T14:20:00.000Z",
    "block": { "id": 320, "name": "Spot the Lookalike Domain" },
    "contact": { "id": 880, "email": "jan.kowalski@acme.test", "first_name": "Jan", "last_name": "Kowalski", "full_name": "Jan Kowalski" }
  }
]

Kody statusu

Kod	Kiedy
200	Zwrócono wyniki.
403	Użytkownik tokena nie jest uprawniony do wyświetlenia konta (account.show? odmówiono).
404	account_id nie należy do użytkownika tokena.

POST /api/v1/accounts/:account_id/results

Rejestruje wynik kontaktu dla bloku kursu. account jest pobierane automatycznie z bloku. Uwierzytelnianie: Bearer; rola: odczyt (każda rola).

Parametry

Parametry treści żądania są opakowane w obiekt result.

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita).
result.block_id	body	integer	tak	Blok kursu, którego dotyczy ten wynik. Walidowane presence.
result.contact_id	body	integer	tak	Kontakt wytwarzający wynik. Walidowane presence.
result.metadata	body	object	nie	Hash JSON z danymi odpowiedzi/punktacji/ukończenia. Domyślnie {}. Dozwolone jako parametr skalarny (:metadata), więc wyślij go jako wartość obiektu JSON.
result.name	body	string	nie	Akceptowane przez strong params, ale niezapisywane (brak kolumny name).
result.state	body	string	nie	Akceptowane przez strong params, ale niezapisywane (Result nie ma kolumny/enuma state).

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "result": { "block_id": 320, "contact_id": 880, "metadata": { "answer": "B", "correct": true, "score": 100, "completed": true } } }' \
  https://platform.phishspot.com/api/v1/accounts/11/results

Odpowiedź 201 Created — utworzony obiekt wyniku (taki sam kształt jak element listy powyżej).

{
  "id": 7150,
  "block_id": 320,
  "contact_id": 880,
  "account_id": 11,
  "metadata": { "answer": "B", "correct": true, "score": 100, "completed": true },
  "created_at": "2026-06-02T08:30:00.000Z",
  "updated_at": "2026-06-02T08:30:00.000Z",
  "block": { "id": 320, "name": "Spot the Lookalike Domain" },
  "contact": { "id": 880, "email": "jan.kowalski@acme.test", "first_name": "Jan", "last_name": "Kowalski", "full_name": "Jan Kowalski" }
}

Kody statusu

Kod	Kiedy
201	Utworzono wynik.
404	account_id nie należy do użytkownika tokena.
422	Walidacja nie powiodła się (brak block_id/contact_id). Treść: { "errors": { … } }.

GET /api/v1/results/:id

Pobiera pojedynczy wynik. Uwierzytelnianie: Bearer; rola: odczyt (każda rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator wyniku (res_… lub liczba całkowita).

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/results/7100

Odpowiedź 200 OK — pojedynczy obiekt wyniku (te same pola co element listy powyżej).

{
  "id": 7100,
  "block_id": 320,
  "contact_id": 880,
  "account_id": 11,
  "metadata": { "answer": "B", "correct": true, "score": 100 },
  "created_at": "2026-05-31T14:20:00.000Z",
  "updated_at": "2026-05-31T14:20:00.000Z",
  "block": { "id": 320, "name": "Spot the Lookalike Domain" },
  "contact": { "id": 880, "email": "jan.kowalski@acme.test", "first_name": "Jan", "last_name": "Kowalski", "full_name": "Jan Kowalski" }
}

Kody statusu

Kod	Kiedy
200	Zwrócono wynik.
404	Brak wyniku o tym identyfikatorze w koncie, do którego należy użytkownik tokena.

PATCH /api/v1/results/:id

Aktualizuje wynik, zazwyczaj w celu skorygowania jego metadanych (odpowiedź, punktacja, ukończenie). Uwierzytelnianie: Bearer; rola: odczyt (każda rola).

Parametry

Parametry treści żądania są opakowane w obiekt result; wyślij tylko te pola, które chcesz zmienić.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator wyniku (res_… lub liczba całkowita).
result.metadata	body	object	nie	Zastępczy hash metadanych.
result.block_id	body	integer	nie	Zmiana przypisania bloku (presence wymuszane).
result.contact_id	body	integer	nie	Zmiana przypisania kontaktu (presence wymuszane).
result.name	body	string	nie	Akceptowane, ale niezapisywane.
result.state	body	string	nie	Akceptowane, ale niezapisywane.

Żądanie

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "result": { "metadata": { "answer": "C", "correct": false, "score": 0 } } }' \
  https://platform.phishspot.com/api/v1/results/7100

Odpowiedź 200 OK — zaktualizowany obiekt wyniku (taki sam kształt jak show).

Kody statusu

Kod	Kiedy
200	Zaktualizowano wynik.
404	Brak wyniku o tym identyfikatorze w koncie, do którego należy użytkownik tokena.
422	Walidacja nie powiodła się (np. wyczyszczony block_id/contact_id). Treść: { "errors": { … } }.

DELETE /api/v1/results/:id

Trwale usuwa wynik. Uwierzytelnianie: Bearer; rola: odczyt (każda rola).

Brak parametrów poza tokenem bearer i identyfikatorem w ścieżce.

Żądanie

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/results/7100

Odpowiedź 204 No Content — pusta treść po sukcesie.

Kody statusu

Kod	Kiedy
204	Usunięto wynik.
404	Brak wyniku o tym identyfikatorze w koncie, do którego należy użytkownik tokena.

27.8 Trendy konta

Zagregowana analityka podatności na phishing dla konta: jeden punkt danych na każdą dostarczoną kampanię w zakresie dat, plus podsumowanie zbiorcze. Oparte na Campaigns::TrendService, który liczy tylko kampanie w stanie in_progress lub done (scope delivered) utworzone w wybranym zakresie.

GET /accounts/:account_id/trends

Zwraca metryki podatności dla dostarczonych kampanii konta, uporządkowane od najstarszych, wraz z podsumowaniem (liczba kampanii, średni współczynnik kliknięć, kierunek trendu oraz grupa odbiorców o najwyższej klikalności). Użyj go, aby zasilić panel trendów lub śledzić, czy pracownicy z czasem coraz lepiej (czy gorzej) rozpoznają phishing. Uwierzytelnianie: Bearer; rola: read (dowolna rola — każdy członek konta).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita). Musi to być konto, do którego należy użytkownik tokena.
start_date	query	string	nie	Początek niestandardowego zakresu, YYYY-MM-DD. Parsowany do początku tego dnia. Jeśli jest obecny (z end_date lub bez), niestandardowy zakres ma pierwszeństwo przed range. Gdy pominięty, ale podano end_date, domyślnie przyjmuje datę sprzed 1 roku.
end_date	query	string	nie	Koniec niestandardowego zakresu, YYYY-MM-DD. Parsowany do końca tego dnia. Gdy pominięty, ale podano start_date, domyślnie przyjmuje teraz.
range	query	string	nie	Predefiniowany zakres, używany tylko wtedy, gdy nie podano ani start_date, ani end_date. Jedna z wartości 30d, 90d, 6m, all. Każda inna/brakująca wartość (w tym domyślna) daje ostatni 1 rok. all obejmuje okres od epoki uniksowej do teraz.

Notatka

start_date/end_date tworzą niestandardowy zakres, który nadpisuje range. Daty są włączne (początek = początek dnia, koniec = koniec dnia). Nieprawidłowe daty zwracają 422 (patrz niżej).

Żądanie

curl -X GET -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "https://platform.phishspot.com/api/v1/accounts/11/trends?start_date=2026-01-01&end_date=2026-06-01"

Odpowiedź 200 OK — obiekt z tablicą campaigns (jeden wpis na każdą dostarczoną kampanię w zakresie) oraz obiektem summary.

Pole	Typ	Opis
campaigns	array	Dostarczone kampanie w zakresie, uporządkowane rosnąco według created_at. Każdy element to punkt danych (pola poniżej). Pusta tablica, jeśli brak.
campaigns[].id	integer	Identyfikator kampanii (surowa liczba całkowita).
campaigns[].name	string	Nazwa kampanii.
campaigns[].date	string	Data uruchomienia kampanii, YYYY-MM-DD (data ISO 8601). Używa scheduled_at, jeśli ustawiono, w przeciwnym razie created_at.
campaigns[].open_rate	number (float)	Procent odbiorców, którzy otworzyli e-mail (0.0, gdy brak danych).
campaigns[].click_rate	number (float)	Procent odbiorców, którzy kliknęli link (0.0, gdy brak danych).
campaigns[].submit_rate	number (float)	Procent odbiorców, którzy przesłali dane na stronie docelowej (0.0, gdy brak danych).
campaigns[].total_sent	integer	Liczba odbiorców, do których wysłano kampanię.
summary	object	Zestawienie zbiorcze dla powyższych kampanii (pola poniżej).
summary.total_campaigns	integer	Liczba dostarczonych kampanii w zakresie (0, gdy brak).
summary.avg_click_rate	number (float)	Średnia z wartości click_rate poszczególnych kampanii, zaokrąglona do 1 miejsca po przecinku (0.0, gdy brak).
summary.trend_direction	string	Jedna z wartości improving, worsening, stable lub neutral. Porównuje średni współczynnik kliknięć ostatnich do 3 kampanii ze średnią najwcześniejszych do 3; neutral, gdy mniej niż 2 kampanie, stable, gdy zmiana mieści się w zakresie ±1.0 punktu procentowego.
summary.most_vulnerable_group	string | null	Nazwa grupy odbiorców o najwyższym stosunku kliknięć do wysłanych w zakresie; null, gdy brak danych o grupach.

{
  "campaigns": [
    {
      "id": 42,
      "name": "Q1 Invoice Lure",
      "date": "2026-01-14",
      "open_rate": 61.5,
      "click_rate": 23.1,
      "submit_rate": 7.7,
      "total_sent": 130
    },
    {
      "id": 57,
      "name": "Password Expiry Notice",
      "date": "2026-04-02",
      "open_rate": 54.0,
      "click_rate": 12.0,
      "submit_rate": 4.0,
      "total_sent": 150
    }
  ],
  "summary": {
    "total_campaigns": 2,
    "avg_click_rate": 17.6,
    "trend_direction": "improving",
    "most_vulnerable_group": "Finance"
  }
}

Kody statusu

Kod	Kiedy
200	Zwrócono dane trendów (tablica campaigns i summary są obecne nawet wtedy, gdy nie ma pasujących kampanii).
404	account_id nie należy do użytkownika tokena ({"error":"Account not found"}).
422	start_date lub end_date nie jest możliwą do sparsowania datą YYYY-MM-DD ({"error":"Invalid date; use YYYY-MM-DD."}).

27.9 Kursy i bloki

Kursy e-learningowe dostarczane pracownikom, którzy dali się nabrać na symulację phishingu. Kurs to uporządkowany zbiór bloków (tekst, HTML, wideo, quiz itp.). Kursy należą do Twojego konta albo są globalne (wyselekcjonowana, współdzielona biblioteka). Bloki są zagnieżdżone w kursie na potrzeby listowania/tworzenia, ale są adresowalne po własnym płytkim id na potrzeby wyświetlania/aktualizacji/usuwania.

Notatka

Wszystkie punkty końcowe w tej sekcji autoryzują przez politykę dla pojedynczego rekordu, która nadaje odczyt oraz zapis każdej roli na koncie (członek, edytor, admin). Jedyne ograniczenia zapisu to: nie możesz modyfikować kursu/bloku globalnego, który nie należy do Twojego konta (403), oraz nie możesz aktualizować/usuwać kursu lub bloku, który jest zablokowany przez trwającą lub wstrzymaną kampanię.

GET /api/v1/accounts/:account_id/courses

Listuje wszystkie kursy dostępne dla konta — kursy należące do Twojego konta plus wszystkie kursy z global: true — uporządkowane według nazwy, z dołączonym lekkim podsumowaniem bloków. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Id konta (acct_… lub liczba całkowita). Musi być kontem, do którego należy użytkownik tokena.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/accounts/11/courses

Odpowiedź 200 OK — tablica JSON obiektów kursu (zobacz pola kursu poniżej).

Pole	Typ	Opis
id	integer	Id kursu.
account_id	integer	Id konta będącego właścicielem.
name	string	Nazwa kursu.
description	string	Opis kursu.
global	boolean	true dla współdzielonych/wyselekcjonowanych kursów z biblioteki, false dla kursów należących do konta.
created_at	string	Znacznik czasu ISO 8601.
updated_at	string	Znacznik czasu ISO 8601.
blocks	array	Dołączone podsumowania bloków (zobacz pola poniżej). Uporządkowane tak, jak zapisano w asocjacji.
blocks[].id	integer	Id bloku.
blocks[].name	string	Nazwa bloku.
blocks[].order	integer	Pozycja w kursie liczona od zera.
blocks[].genre	string	Rodzaj bloku (zobacz enum przy punktach końcowych bloków).

[
  {
    "id": 7,
    "account_id": 11,
    "name": "Spotting Spoofed Senders",
    "description": "A short course on recognising display-name and domain spoofing.",
    "global": false,
    "created_at": "2026-05-01T09:12:00.000Z",
    "updated_at": "2026-05-14T16:40:11.000Z",
    "blocks": [
      { "id": 31, "name": "Intro", "order": 0, "genre": "html" },
      { "id": 32, "name": "Quick check", "order": 1, "genre": "quiz" }
    ]
  }
]

Kody statusu

Kod	Kiedy
200	Kursy zwrócone.
404	account_id nie jest kontem, do którego należy użytkownik tokena.

POST /api/v1/accounts/:account_id/courses

Tworzy nowy kurs należący do konta. Kurs jest zawsze tworzony pod kontem z ścieżki (nie można ustawić global — nowe kursy są prywatne). Zarówno name, jak i description są wymagane przez model. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola — wszyscy członkowie zespołu mogą tworzyć kursy).

Parametry

Parametry treści żądania są opakowane w obiekt course.

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Id konta (acct_… lub liczba całkowita).
course	body	object	tak	Obiekt opakowujący zawierający pola poniżej.
course.name	body	string	tak	Nazwa kursu. Walidowana pod kątem obecności.
course.description	body	string	tak	Opis kursu. Walidowany pod kątem obecności.

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "course": { "name": "Invoice Fraud 101", "description": "Recognising fake supplier invoices." } }' \
  https://platform.phishspot.com/api/v1/accounts/11/courses

Odpowiedź 201 Created — utworzony kurs, taki sam kształt jak element listy (z pustą tablicą blocks).

Pole	Typ	Opis
id	integer	Id nowego kursu.
account_id	integer	Id konta będącego właścicielem (konto ze ścieżki).
name	string	Nazwa kursu.
description	string	Opis kursu.
global	boolean	Zawsze false dla nowo utworzonych kursów.
created_at	string	Znacznik czasu ISO 8601.
updated_at	string	Znacznik czasu ISO 8601.
blocks	array	Pusta przy tworzeniu.

{
  "id": 19,
  "account_id": 11,
  "name": "Invoice Fraud 101",
  "description": "Recognising fake supplier invoices.",
  "global": false,
  "created_at": "2026-06-02T10:00:00.000Z",
  "updated_at": "2026-06-02T10:00:00.000Z",
  "blocks": []
}

Kody statusu

Kod	Kiedy
201	Kurs utworzony.
404	account_id nie jest kontem, do którego należy użytkownik tokena.
422	Walidacja nie powiodła się — np. name lub description puste. Treść: {"errors": {"name": ["can't be blank"]}}.

GET /api/v1/courses/:id

Pobiera pojedynczy kurs po jego płytkim id. Rozwiązywalne dla kursów należących do Twojego konta lub dowolnego kursu global; kurs należący do innego najemcy zwraca 404. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Id kursu (course_… lub liczba całkowita).

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/courses/7

Odpowiedź 200 OK — jeden obiekt kursu, te same pola co element listy (w tym dołączone podsumowanie blocks).

Pole	Typ	Opis
id	integer	Id kursu.
account_id	integer	Id konta będącego właścicielem.
name	string	Nazwa kursu.
description	string	Opis kursu.
global	boolean	Czy kurs pochodzi ze współdzielonej biblioteki.
created_at	string	Znacznik czasu ISO 8601.
updated_at	string	Znacznik czasu ISO 8601.
blocks	array	Dołączone podsumowania bloków: id, name, order, genre.

{
  "id": 7,
  "account_id": 11,
  "name": "Spotting Spoofed Senders",
  "description": "A short course on recognising display-name and domain spoofing.",
  "global": false,
  "created_at": "2026-05-01T09:12:00.000Z",
  "updated_at": "2026-05-14T16:40:11.000Z",
  "blocks": [
    { "id": 31, "name": "Intro", "order": 0, "genre": "html" },
    { "id": 32, "name": "Quick check", "order": 1, "genre": "quiz" }
  ]
}

Kody statusu

Kod	Kiedy
200	Kurs zwrócony.
404	Brak kursu o tym id należącego do Twojego konta, a kurs nie jest globalny.

PATCH /api/v1/courses/:id

Aktualizuje pola name i/lub description kursu. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola), z zastrzeżeniem kontroli własności globalnej i blokady opisanych poniżej.

Parametry

Parametry treści żądania są opakowane w obiekt course. Dozwolone są tylko name i description.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Id kursu (course_… lub liczba całkowita).
course	body	object	tak	Obiekt opakowujący zawierający pola poniżej.
course.name	body	string	nie	Nowa nazwa. Nie może być pusta, jeśli podana (walidacja obecności).
course.description	body	string	nie	Nowy opis. Nie może być pusty, jeśli podany (walidacja obecności).

Żądanie

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "course": { "description": "Updated for the 2026 supplier-fraud wave." } }' \
  https://platform.phishspot.com/api/v1/courses/7

Odpowiedź 200 OK — zaktualizowany kurs (taki sam kształt jak GET /courses/:id).

{
  "id": 7,
  "account_id": 11,
  "name": "Spotting Spoofed Senders",
  "description": "Updated for the 2026 supplier-fraud wave.",
  "global": false,
  "created_at": "2026-05-01T09:12:00.000Z",
  "updated_at": "2026-06-02T10:05:00.000Z",
  "blocks": [
    { "id": 31, "name": "Intro", "order": 0, "genre": "html" }
  ]
}

Kody statusu

Kod	Kiedy
200	Kurs zaktualizowany.
403	Kurs jest global i nie należy do Twojego konta, albo jest zablokowany przez trwającą/wstrzymaną kampanię.
404	Kurs nieosiągalny dla Twojego konta (nie jest własnością i nie jest globalny).
422	Walidacja nie powiodła się — np. name/description ustawione na puste. Treść: {"errors": {...}}.

DELETE /api/v1/courses/:id

Usuwa kurs i (poprzez dependent: :destroy) wszystkie jego bloki. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola), z zastrzeżeniem kontroli własności globalnej i blokady opisanych poniżej.

Parametry

Brak parametrów poza tokenem bearer i id ze ścieżki.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Id kursu (course_… lub liczba całkowita).

Żądanie

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/courses/19

Odpowiedź 204 No Content — pusta treść po sukcesie.

Kody statusu

Kod	Kiedy
204	Kurs usunięty.
403	Kurs jest global i nie należy do Twojego konta, albo jest zablokowany przez trwającą/wstrzymaną kampanię.
404	Kurs nieosiągalny dla Twojego konta.

GET /api/v1/courses/:course_id/blocks

Listuje bloki kursu, uporządkowane według order (rosnąco), zawężone przez Pundit do bloków dostępnych (własnych lub globalnych) kursów. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
course_id	path	string	tak	Id kursu (course_… lub liczba całkowita). Musi należeć do Twojego konta lub być globalny.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/courses/7/blocks

Odpowiedź 200 OK — tablica JSON pełnych obiektów bloku (pola poniżej).

Pole	Typ	Opis
id	integer	Id bloku.
name	string	Nazwa bloku.
course_id	integer	Id kursu nadrzędnego.
order	integer	Pozycja w kursie liczona od zera.
genre	string	Jeden z: text, html, image, video, quiz, interactive, code, file_download.
metadata	object	Dowolny JSON. Dla bloków quizowych przechowuje ładunek z pytaniem/odpowiedziami.
created_at	string	Znacznik czasu ISO 8601.
updated_at	string	Znacznik czasu ISO 8601.
html_data	string	Wyrenderowany HTML z tekstu sformatowanego. Obecne tylko wtedy, gdy blok ma treść ActionText.
locked	boolean	true, gdy powiązana kampania jest w toku (bloku nie można aktualizować/usuwać).
quiz_question	string	Tylko bloki quizowe. Sparsowany tekst pytania.
quiz_answers	array	Tylko bloki quizowe. Tablica hashy odpowiedzi sparsowanych z metadata.
url	string	Kanoniczny adres URL API tego bloku (/api/v1/blocks/:id).

[
  {
    "id": 31,
    "name": "Intro",
    "course_id": 7,
    "order": 0,
    "genre": "html",
    "metadata": {},
    "created_at": "2026-05-01T09:12:00.000Z",
    "updated_at": "2026-05-01T09:12:00.000Z",
    "html_data": "<div>Welcome to the course.</div>",
    "locked": false,
    "url": "https://platform.phishspot.com/api/v1/blocks/31"
  },
  {
    "id": 32,
    "name": "Quick check",
    "course_id": 7,
    "order": 1,
    "genre": "quiz",
    "metadata": [
      { "question_text": "Which sender is spoofed?" },
      { "answer_text": "no-reply@paypa1.com", "right_answer": "on" },
      { "answer_text": "no-reply@paypal.com" }
    ],
    "created_at": "2026-05-01T09:13:00.000Z",
    "updated_at": "2026-05-01T09:13:00.000Z",
    "locked": false,
    "quiz_question": "Which sender is spoofed?",
    "quiz_answers": [
      { "answer_text": "no-reply@paypa1.com", "right_answer": "on" },
      { "answer_text": "no-reply@paypal.com" }
    ],
    "url": "https://platform.phishspot.com/api/v1/blocks/32"
  }
]

Kody statusu

Kod	Kiedy
200	Bloki zwrócone (pusta tablica, jeśli kurs nie ma żadnych).
404	course_id nieosiągalny dla Twojego konta (nie jest własnością i nie jest globalny).

POST /api/v1/courses/:course_id/blocks

Dodaje blok do kursu. Pole account bloku jest ustawiane automatycznie na podstawie kursu; jeśli order jest pominięte, jest automatycznie przypisywane na koniec kursu. Wymagania dotyczące treści różnią się w zależności od genre (zobacz poniżej). Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola), ale nie możesz dodawać bloków do kursu globalnego, który nie należy do Ciebie (403).

Parametry

Parametry treści żądania są opakowane w obiekt block.

Nazwa	Gdzie	Typ	Wymagane	Opis
course_id	path	string	tak	Id kursu (course_… lub liczba całkowita).
block	body	object	tak	Obiekt opakowujący zawierający pola poniżej.
block.name	body	string	tak	Nazwa bloku. Walidowana pod kątem obecności.
block.genre	body	string	tak	Jeden z text, html, image, video, quiz, interactive, code, file_download. Domyślnie text, jeśli pominięty.
block.body	body	string	warunkowo	Treść w zwykłym tekście/markdownie. Wymagana, chyba że genre to quiz, html, video lub file_download. Dla video/file_download służy jako opcjonalny opis.
block.html_data	body	string	warunkowo	Treść w formacie rich HTML (ActionText). Dla bloków html/text podaj body albo html_data.
block.metadata	body	object/array	warunkowo	Dowolny JSON. Wymagane dla bloków quiz, gdzie niesie pytanie i odpowiedzi (zobacz ograniczenia quizu).
block.order	body	integer	nie	Pozycja w kursie (liczba całkowita ≥ 0). Automatycznie przypisana na koniec, jeśli pominięta.
block.course_id	body	integer	nie	Dozwolone, ale zwykle nadmiarowe wobec course_id ze ścieżki.
block.video_file	body	file	warunkowo	Załącznik wideo. Wymagany dla bloków video. Musi być video/mp4 lub video/webm, ≤ 300 MB, ≤ 1920×1080, ≤ 600 s, kodek wideo h264/vp8/vp9, kodek audio aac/opus. Puste wartości tekstowe są ignorowane.
block.document_file	body	file	warunkowo	Załącznik dokumentu. Wymagany dla bloków file_download. Dowolny format, ≤ 100 MB. Puste wartości tekstowe są ignorowane.

Notatka

Bloki quiz muszą mieć od 2 do 6 odpowiedzi w metadata, a co najmniej jedna odpowiedź musi być oznaczona jako poprawna (odpowiedź jest poprawna, gdy jej wartość right_answer/correct to true, "on", "true", "1" lub "yes"). W przeciwnym razie tworzenie kończy się błędem 422.

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
        "block": {
          "name": "Identify the phish",
          "genre": "quiz",
          "metadata": [
            { "question_text": "Which sender is spoofed?" },
            { "answer_text": "no-reply@paypa1.com", "right_answer": "on" },
            { "answer_text": "no-reply@paypal.com" }
          ]
        }
      }' \
  https://platform.phishspot.com/api/v1/courses/7/blocks

Odpowiedź 201 Created — utworzony blok (taki sam kształt jak element listy).

{
  "id": 33,
  "name": "Identify the phish",
  "course_id": 7,
  "order": 2,
  "genre": "quiz",
  "metadata": [
    { "question_text": "Which sender is spoofed?" },
    { "answer_text": "no-reply@paypa1.com", "right_answer": "on" },
    { "answer_text": "no-reply@paypal.com" }
  ],
  "created_at": "2026-06-02T10:10:00.000Z",
  "updated_at": "2026-06-02T10:10:00.000Z",
  "locked": false,
  "quiz_question": "Which sender is spoofed?",
  "quiz_answers": [
    { "answer_text": "no-reply@paypa1.com", "right_answer": "on" },
    { "answer_text": "no-reply@paypal.com" }
  ],
  "url": "https://platform.phishspot.com/api/v1/blocks/33"
}

Kody statusu

Kod	Kiedy
201	Blok utworzony.
403	Kurs nadrzędny jest global i nie należy do Twojego konta.
404	course_id nieosiągalny dla Twojego konta.
422	Walidacja nie powiodła się — brak name/genre, brak wymaganej treści dla danego genre (body, html_data, metadata, video_file lub document_file), zbyt mało/zbyt wiele odpowiedzi quizowych, brak poprawnej odpowiedzi quizowej lub niedozwolony plik wideo/dokumentu. Treść: {"errors": {...}}.

GET /api/v1/blocks/:id

Pobiera pojedynczy blok po jego płytkim id, zawężony do bloków kursów, do których Twoje konto ma dostęp (własnych lub globalnych). Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Id bloku (blk_… lub liczba całkowita).

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/blocks/32

Odpowiedź 200 OK — jeden obiekt bloku (pełne pola jak na liście bloków).

Pole	Typ	Opis
id	integer	Id bloku.
name	string	Nazwa bloku.
course_id	integer	Id kursu nadrzędnego.
order	integer	Pozycja liczona od zera.
genre	string	Rodzaj bloku (zobacz enum powyżej).
metadata	object/array	Dowolny JSON; ładunek quizu dla bloków quizowych.
created_at	string	Znacznik czasu ISO 8601.
updated_at	string	Znacznik czasu ISO 8601.
html_data	string	Wyrenderowany tekst sformatowany. Obecne tylko, gdy ustawione.
locked	boolean	true, gdy powiązana kampania jest w toku.
quiz_question	string	Tylko bloki quizowe.
quiz_answers	array	Tylko bloki quizowe.
url	string	Kanoniczny adres URL API tego bloku.

{
  "id": 32,
  "name": "Quick check",
  "course_id": 7,
  "order": 1,
  "genre": "quiz",
  "metadata": [
    { "question_text": "Which sender is spoofed?" },
    { "answer_text": "no-reply@paypa1.com", "right_answer": "on" },
    { "answer_text": "no-reply@paypal.com" }
  ],
  "created_at": "2026-05-01T09:13:00.000Z",
  "updated_at": "2026-05-01T09:13:00.000Z",
  "locked": false,
  "quiz_question": "Which sender is spoofed?",
  "quiz_answers": [
    { "answer_text": "no-reply@paypa1.com", "right_answer": "on" },
    { "answer_text": "no-reply@paypal.com" }
  ],
  "url": "https://platform.phishspot.com/api/v1/blocks/32"
}

Kody statusu

Kod	Kiedy
200	Blok zwrócony.
404	Blok nieosiągalny dla Twojego konta (jego kurs nie jest ani własnością, ani globalny).

PATCH /api/v1/blocks/:id

Aktualizuje blok. Te same dozwolone pola i reguły treści zależne od genre co przy tworzeniu. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola), ale nie możesz edytować bloku w kursie globalnym, który nie należy do Ciebie (403), a blok locked? (kampania w toku) wywołuje błąd not-destroyed podczas aktualizacji.

Parametry

Parametry treści żądania są opakowane w obiekt block. Dozwolone klucze: name, body, course_id, order, genre, metadata, html_data, video_file, document_file.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Id bloku (blk_… lub liczba całkowita).
block	body	object	tak	Obiekt opakowujący zawierający dowolne z dozwolonych pól.
block.name	body	string	nie	Nowa nazwa (walidacja obecności, jeśli podana).
block.genre	body	string	nie	Zmiana genre; ten sam enum co przy tworzeniu. Zmiana genre może sprawić, że inne pola staną się wymagane.
block.body	body	string	nie	Treść tekstowa. Wymagana, chyba że genre to quiz/html/video/file_download.
block.html_data	body	string	nie	Treść w formacie rich HTML.
block.metadata	body	object/array	nie	Dowolny JSON; ładunek quizu (2–6 odpowiedzi, ≥1 poprawna).
block.order	body	integer	nie	Nowa pozycja (liczba całkowita ≥ 0).
block.video_file	body	file	nie	Zastępcze wideo (te same ograniczenia co przy tworzeniu). Puste ciągi ignorowane.
block.document_file	body	file	nie	Zastępczy dokument (≤ 100 MB). Puste ciągi ignorowane.

Żądanie

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "block": { "name": "Identify the phishing sender", "order": 1 } }' \
  https://platform.phishspot.com/api/v1/blocks/32

Odpowiedź 200 OK — zaktualizowany blok (taki sam kształt jak GET /blocks/:id).

{
  "id": 32,
  "name": "Identify the phishing sender",
  "course_id": 7,
  "order": 1,
  "genre": "quiz",
  "metadata": [
    { "question_text": "Which sender is spoofed?" },
    { "answer_text": "no-reply@paypa1.com", "right_answer": "on" },
    { "answer_text": "no-reply@paypal.com" }
  ],
  "created_at": "2026-05-01T09:13:00.000Z",
  "updated_at": "2026-06-02T10:15:00.000Z",
  "locked": false,
  "quiz_question": "Which sender is spoofed?",
  "quiz_answers": [
    { "answer_text": "no-reply@paypa1.com", "right_answer": "on" },
    { "answer_text": "no-reply@paypal.com" }
  ],
  "url": "https://platform.phishspot.com/api/v1/blocks/32"
}

Kody statusu

Kod	Kiedy
200	Blok zaktualizowany.
403	Kurs bloku jest global i nie należy do Twojego konta.
404	Blok nieosiągalny dla Twojego konta.
422	Walidacja nie powiodła się — puste name, brak treści wymaganej przez genre, nieprawidłowe odpowiedzi quizowe, niedozwolony plik, albo blok jest zablokowany przez kampanię w toku. Treść: {"errors": {...}}.

DELETE /api/v1/blocks/:id

Usuwa blok. Kontroler najpierw sprawdza, czy blok jest zablokowany przez trwającą kampanię, i odmawia z kodem 422, jeśli tak jest. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola), ale nie możesz usunąć bloku w kursie globalnym, który nie należy do Ciebie (403).

Parametry

Brak parametrów poza tokenem bearer i id ze ścieżki.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Id bloku (blk_… lub liczba całkowita).

Żądanie

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/blocks/33

Odpowiedź 204 No Content — pusta treść po sukcesie.

Kody statusu

Kod	Kiedy
204	Blok usunięty.
403	Kurs bloku jest global i nie należy do Twojego konta.
404	Blok nieosiągalny dla Twojego konta.
422	Blok jest zablokowany (powiązana kampania jest w toku). Treść: {"errors": ["Cannot delete block because connected campaign is in progress"]}.

27.10 Autopiloty

Autopiloty to powtarzalne, bezobsługowe programy phishingowe: opisujesz odbiorców i kadencję, a platforma sama generuje i dostarcza kampanie, dopóki jej nie zatrzymasz. Autopilot powstaje jako draft, a następnie przechodzi przez niewielki cykl życia (draft → running ⇄ paused → stopped) za pomocą dedykowanych akcji opisanych poniżej.

::: caution Uruchomienie autopilotu aktywuje działający, wysyłający program — platforma zacznie generować i dostarczać prawdziwe kampanie phishingowe do wskazanych członków zgodnie ze skonfigurowaną kadencją. Traktuj POST /autopilots/:id/start jak akcję uruchamiającą produkcję, nie jak przebieg testowy. :::

Kilka faktów o modelu, do których odwołujemy się w całym tym rozdziale:

• Stan (state): jeden z draft, running, paused, stopped.
• Okres intensywności (intensity_period): jeden z day, week, month, year.
• Rodzaj czasu trwania (duration_kind): continuous (działa bez końca) lub until_date (zatrzymuje się w dniu ends_on).
• Typ akcji końcowej (end_action_type): jeden z nothing, redirect_to_course, message_page, redirect_to_url — decyduje, co widzi cel po zakończeniu symulacji.
• Limit dziennego tempa: efektywne tempo wysyłki to intensity_count / period_in_days i nie może przekroczyć 2 kampanii/dzień (day=1, week=7, month=30, year=365 dni na okres). Przekroczenie powoduje błąd walidacji na intensity_count.
• Edytowalność: autopilot jest edytowalny, dopóki nie jest stopped. Po przejściu w stan stopped dostępne pozostają tylko odczyt i usunięcie.

GET /accounts/:account_id/autopilots

Listuje wszystkie autopiloty należące do konta, od najnowszych. Użyj, aby wyrenderować panel autopilotów lub znaleźć id autopilotu przed wykonaniem na nim akcji. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola — członek, edytor lub admin).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Id konta (acct_… lub liczba całkowita).
state	query	string	nie	Filtruje do pojedynczego stanu. Jeden z draft, running, paused, stopped. Każda inna wartość zwraca 422.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  "https://platform.phishspot.com/api/v1/accounts/11/autopilots?state=running"

Odpowiedź 200 OK — tablica JSON obiektów autopilota (każdy identyczny z odpowiedzią dla pojedynczego autopilotu poniżej).

Pole	Typ	Opis
id	integer	Id autopilotu.
account_id	integer	Id konta będącego właścicielem.
name	string	Nazwa wyświetlana.
state	string	draft | running | paused | stopped.
all_groups	boolean	Czy autopilot kieruje się do wszystkich grup (zamiast do wymienionych groups).
intensity_count	integer	Liczba kampanii na intensity_period.
intensity_period	string	day | week | month | year.
duration_kind	string	continuous | until_date.
ai_optimizer_enabled	boolean	Czy optymalizacja AI jest włączona.
auto_include_new_members	boolean	Czy nowi członkowie są automatycznie dołączani.
language	string	Kod języka docelowego (np. en, pl).
end_action_type	string	nothing | redirect_to_course | message_page | redirect_to_url.
end_action_url	string | null	URL przekierowania (używany, gdy end_action_type to redirect_to_url).
created_at	string	Znacznik czasu ISO-8601.
updated_at	string	Znacznik czasu ISO-8601.
ends_on	string | null	Data ISO-8601, w której program się zatrzymuje (gdy duration_kind to until_date), w przeciwnym razie null.
started_at	string | null	Znacznik czasu ISO-8601 pierwszego uruchomienia, w przeciwnym razie null.
daily_rate	number	Efektywna liczba kampanii/dzień, zaokrąglona do 2 miejsc po przecinku.
progress_percentage	integer | null	Całkowity % oczekiwanych kampanii dostarczonych w bieżącym okresie; null dla draft/stopped.
course_id	integer | null	Id powiązanego kursu e-learningowego, w przeciwnym razie null.
editable	boolean	false tylko wtedy, gdy state to stopped.
groups	array	Docelowe grupy. Każda: { "id": integer, "name": string }.
recent_campaigns	array	Do 10 najnowszych wygenerowanych kampanii, od najnowszych. Każda: { "id": integer, "name": string, "state": string }.

[
  {
    "id": 7,
    "account_id": 11,
    "name": "Finance team — quarterly drip",
    "state": "running",
    "all_groups": false,
    "intensity_count": 2,
    "intensity_period": "month",
    "duration_kind": "continuous",
    "ai_optimizer_enabled": true,
    "auto_include_new_members": true,
    "language": "en",
    "end_action_type": "redirect_to_course",
    "end_action_url": null,
    "created_at": "2026-05-01T09:00:00Z",
    "updated_at": "2026-06-01T12:30:00Z",
    "ends_on": null,
    "started_at": "2026-05-02T08:00:00Z",
    "daily_rate": 0.07,
    "progress_percentage": 88,
    "course_id": 14,
    "editable": true,
    "groups": [
      { "id": 3, "name": "Finance" }
    ],
    "recent_campaigns": [
      { "id": 102, "name": "Invoice approval — May", "state": "completed" }
    ]
  }
]

Kody statusu

Kod	Kiedy
200	Lista zwrócona (być może pusta).
404	account_id nie istnieje lub użytkownik tokenu nie jest jego członkiem.
422	Parametr query state jest obecny, ale nie jest jednym z draft, running, paused, stopped.

POST /accounts/:account_id/autopilots

Tworzy nowy autopilot w stanie draft. Puste pola są wstępnie wypełniane z ustawień autopilotu konta oraz domyślnych wartości konta (branża, język, URL/HTML akcji końcowej, domyślny kurs), więc nawet minimalna treść żądania daje użyteczny szkic. Autopilot nie jest uruchamiany — wywołaj potem start, aby przejść na żywo. Uwierzytelnianie: Bearer; rola: admin/edytor.

Treść żądania jest opakowana w obiekt autopilot.

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Id konta (acct_… lub liczba całkowita).
name	body	string	tak	Nazwa wyświetlana. Maks. 80 znaków; musi być unikalna w obrębie konta (bez rozróżniania wielkości liter).
all_groups	body	boolean	nie	Kieruj do wszystkich grup. Domyślnie true.
group_ids	body	array	nie	Prefiksowane id grup (grp_…), do których kierować. Nieznane/obce id → 422. Używane, gdy all_groups to false.
intensity_count	body	integer	nie	Liczba kampanii na okres. Musi być ≥ 1. Domyślnie 1. Wynikowe dzienne tempo (intensity_count / period_days) musi być ≤ 2/dzień.
intensity_period	body	string	nie	day | week | month | year. Domyślnie month.
duration_kind	body	string	nie	continuous | until_date. Domyślnie continuous.
ends_on	body	string (date)	warunkowo	Wymagane (i musi być datą przyszłą), gdy duration_kind to until_date.
ai_optimizer_enabled	body	boolean	nie	Domyślnie true.
auto_include_new_members	body	boolean	nie	Domyślnie true.
language	body	string	nie	Kod języka docelowego (np. en, pl). Wstępnie wypełniany z ustawień/lokalizacji konta, jeśli pusty.
industry_code_id	body	integer	nie	Id kodu branży. Wstępnie wypełniany z ustawień konta, jeśli pusty.
end_action_type	body	string	nie	nothing | redirect_to_course | message_page | redirect_to_url. Domyślnie message_page.
end_action_url	body	string	warunkowo	Wymagane i musi być http/https, gdy end_action_type to redirect_to_url.
end_action_html	body	string	warunkowo	Wymagane, gdy end_action_type to message_page (wstępnie wypełniane z domyślnych wartości konta, jeśli puste).
course_id	body	string	warunkowo	Prefiksowane id kursu (course_…); musi należeć do konta albo być kursem globalnym (inaczej 422). Wymagane, gdy end_action_type to redirect_to_course.

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
        "autopilot": {
          "name": "Finance team — quarterly drip",
          "all_groups": false,
          "group_ids": ["grp_3a9k"],
          "intensity_count": 2,
          "intensity_period": "month",
          "duration_kind": "continuous",
          "end_action_type": "redirect_to_course",
          "course_id": "course_8h2d"
        }
      }' \
  https://platform.phishspot.com/api/v1/accounts/11/autopilots

Odpowiedź 201 Created — nowo utworzony autopilot, w tym samym kształcie co element listy powyżej (state będzie draft, a started_at i progress_percentage null).

{
  "id": 9,
  "account_id": 11,
  "name": "Finance team — quarterly drip",
  "state": "draft",
  "all_groups": false,
  "intensity_count": 2,
  "intensity_period": "month",
  "duration_kind": "continuous",
  "ai_optimizer_enabled": true,
  "auto_include_new_members": true,
  "language": "en",
  "end_action_type": "redirect_to_course",
  "end_action_url": null,
  "created_at": "2026-06-02T10:15:00Z",
  "updated_at": "2026-06-02T10:15:00Z",
  "ends_on": null,
  "started_at": null,
  "daily_rate": 0.07,
  "progress_percentage": null,
  "course_id": 14,
  "editable": true,
  "groups": [
    { "id": 3, "name": "Finance" }
  ],
  "recent_campaigns": []
}

Kody statusu

Kod	Kiedy
201	Autopilot utworzony.
400	Opakowanie treści autopilot jest całkowicie nieobecne.
403	Użytkownik tokenu jest member (tylko odczyt) na koncie — tylko admini/edytorzy mogą tworzyć.
404	account_id nie istnieje lub użytkownik tokenu nie jest jego członkiem.
422	Walidacja nie powiodła się — np. pusta/zduplikowana/zbyt długa name, dzienne tempo powyżej limitu 2/dzień, brak ends_on dla until_date, brak end_action_url/end_action_html/course_id dla wybranego end_action_type albo nieznane group_ids / course_id.

GET /autopilots/:id

Pobiera pojedynczy autopilot po jego id. To trasa płaska (niezagnieżdżona) — bez account_id w ścieżce; konto jest wnioskowane z autopilotu, a członkostwo użytkownika tokenu jest weryfikowane. Uwierzytelnianie: Bearer; rola: admin/edytor.

Brak parametrów poza tokenem bearer.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Id autopilotu (auto_… lub liczba całkowita).

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/autopilots/9

Odpowiedź 200 OK — pojedynczy obiekt autopilota (identyczny zestaw pól jak element listy udokumentowany w GET …/autopilots).

{
  "id": 9,
  "account_id": 11,
  "name": "Finance team — quarterly drip",
  "state": "running",
  "all_groups": false,
  "intensity_count": 2,
  "intensity_period": "month",
  "duration_kind": "continuous",
  "ai_optimizer_enabled": true,
  "auto_include_new_members": true,
  "language": "en",
  "end_action_type": "redirect_to_course",
  "end_action_url": null,
  "created_at": "2026-06-02T10:15:00Z",
  "updated_at": "2026-06-02T10:16:00Z",
  "ends_on": null,
  "started_at": "2026-06-02T10:16:00Z",
  "daily_rate": 0.07,
  "progress_percentage": 100,
  "course_id": 14,
  "editable": true,
  "groups": [
    { "id": 3, "name": "Finance" }
  ],
  "recent_campaigns": []
}

Kody statusu

Kod	Kiedy
200	Autopilot zwrócony.
403	Użytkownik tokenu jest member (tylko odczyt) na koncie autopilotu — odczyt pojedynczego autopilotu wymaga roli admin/edytor.
404	Brak autopilotu o tym id lub użytkownik tokenu nie ma aktywnego członkostwa w jego koncie.

PATCH /autopilots/:id

Aktualizuje konfigurację autopilotu. Treść żądania jest opakowana w obiekt autopilot i przyjmuje te same pola co przy tworzeniu. Przekazanie group_ids zastępuje cały zestaw docelowych grup. Uwierzytelnianie: Bearer; rola: admin/edytor — a autopilot musi być edytowalny (nie stopped). Trasa płaska (bez account_id).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Id autopilotu (auto_… lub liczba całkowita).
name	body	string	nie	Nazwa wyświetlana. Maks. 80 znaków; unikalna w obrębie konta (bez rozróżniania wielkości liter).
all_groups	body	boolean	nie	Kieruj do wszystkich grup.
group_ids	body	array	nie	Prefiksowane id grup (grp_…). Gdy obecne, zastępują bieżący zestaw grup; nieznane/obce id → 422.
intensity_count	body	integer	nie	Liczba kampanii na okres (≥ 1; dzienne tempo musi pozostać ≤ 2/dzień).
intensity_period	body	string	nie	day | week | month | year.
duration_kind	body	string	nie	continuous | until_date.
ends_on	body	string (date)	warunkowo	Wymagana data przyszła, gdy duration_kind to until_date.
ai_optimizer_enabled	body	boolean	nie	Przełącz optymalizację AI.
auto_include_new_members	body	boolean	nie	Przełącz automatyczne dołączanie.
language	body	string	nie	Kod języka docelowego.
industry_code_id	body	integer	nie	Id kodu branży.
end_action_type	body	string	nie	nothing | redirect_to_course | message_page | redirect_to_url.
end_action_url	body	string	warunkowo	Wymagany URL http/https, gdy end_action_type to redirect_to_url.
end_action_html	body	string	warunkowo	Wymagane, gdy end_action_type to message_page.
course_id	body	string	warunkowo	Prefiksowane id kursu (course_…); musi należeć do konta albo być globalne. Wymagane, gdy end_action_type to redirect_to_course.

Żądanie

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "autopilot": { "intensity_count": 1, "intensity_period": "week" } }' \
  https://platform.phishspot.com/api/v1/autopilots/9

Odpowiedź 200 OK — zaktualizowany obiekt autopilota (ten sam kształt co GET /autopilots/:id).

{
  "id": 9,
  "account_id": 11,
  "name": "Finance team — quarterly drip",
  "state": "running",
  "all_groups": false,
  "intensity_count": 1,
  "intensity_period": "week",
  "duration_kind": "continuous",
  "ai_optimizer_enabled": true,
  "auto_include_new_members": true,
  "language": "en",
  "end_action_type": "redirect_to_course",
  "end_action_url": null,
  "created_at": "2026-06-02T10:15:00Z",
  "updated_at": "2026-06-02T11:00:00Z",
  "ends_on": null,
  "started_at": "2026-06-02T10:16:00Z",
  "daily_rate": 0.14,
  "progress_percentage": 100,
  "course_id": 14,
  "editable": true,
  "groups": [
    { "id": 3, "name": "Finance" }
  ],
  "recent_campaigns": []
}

Kody statusu

Kod	Kiedy
200	Autopilot zaktualizowany.
400	Opakowanie treści autopilot jest całkowicie nieobecne.
403	Użytkownik tokenu jest member (tylko odczyt) lub autopilot jest stopped (zatrzymane autopiloty są tylko do odczytu — wyłącznie usunięcie).
404	Brak autopilotu o tym id lub użytkownik tokenu nie ma aktywnego członkostwa w jego koncie.
422	Walidacja nie powiodła się — te same przyczyny co przy tworzeniu (name, limit dziennego tempa, ends_on, wymagania akcji końcowej, nieznane group_ids/course_id).

DELETE /autopilots/:id

Trwale usuwa autopilot i jego powiązania z grupami; wygenerowane kampanie są odłączane (nie usuwane). Autopilotu w stanie running nie da się usunąć — najpierw go zatrzymaj. Uwierzytelnianie: Bearer; rola: admin/edytor. Trasa płaska (bez account_id).

Brak parametrów poza tokenem bearer.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Id autopilotu (auto_… lub liczba całkowita).

Żądanie

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/autopilots/9

Odpowiedź 204 No Content — puste ciało przy powodzeniu.

Kody statusu

Kod	Kiedy
204	Autopilot usunięty.
403	Użytkownik tokenu jest member (tylko odczyt) na koncie autopilotu.
404	Brak autopilotu o tym id lub użytkownik tokenu nie ma aktywnego członkostwa w jego koncie.
422	Autopilot jest running — zatrzymaj go przed usunięciem. (Autopilot paused lub draft można usunąć bezpośrednio.)

POST /autopilots/:id/start

Aktywuje autopilot: ustawia state na running (oznaczając started_at przy pierwszym uruchomieniu), aby platforma zaczęła generować i dostarczać kampanie ze skonfigurowaną kadencją. Użyj, aby przejść na żywo lub wznowić autopilot w stanie paused. Uwierzytelnianie: Bearer; rola: admin/edytor — a autopilot musi być edytowalny (nie stopped). Trasa płaska.

::: caution To akcja na żywo: udane wywołanie rozpoczyna wysyłkę prawdziwych symulowanych wiadomości phishingowych do wskazanych członków. :::

Brak parametrów poza tokenem bearer.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Id autopilotu (auto_… lub liczba całkowita).

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/autopilots/9/start

Odpowiedź 200 OK — obiekt autopilota z state: "running" (ten sam kształt co GET /autopilots/:id).

{
  "id": 9,
  "name": "Finance team — quarterly drip",
  "state": "running",
  "started_at": "2026-06-02T10:16:00Z",
  "editable": true,
  "progress_percentage": 100,
  "daily_rate": 0.07
}

Kody statusu

Kod	Kiedy
200	Autopilot uruchomiony/wznowiony; teraz running.
403	Użytkownik tokenu jest member (tylko odczyt) lub autopilot jest stopped (zatrzymanego autopilotu nie można uruchomić ponownie).
404	Brak autopilotu o tym id lub użytkownik tokenu nie ma aktywnego członkostwa w jego koncie.

POST /autopilots/:id/pause

Wstrzymuje działający (running) autopilot: ustawia state na paused, więc nie są generowane nowe kampanie. Wznów później przez start. Uwierzytelnianie: Bearer; rola: admin/edytor — a autopilot musi być edytowalny (nie stopped). Trasa płaska.

Brak parametrów poza tokenem bearer.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Id autopilotu (auto_… lub liczba całkowita).

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/autopilots/9/pause

Odpowiedź 200 OK — obiekt autopilota z state: "paused" (ten sam kształt co GET /autopilots/:id).

{
  "id": 9,
  "name": "Finance team — quarterly drip",
  "state": "paused",
  "started_at": "2026-06-02T10:16:00Z",
  "editable": true,
  "progress_percentage": 92
}

Kody statusu

Kod	Kiedy
200	Autopilot wstrzymany.
403	Użytkownik tokenu jest member (tylko odczyt) lub autopilot jest stopped.
404	Brak autopilotu o tym id lub użytkownik tokenu nie ma aktywnego członkostwa w jego koncie.

POST /autopilots/:id/stop

Zatrzymuje autopilot na stałe: ustawia state na stopped. Zatrzymany autopilot staje się tylko do odczytu — nie można go już aktualizować, uruchamiać, wstrzymywać ani ponownie zatrzymywać, można go jedynie przeglądać lub usunąć. Uwierzytelnianie: Bearer; rola: admin/edytor — a autopilot musi być nadal edytowalny (nie już stopped). Trasa płaska.

Brak parametrów poza tokenem bearer.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Id autopilotu (auto_… lub liczba całkowita).

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/autopilots/9/stop

Odpowiedź 200 OK — obiekt autopilota z state: "stopped" i editable: false (ten sam kształt co GET /autopilots/:id).

{
  "id": 9,
  "name": "Finance team — quarterly drip",
  "state": "stopped",
  "started_at": "2026-06-02T10:16:00Z",
  "editable": false,
  "progress_percentage": null
}

Kody statusu

Kod	Kiedy
200	Autopilot zatrzymany.
403	Użytkownik tokenu jest member (tylko odczyt) lub autopilot jest już stopped.
404	Brak autopilotu o tym id lub użytkownik tokenu nie ma aktywnego członkostwa w jego koncie.

27.11 Domeny wysyłkowe

Dwa powiązane zasoby kontrolują, z których domen może wysyłać kampania:

• Domeny platformy (pdm_…) to domeny atakującego/landingowe obsługiwane przez PhishSpot. Większość należy do platformy (“publiczne” lub przypisane “prywatne” domeny); klienci mogą też dostarczyć własne (BYOD) za pomocą provision_byod. Bezpośredni zapis rekordów domen platformy (POST/PATCH/DELETE /platform_domains) jest zarezerwowany dla użytkowników z rolą admin; provisioning domeny BYOD jest dostępny dla każdego członka konta.
• Domeny zabezpieczone (sdm_…) to dowody własności DNS. Klient dodaje domenę, którą kontroluje, umieszcza rekord TXT i weryfikuje go — w ten sposób PhishSpot potwierdza, że nadawca może wysyłać “z” tej domeny.

GET /api/v1/platform_domains

Zwraca listę wszystkich domen platformy widocznych dla konta wywołującego tokena — wszystkie operacyjne domeny publiczne oraz wszystkie operacyjne domeny prywatne przypisane do konta. Wyniki są uporządkowane według nazwy. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Brak parametrów poza tokenem bearer.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/platform_domains

Odpowiedź 200 OK — tablica JSON obiektów domen platformy (każdy obiekt używa tych samych pól, co poniższy punkt końcowy show).

Pole	Typ	Opis
id	integer	Numeryczny identyfikator. (W adresach URL używaj identyfikatora z prefiksem pdm_….)
name	string	Nazwa domeny (np. officelogin.in).
public	boolean	Starsza flaga publiczna z kolumny.
mail	boolean	Czy jest to domena pocztowa platformy.
state	string	Stan cyklu życia. Jeden z pending, checking, confirmed, purchasing, purchased, configuring_dns, dns_pending, configuring_postal, active, failed.
expires_on	string|null	Data wygaśnięcia rejestracji w formacie ISO8601 lub null.
metadata	object	Dowolny JSON (szczegóły provisioningu Cloudflare/Postal, diagnostyka itp.).
created_at	string	Znacznik czasu ISO8601.
updated_at	string	Znacznik czasu ISO8601.
active	boolean	True, gdy state == "active".
byod	boolean	True dla rekordów klienta typu “bring your own domain”.
sending_blocked	boolean	True, gdy domena jest aktywna, ale zablokowana przed rozpoczęciem nowych wysyłek.
nameservers	array	Serwery nazw Cloudflare przypisane do strefy tej domeny (puste, dopóki nie zostaną przechwycone).
cloudflare_error	string|null	Ustawione, jeśli nie udało się utworzyć/odczytać strefy Cloudflare.

[
  {
    "id": 42,
    "name": "officelogin.in",
    "public": true,
    "mail": false,
    "state": "active",
    "expires_on": "2027-03-01T00:00:00.000Z",
    "metadata": {},
    "created_at": "2026-01-10T09:00:00.000Z",
    "updated_at": "2026-05-30T14:22:00.000Z",
    "active": true,
    "byod": false,
    "sending_blocked": false,
    "nameservers": [],
    "cloudflare_error": null
  }
]

Kody statusu

Kod	Kiedy
200	Domeny zwrócone (możliwe, że pusta tablica).

GET /api/v1/platform_domains/:id

Pobiera pojedynczą domenę platformy po identyfikatorze. Przydatne do sprawdzenia stanu, serwerów nazw BYOD oraz sending_blocked przed wybraniem jej do kampanii. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator domeny platformy (pdm_… lub liczba całkowita).

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/platform_domains/pdm_42

Odpowiedź 200 OK — pojedynczy obiekt domeny platformy (te same pola, co powyższy punkt końcowy listy).

{
  "id": 42,
  "name": "officelogin.in",
  "public": true,
  "mail": false,
  "state": "active",
  "expires_on": "2027-03-01T00:00:00.000Z",
  "metadata": {},
  "created_at": "2026-01-10T09:00:00.000Z",
  "updated_at": "2026-05-30T14:22:00.000Z",
  "active": true,
  "byod": false,
  "sending_blocked": false,
  "nameservers": [],
  "cloudflare_error": null
}

Kody statusu

Kod	Kiedy
200	Domena znaleziona.
404	Brak domeny platformy o tym identyfikatorze.

POST /api/v1/platform_domains

Tworzy bezpośrednio rekord domeny należącej do platformy. Jest to operacja administracyjna służąca do zarządzania własną pulą domen platformy — klienci powinni zamiast tego używać provision_byod. Uwierzytelnianie: Bearer; rola: admin.

Parametry — opakowane w obiekt platform_domain.

Nazwa	Gdzie	Typ	Wymagane	Opis
platform_domain.name	body	string	tak	Nazwa domeny. Zamieniana na małe litery/przycinana; musi być prawidłową domeną (3–253 znaki, co najmniej jedna kropka, tylko a-z 0-9 . -, bez wiodącej/końcowej kropki ani myślnika, bez kolejnych ../--, etykiety ≤63 znaki). Musi być globalnie unikalna (bez rozróżniania wielkości liter).
platform_domain.public	body	boolean	nie	Starsza flaga publiczna.
platform_domain.metadata	body	object	nie	Dowolne metadane JSON.
platform_domain.expires_on	body	string	nie	Data wygaśnięcia rejestracji w formacie ISO8601.

`state`, `genre` i `source` nie są ustawialne przez API; rekord utworzony tutaj domyślnie przyjmuje `state: "active"`, `genre: "public"`, `source: "manual"`.

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "platform_domain": { "name": "secure-portal.co", "public": true } }' \
  https://platform.phishspot.com/api/v1/platform_domains

Odpowiedź 201 Created — utworzony obiekt domeny platformy (te same pola, co punkt końcowy show).

{
  "id": 77,
  "name": "secure-portal.co",
  "public": true,
  "mail": false,
  "state": "active",
  "expires_on": null,
  "metadata": {},
  "created_at": "2026-06-02T10:00:00.000Z",
  "updated_at": "2026-06-02T10:00:00.000Z",
  "active": true,
  "byod": false,
  "sending_blocked": false,
  "nameservers": [],
  "cloudflare_error": null
}

Kody statusu

Kod	Kiedy
201	Domena utworzona.
403	Wywołujący nie jest administratorem.
422	Walidacja nieudana (np. pusta/zduplikowana/nieprawidłowa name). Treść: { "errors": { "name": ["..."] } }.

PATCH /api/v1/platform_domains/:id

Aktualizuje rekord domeny należącej do platformy. Uwierzytelnianie: Bearer; rola: admin.

Parametry — ta sama opakowana treść platform_domain, co przy tworzeniu; wszystkie pola opcjonalne.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator domeny platformy (pdm_… lub liczba całkowita).
platform_domain.name	body	string	nie	Nowa nazwa domeny (te same reguły walidacji, co przy tworzeniu).
platform_domain.public	body	boolean	nie	Starsza flaga publiczna.
platform_domain.metadata	body	object	nie	Dowolne metadane JSON.
platform_domain.expires_on	body	string	nie	Data wygaśnięcia rejestracji w formacie ISO8601.

Zmiana nazwy lub inna aktualizacja domeny powiązanej z trwającą (zablokowaną) kampanią jest odrzucana na poziomie modelu (`ActiveRecord::RecordNotDestroyed`), co objawia się jako błąd z zakresu 500, a nie 422. Unikaj edytowania domen przypisanych do działających kampanii.

Żądanie

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "platform_domain": { "expires_on": "2028-01-01T00:00:00Z" } }' \
  https://platform.phishspot.com/api/v1/platform_domains/pdm_42

Odpowiedź 200 OK — zaktualizowany obiekt domeny platformy (te same pola, co punkt końcowy show).

Kody statusu

Kod	Kiedy
200	Domena zaktualizowana.
403	Wywołujący nie jest administratorem.
404	Brak domeny platformy o tym identyfikatorze.
422	Walidacja nieudana. Treść: { "errors": { ... } }.

DELETE /api/v1/platform_domains/:id

Usuwa domenę należącą do platformy. Domenę można usunąć tylko wtedy, gdy nie ma blokujących powiązań: domeny należące do platformy nie mogą mieć kampanii ani przypisanych kont; domeny BYOD nie mogą mieć aktywnych (trwających/wstrzymanych) kampanii. Uwierzytelnianie: Bearer; rola: admin.

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator domeny platformy (pdm_… lub liczba całkowita).

Żądanie

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/platform_domains/pdm_42

Odpowiedź 204 No Content — pusta treść przy powodzeniu.

Kody statusu

Kod	Kiedy
204	Domena usunięta.
403	Wywołujący nie jest administratorem.
404	Brak domeny platformy o tym identyfikatorze.
422	Domena nadal ma aktywne kampanie (lub inne blokujące powiązania). Treść: { "error": "Cannot delete platform domain with active campaigns" }.

POST /api/v1/platform_domains/:id/check

Ponownie sprawdza stan provisioningu/kondycji BYOD domeny należącej do konta wywołującego, a następnie zwraca (przeładowaną) domenę. Użyj tego do odpytywania domeny BYOD po delegowaniu serwerów nazw: aktywna domena uruchamia kontrolę kondycji, a domena nadal w trakcie provisioningu odświeża swój status konfiguracji. Przejściowe błędy odświeżania są wyciszane, aby odpytywanie nigdy nie zwracało błędu — otrzymujesz po prostu ostatni utrwalony stan. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola), ale użytkownik tokena musi należeć do konta będącego właścicielem domeny.

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator domeny platformy (pdm_… lub liczba całkowita). Musi to być domena BYOD należąca do konta, do którego należy wywołujący.

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/platform_domains/pdm_88/check

Odpowiedź 200 OK — odświeżony obiekt domeny platformy (te same pola, co punkt końcowy show). Obserwuj state, active, nameservers, sending_blocked oraz cloudflare_error, aby śledzić postęp.

{
  "id": 88,
  "name": "mail.acme-customer.com",
  "public": false,
  "mail": false,
  "state": "dns_pending",
  "expires_on": null,
  "metadata": { "cloudflare_nameservers": ["kara.ns.cloudflare.com", "rob.ns.cloudflare.com"] },
  "created_at": "2026-06-01T08:00:00.000Z",
  "updated_at": "2026-06-02T09:30:00.000Z",
  "active": false,
  "byod": true,
  "sending_blocked": false,
  "nameservers": ["kara.ns.cloudflare.com", "rob.ns.cloudflare.com"],
  "cloudflare_error": null
}

Kody statusu

Kod	Kiedy
200	Status odświeżony i domena zwrócona.
404	Brak takiej domeny lub domena nie ma konta właściciela / wywołujący nie należy do jej konta właściciela.

POST /api/v1/accounts/:account_id/platform_domains/provision_byod

Provisionuje dla konta domenę wysyłkową klienta typu “bring your own domain” (BYOD). Tworzy prywatną domenę platformy BYOD w stanie provisioningu i zwraca serwery nazw Cloudflare, które właściciel domeny musi ustawić u swojego rejestratora; delegacja i weryfikacja kończą się następnie asynchronicznie (odpytuj za pomocą POST /platform_domains/:id/check). Idempotentne — ponowny provisioning domeny, którą konto już posiada, po prostu ponownie wyświetla jej serwery nazw. Uwierzytelnianie: Bearer; rola: dowolna rola, ale wywołujący musi należeć do account_id.

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita), do którego należy wywołujący.
domain_name	body	string	tak	Domena do provisioningu (np. mail.acme-customer.com). Zamieniana na małe litery/przycinana po stronie serwera. Nie opakowana w żaden obiekt — wysyłana jako klucz najwyższego poziomu.

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "domain_name": "mail.acme-customer.com" }' \
  https://platform.phishspot.com/api/v1/accounts/11/platform_domains/provision_byod

Odpowiedź 201 Created — wyprovisionowany obiekt domeny platformy wraz ze wskazówkami dotyczącymi provisioningu. Wszystkie pola domeny platformy z punktu końcowego show oraz dodatkowo:

Pole	Typ	Opis
nameservers	array	Serwery nazw Cloudflare, które właściciel domeny musi ustawić u swojego rejestratora. (Obecne także w obiekcie bazowym; powtórzone na najwyższym poziomie dla wygody.)
next_step	string	Czytelna dla człowieka instrukcja opisująca zmianę u rejestratora oraz punkt końcowy check do odpytywania.

{
  "id": 88,
  "name": "mail.acme-customer.com",
  "public": null,
  "mail": false,
  "state": "dns_pending",
  "expires_on": null,
  "metadata": { "cloudflare_nameservers": ["kara.ns.cloudflare.com", "rob.ns.cloudflare.com"] },
  "created_at": "2026-06-02T09:00:00.000Z",
  "updated_at": "2026-06-02T09:00:00.000Z",
  "active": false,
  "byod": true,
  "sending_blocked": false,
  "nameservers": ["kara.ns.cloudflare.com", "rob.ns.cloudflare.com"],
  "cloudflare_error": null,
  "next_step": "At the registrar for mail.acme-customer.com, replace the nameservers with the ones above, then poll POST /api/v1/platform_domains/pdm_88/check."
}

Kody statusu

Kod	Kiedy
201	Domena wyprovisionowana (lub ponownie wyświetlona, jeśli już należy do tego konta).
403	Wywołujący nie należy do account_id (odmowa Pundit show?).
404	account_id nie znaleziono wśród kont wywołującego. Treść: { "error": "Account not found" }.
422	Provisioning odrzucony. Treść: { "error": "<message>" }, jeden z: pusta nazwa ("Domain name is required."), już zarejestrowana przez inne konto ("That domain is already registered in PhishSpot by another account.") lub nieprawidłowa domena ("That domain name is invalid.").

GET /api/v1/accounts/:account_id/secured_domains

Zwraca listę zabezpieczonych (z potwierdzoną własnością) domen konta, od najnowszej. Opcjonalnie filtruje według stanu weryfikacji. Uwierzytelnianie: Bearer; rola: dowolna rola, ale wywołujący musi należeć do account_id.

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita), do którego należy wywołujący.
state	query	string	nie	Filtr według stanu weryfikacji. Jeden z pending, verified, failed. Pomiń, aby uzyskać wszystkie.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  "https://platform.phishspot.com/api/v1/accounts/11/secured_domains?state=verified"

Odpowiedź 200 OK — tablica JSON obiektów domen zabezpieczonych.

Pole	Typ	Opis
id	integer	Numeryczny identyfikator. (W adresach URL używaj identyfikatora z prefiksem sdm_….)
account_id	integer	Identyfikator konta będącego właścicielem.
domain	string	Weryfikowana domena (zamieniona na małe litery).
state	string	Stan weryfikacji: pending, verified lub failed.
verification_attempts	integer	Liczba wykonanych prób weryfikacji DNS.
verified_at	string|null	Znacznik czasu ISO8601 pomyślnej weryfikacji lub null.
created_at	string	Znacznik czasu ISO8601.
updated_at	string	Znacznik czasu ISO8601.
dns_record	object	Rekord TXT, który właściciel musi opublikować, aby udowodnić własność.
dns_record.type	string	Zawsze "TXT".
dns_record.name	string	Host rekordu, np. _phishspot-verify.example.com.
dns_record.value	string	Wartość rekordu, np. phishspot-verify=<64-hex-token>.

[
  {
    "id": 5,
    "account_id": 11,
    "domain": "acme-customer.com",
    "state": "verified",
    "verification_attempts": 2,
    "verified_at": "2026-05-20T11:00:00.000Z",
    "created_at": "2026-05-19T16:30:00.000Z",
    "updated_at": "2026-05-20T11:00:00.000Z",
    "dns_record": {
      "type": "TXT",
      "name": "_phishspot-verify.acme-customer.com",
      "value": "phishspot-verify=3f9a...c2"
    }
  }
]

Kody statusu

Kod	Kiedy
200	Domeny zwrócone (możliwe, że pusta tablica).
403	Wywołujący nie należy do account_id.
404	account_id nie znaleziono wśród kont wywołującego. Treść: { "error": "Account not found" }.

POST /api/v1/accounts/:account_id/secured_domains

Dodaje domenę kontrolowaną przez klienta i zwraca rekord TXT do opublikowania w celu weryfikacji własności. Domeny publicznych dostawców poczty (np. gmail.com) są odrzucane. Uwierzytelnianie: Bearer; rola: dowolna rola, ale wywołujący musi należeć do account_id.

Parametry — opakowane w obiekt secured_domain.

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita), do którego należy wywołujący.
secured_domain.domain	body	string	tak	Domena do weryfikacji (np. acme-customer.com). Zamieniana na małe litery/przycinana; musi odpowiadać standardowemu formatowi domeny; musi być unikalna w obrębie konta (bez rozróżniania wielkości liter); nie może być zablokowaną domeną publicznego dostawcy poczty.

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "secured_domain": { "domain": "acme-customer.com" } }' \
  https://platform.phishspot.com/api/v1/accounts/11/secured_domains

Odpowiedź 201 Created — utworzony obiekt domeny zabezpieczonej (te same pola, co punkt końcowy listy), z state: "pending" oraz świeżo wygenerowanym dns_record do opublikowania.

{
  "id": 6,
  "account_id": 11,
  "domain": "acme-customer.com",
  "state": "pending",
  "verification_attempts": 0,
  "verified_at": null,
  "created_at": "2026-06-02T10:00:00.000Z",
  "updated_at": "2026-06-02T10:00:00.000Z",
  "dns_record": {
    "type": "TXT",
    "name": "_phishspot-verify.acme-customer.com",
    "value": "phishspot-verify=3f9a...c2"
  }
}

Kody statusu

Kod	Kiedy
201	Domena dodana; opublikuj zwrócony rekord TXT, a następnie wywołaj verify_dns.
403	Wywołujący nie należy do account_id.
404	account_id nie znaleziono wśród kont wywołującego. Treść: { "error": "Account not found" }.
422	Walidacja nieudana — pusty/nieprawidłowy format, duplikat dla tego konta lub zablokowana domena publicznego dostawcy poczty. Treść: { "errors": { "domain": ["..."] } }.

GET /api/v1/secured_domains/:id

Pobiera pojedynczą domenę zabezpieczoną po identyfikatorze, wraz z rekordem TXT potrzebnym do weryfikacji. Trasa płytka (nie zagnieżdżona pod kontem) — wywołujący musi należeć do konta będącego właścicielem. Uwierzytelnianie: Bearer; rola: dowolna rola (członek konta).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator domeny zabezpieczonej (sdm_… lub liczba całkowita).

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/secured_domains/sdm_6

Odpowiedź 200 OK — pojedynczy obiekt domeny zabezpieczonej (te same pola, co powyższy punkt końcowy listy).

Kody statusu

Kod	Kiedy
200	Domena znaleziona.
403	Odmowa Pundit (zwykle nie powinna wystąpić — polityka zezwala każdemu członkowi).
404	Brak takiej domeny lub wywołujący nie należy do konta będącego jej właścicielem.

DELETE /api/v1/secured_domains/:id

Usuwa domenę zabezpieczoną. Zablokowane, dopóki jakakolwiek aktywna (trwająca/wstrzymana) kampania wysyła z adresu e-mail w tej domenie. Trasa płytka — wywołujący musi należeć do konta będącego właścicielem. Uwierzytelnianie: Bearer; rola: dowolna rola (członek konta).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator domeny zabezpieczonej (sdm_… lub liczba całkowita).

Żądanie

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/secured_domains/sdm_6

Odpowiedź 204 No Content — pusta treść przy powodzeniu.

Kody statusu

Kod	Kiedy
204	Domena usunięta.
403	Odmowa Pundit (zwykle nie powinna wystąpić).
404	Brak takiej domeny lub wywołujący nie należy do konta będącego jej właścicielem.
422	Domena jest zweryfikowana i używana przez aktywne kampanie. Treść: { "error": "Cannot delete secured domain <domain> while it is used by active campaigns: <campaign names>" }.

POST /api/v1/secured_domains/:id/verify_dns

Uruchamia weryfikację DNS: wyszukuje oczekiwany rekord TXT dla domeny i, jeśli go znajdzie, oznacza domenę jako verified. Wywołaj to po opublikowaniu rekordu TXT zwróconego przy tworzeniu. Zwraca (przeładowaną) domenę, abyś mógł odczytać wynikowy state. Trasa płytka — wywołujący musi należeć do konta będącego właścicielem. Uwierzytelnianie: Bearer; rola: dowolna rola (członek konta).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator domeny zabezpieczonej (sdm_… lub liczba całkowita).

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/secured_domains/sdm_6/verify_dns

Odpowiedź 200 OK — odświeżony obiekt domeny zabezpieczonej (te same pola, co punkt końcowy listy). Przy powodzeniu state zmienia się na "verified", a verified_at zostaje ustawione; w przeciwnym razie pozostaje pending/failed, a verification_attempts wzrasta.

{
  "id": 6,
  "account_id": 11,
  "domain": "acme-customer.com",
  "state": "verified",
  "verification_attempts": 1,
  "verified_at": "2026-06-02T10:05:00.000Z",
  "created_at": "2026-06-02T10:00:00.000Z",
  "updated_at": "2026-06-02T10:05:00.000Z",
  "dns_record": {
    "type": "TXT",
    "name": "_phishspot-verify.acme-customer.com",
    "value": "phishspot-verify=3f9a...c2"
  }
}

Kody statusu

Kod	Kiedy
200	Weryfikacja przeprowadzona; sprawdź state w odpowiedzi.
403	Odmowa Pundit (zwykle nie powinna wystąpić).
404	Brak takiej domeny lub wywołujący nie należy do konta będącego jej właścicielem.

27.12 Zgłoszone wiadomości

Zgłoszone wiadomości to podejrzane e-maile, które pracownicy oznaczyli — przekazane do skrzynki zgłoszeń konta (source: inbound_webhook) albo przesłane przez dodatek do Outlooka (source: outlook_addin). Poniższe punkty końcowe odczytu zwracają wyłącznie metadane (nadawca, temat, data odebrania, źródło, zgłaszający) — nigdy treści wiadomości, nagłówków ani załączników. Są ograniczone do kont, do których należy użytkownik wywołującego tokenu.

GET /accounts/:account_id/reported_messages

Wyświetla listę zgłoszonych wiadomości dla jednego konta, od najnowszych (sortowanie po received_at malejąco). Użyj go, aby zasilić kolejkę do weryfikacji lub zsynchronizować zgłoszenia z narzędziami SOC. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita). Musi być kontem, do którego należy użytkownik tokenu.
source	query	string	nie	Filtruj według źródła zgłoszenia. Jedna z wartości inbound_webhook, outlook_addin. Nieznana wartość zwraca 422. Pomiń, aby zwrócić wszystkie źródła.
limit	query	integer	nie	Rozmiar strony. Domyślnie 50; ograniczony do zakresu 1–500 (wartości <1 lub 0 przyjmują wartość 50, wartości >500 są ograniczane do 500).
page	query	integer	nie	Numer strony liczony od 1. Domyślnie 1; wartości poniżej 1 są traktowane jako 1. Przesunięcie obliczane jest jako (page - 1) * limit.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  "https://platform.phishspot.com/api/v1/accounts/11/reported_messages?source=outlook_addin&limit=25&page=1"

Odpowiedź 200 OK — tablica JSON obiektów metadanych zgłoszonych wiadomości (bez koperty). Każdy element zawiera następujące pola:

Pole	Typ	Opis
id	integer	Identyfikator zgłoszonej wiadomości.
account_id	integer	Identyfikator konta właściciela.
from_email	string	Adres nadawcy zgłoszonego e-maila.
from_name	string | null	Wyświetlana nazwa nadawcy, jeśli została przechwycona.
subject	string | null	Temat zgłoszonego e-maila.
message_id	string | null	Oryginalny Message-ID zgodny z RFC, jeśli został przechwycony.
source	string	Źródło zgłoszenia: inbound_webhook lub outlook_addin.
received_at	string (ISO 8601)	Kiedy oryginalny e-mail został odebrany.
created_at	string (ISO 8601)	Kiedy zgłoszenie zostało przyjęte do PhishSpot.
from_domain	string	Część domenowa adresu from_email zapisana małymi literami (tekst po @).
reporter_contact_email	string | null	E-mail odbiorcy z konta, który dokonał zgłoszenia (dopasowany po from_email); null, gdy nie istnieje pasujący odbiorca.

[
  {
    "id": 4821,
    "account_id": 11,
    "from_email": "billing@suspicious-invoice.example",
    "from_name": "Accounts Payable",
    "subject": "Overdue invoice — action required",
    "message_id": "<CADnf9x1@mail.suspicious-invoice.example>",
    "source": "outlook_addin",
    "received_at": "2026-05-28T09:14:00.000Z",
    "created_at": "2026-05-28T09:15:32.000Z",
    "from_domain": "suspicious-invoice.example",
    "reporter_contact_email": "jane.doe@acme.test"
  }
]

Kody statusu

Kod	Kiedy
200	Zwrócono zgłoszenia (tablica może być pusta).
403	Użytkownik tokenu jest autoryzowany, ale Pundit odmawia AccountPolicy#show? dla tego konta.
404	account_id nie jest kontem, do którego należy użytkownik tokenu (zwraca { "error": "Account not found" }).
422	source jest podane, ale nie jest jednym z prawidłowych źródeł (zwraca { "error": "Unknown source …; valid sources: inbound_webhook, outlook_addin." }).

GET /reported_messages/:id

Pobiera metadane pojedynczej zgłoszonej wiadomości. Jest to trasa płytka — przyjmuje identyfikator zgłoszenia bezpośrednio, bez segmentu ścieżki account_id. Izolacja kont jest wymuszana po stronie serwera: wyszukiwanie jest ograniczone do kont użytkownika tokenu, więc żądanie zgłoszenia z innego konta zwraca 404. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator zgłoszonej wiadomości (rep_… lub liczba całkowita).

Brak parametrów poza tokenem bearer i identyfikatorem w ścieżce.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/reported_messages/rep_4821

Odpowiedź 200 OK — pojedynczy obiekt metadanych zgłoszonej wiadomości z tymi samymi polami co jeden element tablicy indeksu:

Pole	Typ	Opis
id	integer	Identyfikator zgłoszonej wiadomości.
account_id	integer	Identyfikator konta właściciela.
from_email	string	Adres nadawcy zgłoszonego e-maila.
from_name	string | null	Wyświetlana nazwa nadawcy, jeśli została przechwycona.
subject	string | null	Temat zgłoszonego e-maila.
message_id	string | null	Oryginalny Message-ID zgodny z RFC, jeśli został przechwycony.
source	string	Źródło zgłoszenia: inbound_webhook lub outlook_addin.
received_at	string (ISO 8601)	Kiedy oryginalny e-mail został odebrany.
created_at	string (ISO 8601)	Kiedy zgłoszenie zostało przyjęte do PhishSpot.
from_domain	string	Część domenowa adresu from_email zapisana małymi literami.
reporter_contact_email	string | null	E-mail pasującego odbiorcy z konta lub null.

{
  "id": 4821,
  "account_id": 11,
  "from_email": "billing@suspicious-invoice.example",
  "from_name": "Accounts Payable",
  "subject": "Overdue invoice — action required",
  "message_id": "<CADnf9x1@mail.suspicious-invoice.example>",
  "source": "outlook_addin",
  "received_at": "2026-05-28T09:14:00.000Z",
  "created_at": "2026-05-28T09:15:32.000Z",
  "from_domain": "suspicious-invoice.example",
  "reporter_contact_email": "jane.doe@acme.test"
}

Kody statusu

Kod	Kiedy
200	Zgłoszenie zostało znalezione i zwrócone.
404	Nie istnieje zgłoszenie o tym identyfikatorze w obrębie kont użytkownika tokenu (zwraca { "error": "Resource not found" }).

POST /accounts/:account_id/reported_messages

Tylko dodatek. Przyjmuje nowo zgłoszoną wiadomość z dodatku do Outlooka. Ten punkt końcowy nie używa zwykłego tokenu bearer API ani Pundita — wymaga tokenu uprawnień dodatku (reported_messages:create), którego przypięty account_id odpowiada :account_id w adresie URL. Standardowe integracje go nie wywołują; do odczytu służą dwa powyższe punkty końcowe. Treść jest opakowana w obiekt reported_message (dozwolone klucze: from_email, from_name, subject, plain_body, html_body, received_at, message_id, headers oraz tablica attachments), a pomyślne wywołanie zwraca 201 Created z { "id": "rep_…", "url": "…" }. Niezgodność uprawnień/konta zwraca 403; błędy walidacji zwracają 422.

Notatka

Proces przesyłania z dodatku (uprawnienia tokenu, parowanie i pełny kształt żądania) jest opisany osobno w rozdziale Zgłoszone wiadomości (przyjmowanie z dodatku). Do każdej integracji raportującej lub weryfikacyjnej używaj powyższych punktów końcowych odczytu.

Kody statusu

Kod	Kiedy
201	Zgłoszenie zostało utworzone.
403	Token nie ma uprawnienia reported_messages:create albo jego przypięty account_id nie odpowiada adresowi URL.
404	account_id nie odpowiada istniejącemu kontu (zwraca { "error": "Account not found" }).
422	Usługa przyjmowania odrzuciła ładunek (zwraca { "error": "…" }).

27.13 Biblioteka mediów

Biblioteka mediów przechowuje hostowane pliki graficzne i CSS dla konta. Prześlij plik raz, a następnie odwołuj się do zwróconego url w treści HTML wiadomości kampanii, na stronach docelowych i w szablonach. Zawsze osadzaj hostowany url — klienty pocztowe (Gmail, Outlook) usuwają wbudowane identyfikatory URI data:, więc obrazy osadzone jako base64 nie zostaną wyświetlone.

Dozwolone typy zawartości: image/png, image/jpg, image/jpeg, image/gif, image/svg+xml oraz text/css. Maksymalny rozmiar pliku to 5 MB. Każdy element mediów musi mieć unikalną (bez rozróżniania wielkości liter) name w obrębie swojego konta.

Wszystkie punkty końcowe mediów mogą być używane przez dowolnego członka konta (bez ograniczenia do roli admin/edytor). Punkty końcowe kolekcji (index, create) są zagnieżdżone pod kontem; punkty końcowe pojedynczego elementu (show, update, destroy) są płytkie (/media/:id) i rozpoznają tylko media należące do jednego z kont użytkownika tokenu — wszystko inne zwraca 404.

GET /accounts/:account_id/media

Wyświetla wszystkie elementy mediów dla konta, od najnowszego. Użyj go, aby znaleźć hostowany url pliku przed osadzeniem go w kampanii. Uwierzytelnianie: bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita).

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/accounts/11/media

Odpowiedź 200 OK — tablica JSON obiektów mediów (każdy ma kształt opisany poniżej).

Pole	Typ	Opis
id	integer	Identyfikator elementu mediów.
account_id	integer	Identyfikator konta będącego właścicielem.
name	string	Nazwa wyświetlana (unikalna w obrębie konta, bez rozróżniania wielkości liter).
created_at	string	Znacznik czasu ISO 8601.
updated_at	string	Znacznik czasu ISO 8601.
url	string|null	Adres URL hostowanego pliku (ścieżka względna); osadź go w HTML. null, jeśli żaden plik nie jest dołączony.
filename	string|null	Oryginalna nazwa przesłanego pliku.
content_type	string|null	Typ MIME, np. image/png.

[
  {
    "id": 42,
    "account_id": 11,
    "name": "phishing-logo",
    "created_at": "2026-06-02T10:15:00.000Z",
    "updated_at": "2026-06-02T10:15:00.000Z",
    "url": "/rails/active_storage/blobs/redirect/eyJfcmFpbHMi.../phishing-logo.png",
    "filename": "phishing-logo.png",
    "content_type": "image/png"
  }
]

Kody statusu

Kod	Kiedy
200	Zwrócono listę mediów.
404	account_id nie jest jednym z kont użytkownika tokenu.

POST /accounts/:account_id/media

Przesyła nowy plik do biblioteki mediów konta. To żądanie jest typu multipart/form-data, a nie JSON — plik jest wysyłany jako pole formularza, a nie jako ciąg base64 w treści JSON. Uwierzytelnianie: bearer; rola: dowolny członek konta.

Parametry (pola formularza opakowane w obiekt medium[...])

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Identyfikator konta (acct_… lub liczba całkowita).
medium[name]	body	string	tak	Nazwa wyświetlana; musi być unikalna (bez rozróżniania wielkości liter) w obrębie konta.
medium[attachment]	body	file	tak	Plik do przesłania. Musi być jednym z image/png, image/jpg, image/jpeg, image/gif, image/svg+xml, text/css oraz ≤ 5 MB.

Żądanie

Zwróć uwagę na flagi -F (multipart). Nie ustawiaj Content-Type: application/json; pozwól curl ustawić granicę multipart. Plik jest odczytywany z dysku za pomocą @/path.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -F "medium[name]=phishing-logo" \
  -F "medium[attachment]=@./phishing-logo.png;type=image/png" \
  https://platform.phishspot.com/api/v1/accounts/11/media

Odpowiedź 201 Created — utworzony obiekt mediów (taki sam kształt jak element listy powyżej).

Pole	Typ	Opis
id	integer	Identyfikator nowego elementu mediów.
account_id	integer	Identyfikator konta będącego właścicielem.
name	string	Nazwa wyświetlana.
created_at	string	Znacznik czasu ISO 8601.
updated_at	string	Znacznik czasu ISO 8601.
url	string	Adres URL hostowanego pliku — osadź go w treści HTML kampanii.
filename	string	Zapisana nazwa pliku.
content_type	string	Typ MIME przesłanego pliku.

{
  "id": 42,
  "account_id": 11,
  "name": "phishing-logo",
  "created_at": "2026-06-02T10:15:00.000Z",
  "updated_at": "2026-06-02T10:15:00.000Z",
  "url": "/rails/active_storage/blobs/redirect/eyJfcmFpbHMi.../phishing-logo.png",
  "filename": "phishing-logo.png",
  "content_type": "image/png"
}

Wskazówka

Poprzedź zwrócony względny url hostem swojej platformy (https://platform.phishspot.com), aby uzyskać bezwzględny, osiągalny z zewnątrz adres URL do użycia w treści HTML wiadomości e-mail.

Kody statusu

Kod	Kiedy
201	Utworzono media.
404	account_id nie jest jednym z kont użytkownika tokenu.
422	Walidacja nie powiodła się — brakująca/pusta name, zduplikowana name w koncie, brakujący attachment, niedozwolony typ zawartości lub plik większy niż 5 MB. Treść: { "errors": { … } }.

Przykładowa treść 422 (brakujący załącznik):

{ "errors": { "attachment": ["can't be blank"] } }

GET /media/:id

Zwraca pojedynczy element mediów według identyfikatora. Rozpoznaje tylko media należące do jednego z kont użytkownika tokenu. Uwierzytelnianie: bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator elementu mediów (med_… lub liczba całkowita).

Brak parametrów poza tokenem bearer.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/media/42

Odpowiedź 200 OK — obiekt mediów (te same pola co w odpowiedzi POST powyżej).

{
  "id": 42,
  "account_id": 11,
  "name": "phishing-logo",
  "created_at": "2026-06-02T10:15:00.000Z",
  "updated_at": "2026-06-02T10:15:00.000Z",
  "url": "/rails/active_storage/blobs/redirect/eyJfcmFpbHMi.../phishing-logo.png",
  "filename": "phishing-logo.png",
  "content_type": "image/png"
}

Kody statusu

Kod	Kiedy
200	Zwrócono element mediów.
404	Żaden element mediów o tym identyfikatorze nie należy do jednego z kont użytkownika tokenu.

PATCH /media/:id

Aktualizuje element mediów. W praktyce tylko name ma znaczenie; można też ponownie przesłać plik, wysyłając nowy attachment (multipart). Uwierzytelnianie: bearer; rola: dowolny członek konta.

Parametry (opakowane w obiekt medium[...])

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator elementu mediów (med_… lub liczba całkowita).
medium[name]	body	string	nie	Nowa nazwa wyświetlana; musi pozostać unikalna (bez rozróżniania wielkości liter) w obrębie konta.
medium[attachment]	body	file	nie	Plik zastępczy (wysyłany jako multipart). Te same ograniczenia typu zawartości i 5 MB co przy tworzeniu.

Żądanie

Zmianę samej nazwy można wysłać jako JSON:

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "medium": { "name": "phishing-logo-v2" } }' \
  https://platform.phishspot.com/api/v1/media/42

Aby zastąpić plik, wyślij zamiast tego multipart (-F "medium[attachment]=@./new.png;type=image/png").

Odpowiedź 200 OK — zaktualizowany obiekt mediów (te same pola co w show).

{
  "id": 42,
  "account_id": 11,
  "name": "phishing-logo-v2",
  "created_at": "2026-06-02T10:15:00.000Z",
  "updated_at": "2026-06-02T11:02:00.000Z",
  "url": "/rails/active_storage/blobs/redirect/eyJfcmFpbHMi.../phishing-logo.png",
  "filename": "phishing-logo.png",
  "content_type": "image/png"
}

Kody statusu

Kod	Kiedy
200	Zaktualizowano media.
404	Żaden element mediów o tym identyfikatorze nie należy do jednego z kont użytkownika tokenu.
422	Walidacja nie powiodła się — pusta name, zduplikowana name lub (przy zastępowaniu pliku) niedozwolony typ zawartości / powyżej 5 MB. Treść: { "errors": { … } }.

DELETE /media/:id

Trwale usuwa element mediów i dołączony do niego plik. Każda treść HTML kampanii nadal odwołująca się do url pliku przestanie działać, więc najpierw usuń odwołania. Uwierzytelnianie: bearer; rola: dowolny członek konta.

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Identyfikator elementu mediów (med_… lub liczba całkowita).

Brak parametrów poza tokenem bearer.

Żądanie

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/media/42

Odpowiedź 204 No Content — pusta treść.

Kody statusu

Kod	Kiedy
204	Usunięto media.
404	Żaden element mediów o tym identyfikatorze nie należy do jednego z kont użytkownika tokenu.

27.14 Webhooki

Zarządzaj subskrypcjami wychodzących webhooków i przeglądaj zdarzenia, które PhishSpot wygenerował dla konta. Punkt końcowy to adres URL, który rejestrujesz, aby otrzymywać podpisane żądania HTTP POST; zdarzenie to niezmienny zapis czegoś, co się wydarzyło (utworzono kampanię, usunięto odbiorcę itp.), rozsyłany do każdego włączonego punktu końcowego subskrybującego jego typ. Mechanikę dostarczania — harmonogram ponawiania, nagłówek HMAC X-Webhook-Signature oraz sposób jego weryfikacji za pomocą signing_secret — opisano w Dostarczanie webhooków i podpisy.

Punkty końcowe są globalne dla konta, a nie ograniczone do tenanta

Webhook::Endpoint i Webhook::Event nie są rekordami wielodostępowymi, dlatego płytkie trasy (/webhooks/endpoints/:id, /webhooks/events/:id) przyjmują bezpośrednio id rekordu i nie zawierają account_id w ścieżce. Autoryzacja jest nadal egzekwowana dla każdego rekordu: musisz być członkiem konta będącego właścicielem punktu końcowego/zdarzenia, w przeciwnym razie otrzymasz 403. Segment :id akceptuje zarówno id z prefiksem (whep_…), jak i surową liczbę całkowitą.

Dostępne wartości event_type_ids. Punkt końcowy subskrybuje, wymieniając jeden lub więcej z tych ciągów. Te same ciągi pojawiają się jako event_type w emitowanych zdarzeniach:

Typ zdarzenia	Wyzwalane gdy
campaign.created	Utworzono kampanię.
campaign.updated	Zaktualizowano kampanię.
campaign.deleted	Usunięto kampanię.
contact.created	Dodano odbiorcę.
contact.updated	Zaktualizowano odbiorcę.
contact.deleted	Usunięto odbiorcę.
deliverable.created	Utworzono pozycję dostarczenia kampanii (wysyłka do jednego odbiorcy).
deliverable.updated	Pozycja dostarczenia zmienia stan (wysłana, otwarta, kliknięta itp.).
spam_whitelist.updated	Zmienia się migawka listy spamu/dozwolonych nadawców konta.

GET /accounts/:account_id/webhooks/endpoints

Wyświetla każdy punkt końcowy webhooka zarejestrowany na koncie, od najnowszych. Użyj tego, aby wyrenderować interfejs zarządzania lub uzgodnić lokalną konfigurację. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Id konta (acct_… lub liczba całkowita).

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/accounts/11/webhooks/endpoints

Odpowiedź 200 OK — tablica JSON obiektów punktów końcowych. signing_secret jest pomijany w tym widoku listy (jest zwracany wyłącznie w widokach pojedynczego punktu końcowego).

Pole	Typ	Opis
id	integer	Id punktu końcowego. Segment ścieżki/widoku akceptuje również formę z prefiksem whep_….
account_id	integer	Id konta będącego właścicielem.
name	string	Czytelna etykieta punktu końcowego.
url	string	Docelowy adres URL, który otrzymuje żądania POST.
event_type_ids	array of string	Subskrybowane typy zdarzeń (zobacz tabelę powyżej).
enabled	boolean	Czy dostarczenia są obecnie wysyłane.
api_version	integer	Wersja schematu treści (obecnie 1).
created_at	string	Znacznik czasu ISO 8601.
updated_at	string	Znacznik czasu ISO 8601.
total_deliveries	integer	Liczba wszystkich rekordów dostarczenia dla tego punktu końcowego.
successful_deliveries	integer	Liczba dostarczeń w statusie delivered.
failed_deliveries	integer	Liczba dostarczeń w statusie failed.

[
  {
    "id": 42,
    "account_id": 11,
    "name": "Production listener",
    "url": "https://hooks.example.com/phishspot",
    "event_type_ids": ["campaign.created", "deliverable.updated"],
    "enabled": true,
    "api_version": 1,
    "created_at": "2026-05-30T09:14:22Z",
    "updated_at": "2026-06-01T12:03:10Z",
    "total_deliveries": 128,
    "successful_deliveries": 121,
    "failed_deliveries": 7
  }
]

Kody statusu

Kod	Kiedy
200	Zwrócono punkty końcowe (pusta tablica, jeśli brak).
403	Wywołujący nie jest członkiem account_id.
404	account_id nie istnieje lub wywołujący nie jest członkiem.

POST /accounts/:account_id/webhooks/endpoints

Rejestruje nowy punkt końcowy webhooka. Odpowiedź zawiera signing_secret dokładnie raz — zapisz go natychmiast, ponieważ jest potrzebny do weryfikacji podpisów dostarczeń i nigdy więcej nie jest pokazywany w całości, z wyjątkiem operacji show/update/toggle na tym samym punkcie końcowym. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola — wystarczy członkostwo w koncie).

Punkty końcowe startują wyłączone, chyba że wybierzesz inaczej

Nowo utworzony punkt końcowy domyślnie ma enabled: true w modelu, ale przekaż enabled: false, aby zarejestrować go jako uśpiony i włączyć go później za pomocą punktu końcowego toggle, gdy zweryfikujesz swój odbiornik. url jest walidowany pod kątem bezpieczeństwa: akceptowane są wyłącznie schematy http/https, a adresy URL wskazujące na localhost, 127.0.0.1, ::1, zakresy IP RFC 1918 / link-local / loopback / unique-local lub dowolny host *.phishspot.com są odrzucane z kodem 422.

Parametry

Parametry treści są opakowane w obiekt webhook_endpoint.

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Id konta (acct_… lub liczba całkowita).
webhook_endpoint.name	body	string	tak	Czytelna etykieta. Walidowana pod kątem obecności.
webhook_endpoint.url	body	string	tak	Docelowy adres URL. Musi być prawidłowym adresem URL http/https i przejść opisane powyżej kontrole bezpieczeństwa.
webhook_endpoint.event_type_ids	body	array of string	tak	Jeden lub więcej typów zdarzeń do subskrybowania (zobacz tabelę). Walidowane pod kątem obecności — wymagany co najmniej jeden.
webhook_endpoint.enabled	body	boolean	nie	Czy punkt końcowy ma startować jako włączony. Domyślnie true.

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
        "webhook_endpoint": {
          "name": "Production listener",
          "url": "https://hooks.example.com/phishspot",
          "event_type_ids": ["campaign.created", "deliverable.updated"],
          "enabled": false
        }
      }' \
  https://platform.phishspot.com/api/v1/accounts/11/webhooks/endpoints

Odpowiedź 201 Created — utworzony punkt końcowy, w tym jednorazowy signing_secret. Pola są takie same jak w widoku listy, plus signing_secret:

Pole	Typ	Opis
id	integer	Id punktu końcowego.
account_id	integer	Id konta będącego właścicielem.
name	string	Czytelna etykieta.
url	string	Docelowy adres URL (przycięty/znormalizowany).
event_type_ids	array of string	Subskrybowane typy zdarzeń.
enabled	boolean	Czy dostarczenia są aktywne.
api_version	integer	Wersja schematu treści (1).
created_at	string	Znacznik czasu ISO 8601.
updated_at	string	Znacznik czasu ISO 8601.
signing_secret	string	64-znakowy sekret HMAC w formacie hex. Zwracany tutaj — zapisz go teraz.
total_deliveries	integer	0 dla nowego punktu końcowego.
successful_deliveries	integer	0 dla nowego punktu końcowego.
failed_deliveries	integer	0 dla nowego punktu końcowego.

{
  "id": 42,
  "account_id": 11,
  "name": "Production listener",
  "url": "https://hooks.example.com/phishspot",
  "event_type_ids": ["campaign.created", "deliverable.updated"],
  "enabled": false,
  "api_version": 1,
  "created_at": "2026-06-02T10:00:00Z",
  "updated_at": "2026-06-02T10:00:00Z",
  "signing_secret": "9f2c1e7b4a6d8f0c3e5a7b9d1f3c5e7a9b1d3f5c7e9a1b3d5f7c9e1a3b5d7f9c",
  "total_deliveries": 0,
  "successful_deliveries": 0,
  "failed_deliveries": 0
}

Kody statusu

Kod	Kiedy
201	Utworzono punkt końcowy.
403	Wywołujący nie jest członkiem account_id.
404	account_id nie istnieje lub wywołujący nie jest członkiem.
422	Walidacja nie powiodła się — brak name/url/event_type_ids, nieprawidłowy adres URL lub adres URL wskazujący na localhost / prywatny IP / host *.phishspot.com.

GET /webhooks/endpoints/:id

Pobiera pojedynczy punkt końcowy, w tym jego pełny signing_secret i statystyki dostarczeń z całego okresu. Użyj tego, aby ponownie odczytać sekret, jeśli go zgubisz, lub aby monitorować kondycję dostarczeń. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola — musisz być członkiem konta będącego właścicielem).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Id punktu końcowego (whep_… lub liczba całkowita).

Brak parametrów poza tokenem bearer i id w ścieżce.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/webhooks/endpoints/whep_8xk2p9

Odpowiedź 200 OK — jeden obiekt punktu końcowego z tymi samymi polami co odpowiedź na tworzenie (zawiera signing_secret).

{
  "id": 42,
  "account_id": 11,
  "name": "Production listener",
  "url": "https://hooks.example.com/phishspot",
  "event_type_ids": ["campaign.created", "deliverable.updated"],
  "enabled": true,
  "api_version": 1,
  "created_at": "2026-05-30T09:14:22Z",
  "updated_at": "2026-06-01T12:03:10Z",
  "signing_secret": "9f2c1e7b4a6d8f0c3e5a7b9d1f3c5e7a9b1d3f5c7e9a1b3d5f7c9e1a3b5d7f9c",
  "total_deliveries": 128,
  "successful_deliveries": 121,
  "failed_deliveries": 7
}

Kody statusu

Kod	Kiedy
200	Zwrócono punkt końcowy.
403	Wywołujący nie jest członkiem konta będącego właścicielem punktu końcowego.
404	Brak punktu końcowego o tym id.

PATCH /webhooks/endpoints/:id

Aktualizuje nazwę punktu końcowego, adres URL, subskrybowane typy zdarzeń lub flagę włączenia. signing_secret nie jest regenerowany i nie może zostać zmieniony za pomocą tego wywołania. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola — musisz być członkiem konta będącego właścicielem).

Parametry

Parametry treści są opakowane w obiekt webhook_endpoint; wyślij tylko te pola, które chcesz zmienić.

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Id punktu końcowego (whep_… lub liczba całkowita).
webhook_endpoint.name	body	string	nie	Nowa etykieta. Nie może zostać wyczyszczona (walidowana pod kątem obecności).
webhook_endpoint.url	body	string	nie	Nowy docelowy adres URL. Ponownie walidowany pod kątem bezpieczeństwa (te same reguły co przy tworzeniu).
webhook_endpoint.event_type_ids	body	array of string	nie	Zastępczy zestaw subskrybowanych typów zdarzeń. Nie może zostać opróżniony.
webhook_endpoint.enabled	body	boolean	nie	Włącz/wyłącz.

Żądanie

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
        "webhook_endpoint": {
          "event_type_ids": ["campaign.created", "campaign.updated", "campaign.deleted"]
        }
      }' \
  https://platform.phishspot.com/api/v1/webhooks/endpoints/whep_8xk2p9

Odpowiedź 200 OK — zaktualizowany obiekt punktu końcowego (te same pola co show, w tym signing_secret).

{
  "id": 42,
  "account_id": 11,
  "name": "Production listener",
  "url": "https://hooks.example.com/phishspot",
  "event_type_ids": ["campaign.created", "campaign.updated", "campaign.deleted"],
  "enabled": true,
  "api_version": 1,
  "created_at": "2026-05-30T09:14:22Z",
  "updated_at": "2026-06-02T11:20:45Z",
  "signing_secret": "9f2c1e7b4a6d8f0c3e5a7b9d1f3c5e7a9b1d3f5c7e9a1b3d5f7c9e1a3b5d7f9c",
  "total_deliveries": 128,
  "successful_deliveries": 121,
  "failed_deliveries": 7
}

Kody statusu

Kod	Kiedy
200	Zaktualizowano punkt końcowy.
403	Wywołujący nie jest członkiem konta będącego właścicielem.
404	Brak punktu końcowego o tym id.
422	Walidacja nie powiodła się — pusty name, pusty event_type_ids lub nieprawidłowy/niebezpieczny url.

DELETE /webhooks/endpoints/:id

Trwale usuwa punkt końcowy i wszystkie jego rekordy dostarczenia. Same zdarzenia nie są usuwane. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola — musisz być członkiem konta będącego właścicielem).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Id punktu końcowego (whep_… lub liczba całkowita).

Brak parametrów poza tokenem bearer i id w ścieżce.

Żądanie

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/webhooks/endpoints/whep_8xk2p9

Odpowiedź 204 No Content — pusta treść w przypadku powodzenia.

Kody statusu

Kod	Kiedy
204	Usunięto punkt końcowy.
403	Wywołujący nie jest członkiem konta będącego właścicielem.
404	Brak punktu końcowego o tym id.

POST /webhooks/endpoints/:id/toggle

Przełącza flagę enabled punktu końcowego — włącza wyłączony punkt końcowy lub wyłącza włączony. Użyj tego, aby wstrzymać/wznowić dostarczenia bez usuwania punktu końcowego ani utraty jego sekretu. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola — musisz być członkiem konta będącego właścicielem).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Id punktu końcowego (whep_… lub liczba całkowita).

Brak parametrów poza tokenem bearer i id w ścieżce — nowy stan jest wyprowadzany z bieżącego.

Żądanie

curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/webhooks/endpoints/whep_8xk2p9/toggle

Odpowiedź 200 OK — punkt końcowy z przełączoną wartością enabled (te same pola co show, w tym signing_secret).

{
  "id": 42,
  "account_id": 11,
  "name": "Production listener",
  "url": "https://hooks.example.com/phishspot",
  "event_type_ids": ["campaign.created", "deliverable.updated"],
  "enabled": false,
  "api_version": 1,
  "created_at": "2026-05-30T09:14:22Z",
  "updated_at": "2026-06-02T11:30:00Z",
  "signing_secret": "9f2c1e7b4a6d8f0c3e5a7b9d1f3c5e7a9b1d3f5c7e9a1b3d5f7c9e1a3b5d7f9c",
  "total_deliveries": 128,
  "successful_deliveries": 121,
  "failed_deliveries": 7
}

Kody statusu

Kod	Kiedy
200	Stan przełączony; zwrócono zaktualizowany punkt końcowy.
403	Wywołujący nie jest członkiem konta będącego właścicielem.
404	Brak punktu końcowego o tym id.

GET /accounts/:account_id/webhooks/events

Wyświetla zdarzenia wygenerowane dla konta, od najnowszych, ze stronicowaniem. Każde zdarzenie rejestruje, co się wydarzyło, i dołącza liczby dostarczeń przypadające na zdarzenie. Użyj tego, aby skontrolować, co PhishSpot próbował wysłać, niezależnie od jakiegokolwiek pojedynczego punktu końcowego. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
account_id	path	string	tak	Id konta (acct_… lub liczba całkowita).
event_type	query	string	nie	Filtruj do pojedynczego typu zdarzenia (np. deliverable.updated). Pomiń, aby uwzględnić wszystkie typy.
page	query	integer	nie	Numer strony. Domyślnie 1.
per_page	query	integer	nie	Liczba elementów na stronę. Domyślnie 50.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  "https://platform.phishspot.com/api/v1/accounts/11/webhooks/events?event_type=deliverable.updated&page=1&per_page=50"

Odpowiedź 200 OK — tablica JSON obiektów zdarzeń.

Pole	Typ	Opis
id	integer	Id zdarzenia. Segment widoku akceptuje również formę z prefiksem/surową.
account_id	integer	Id konta będącego właścicielem.
subject_id	integer	Id rekordu, którego dotyczy zdarzenie (kampania, odbiorca, pozycja dostarczenia, …).
subject_type	string	Nazwa klasy podmiotu (np. Campaign, Contact, Deliverable).
event_type	string	Jeden z typów zdarzeń z tabeli powyżej.
api_version	integer	Wersja schematu treści (1).
uuid	string	Stabilne unikalne id tego zdarzenia (używane również jako payload.id).
created_at	string	Znacznik czasu ISO 8601.
updated_at	string	Znacznik czasu ISO 8601.
data	object	Dane specyficzne dla zdarzenia opisujące zmianę (kształt różni się w zależności od event_type).
payload	object	Dokładna treść JSON dostarczana do punktów końcowych (zobacz poniżej).
deliveries	object	Liczby dostarczeń przypadające na zdarzenie.
deliveries.total	integer	Wszystkie rekordy dostarczenia dla tego zdarzenia.
deliveries.delivered	integer	Dostarczenia w statusie delivered.
deliveries.failed	integer	Dostarczenia w statusie failed.
deliveries.pending	integer	Dostarczenia w statusie pending.

Obiekt payload to dokładnie to, co otrzymują odbiorniki, o następującym kształcie: id (uuid zdarzenia), type (event_type), created_at (ISO 8601), data (takie samo jak data na najwyższym poziomie) oraz api_version.

[
  {
    "id": 9001,
    "account_id": 11,
    "subject_id": 305,
    "subject_type": "Deliverable",
    "event_type": "deliverable.updated",
    "api_version": 1,
    "uuid": "3f1c8a02-7d4e-4b9a-9c1e-2a6b5d8f0e11",
    "created_at": "2026-06-02T09:58:12Z",
    "updated_at": "2026-06-02T09:58:12Z",
    "data": { "deliverable_id": "dlv_4k2m", "state": "clicked" },
    "payload": {
      "id": "3f1c8a02-7d4e-4b9a-9c1e-2a6b5d8f0e11",
      "type": "deliverable.updated",
      "created_at": "2026-06-02T09:58:12Z",
      "data": { "deliverable_id": "dlv_4k2m", "state": "clicked" },
      "api_version": 1
    },
    "deliveries": { "total": 2, "delivered": 1, "failed": 0, "pending": 1 }
  }
]

Kody statusu

Kod	Kiedy
200	Zwrócono zdarzenia (pusta tablica, jeśli żadne nie pasuje).
403	Wywołujący nie jest członkiem account_id.
404	account_id nie istnieje lub wywołujący nie jest członkiem.

GET /webhooks/events/:id

Pobiera pojedyncze zdarzenie po id, w tym jego pełne data, dostarczony payload oraz liczby dostarczeń. Użyj tego, aby sprawdzić dokładnie, co zostało wysłane w przypadku jednego wystąpienia. Uwierzytelnianie: Bearer; rola: odczyt (dowolna rola — musisz być członkiem konta będącego właścicielem).

Parametry

Nazwa	Gdzie	Typ	Wymagane	Opis
id	path	string	tak	Id zdarzenia (z prefiksem lub surowa liczba całkowita).

Brak parametrów poza tokenem bearer i id w ścieżce.

Żądanie

curl -H "Authorization: Bearer $TOKEN" \
  https://platform.phishspot.com/api/v1/webhooks/events/9001

Odpowiedź 200 OK — jeden obiekt zdarzenia, o identycznym kształcie jak pojedynczy element tablicy indeksu powyżej.

{
  "id": 9001,
  "account_id": 11,
  "subject_id": 305,
  "subject_type": "Deliverable",
  "event_type": "deliverable.updated",
  "api_version": 1,
  "uuid": "3f1c8a02-7d4e-4b9a-9c1e-2a6b5d8f0e11",
  "created_at": "2026-06-02T09:58:12Z",
  "updated_at": "2026-06-02T09:58:12Z",
  "data": { "deliverable_id": "dlv_4k2m", "state": "clicked" },
  "payload": {
    "id": "3f1c8a02-7d4e-4b9a-9c1e-2a6b5d8f0e11",
    "type": "deliverable.updated",
    "created_at": "2026-06-02T09:58:12Z",
    "data": { "deliverable_id": "dlv_4k2m", "state": "clicked" },
    "api_version": 1
  },
  "deliveries": { "total": 2, "delivered": 1, "failed": 0, "pending": 1 }
}

Kody statusu

Kod	Kiedy
200	Zwrócono zdarzenie.
403	Wywołujący nie jest członkiem konta będącego właścicielem zdarzenia.
404	Brak zdarzenia o tym id.

27.15 Wersja dodatku Outlook (publiczna)

GET /outlook/version

Zwraca metadane bieżącego wydania dodatku Outlook. Nie wymaga uwierzytelniania. Buforowane na ~5 minut.

Parametry: brak.

curl https://platform.phishspot.com/api/v1/outlook/version

Odpowiedź 200 OK

Pole	Typ	Opis
latest	string	Najnowsza wersja dodatku.
min_supported	string	Najstarsza wersja, która nadal może być uruchamiana.
bundle_filename	string	Nazwa pliku pakietu sideload.
bundle_sha256	string	SHA-256 pakietu.

{ "latest": "1.1.0", "min_supported": "1.0.0", "bundle_filename": "phishspot-outlook-sideload-v1.1.0.zip", "bundle_sha256": "…" }

Przydatne dla narzędzi inwentaryzacyjnych weryfikujących, którą wersję dodatku powinny uruchamiać Twoje urządzenia. Zobacz Rozdział 20.

27.16 Pobieranie białej listy antyspamowej (osobny system tokenów)

Samoobsługowy URL dla administratora poczty z Rozdziału 22 korzysta z innego schematu — 64-znakowego tokenu osadzonego w ścieżce, bez nagłówka Authorization:

GET /integrations/spam/:token/:format

Nazwa	Gdzie	Typ	Wymagane	Opis
token	path	string (64 hex)	tak	Token białej listy z panelu Integracje.
format	path	enum	nie	Jeden z txt (domyślny), json, csv, md, microsoft365, google-workspace, mimecast, proofpoint, postfix, spamassassin.

Posiadanie URL-a jest jedynym poświadczeniem — traktuj go jak hasło i rotuj z poziomu Ustawienia konta → Integracje → Biała lista filtra antyspamowego, jeśli wycieknie.

27.17 Limity zapytań

Throttling Rack::Attack obowiązuje per źródłowe IP dla punktów końcowych bez uwierzytelniania oraz per token dla tych uwierzytelnionych:

Powierzchnia	Limit
Generowanie kodu parowania Outlook	10 / minutę / IP
Odpytywanie kodu parowania Outlook	60 / minutę / IP
Przyjmowanie zgłoszeń phishingowych (dodatek)	30 / minutę / IP
Pobieranie białej listy antyspamowej	60 / minutę / token

Przekroczenie limitu zwraca 429 Too Many Requests z nagłówkiem Retry-After. Ogólne uwierzytelnione API nie podlega innym limitom zapytań poza ochroną przed nadużyciami na poziomie infrastruktury; utrzymuj użycie poniżej kilkuset żądań/minutę/token lub skontaktuj się z nami, aby je zwiększyć.

27.18 Odsyłacze

• Tworzenie i zarządzanie tokenami API w panelu administracyjnym: Rozdział 14 Tokeny API.
• Sterowanie tymi samymi funkcjami z klienta AI za pomocą języka naturalnego: Rozdział 29 Serwer MCP.
• Odpowiednik tych punktów końcowych oparty na powiadomieniach push zamiast odpytywania: Rozdział 26 Webhooki.
• Punkt końcowy białej listy antyspamowej w kontekście: Rozdział 22 Biała lista filtra antyspamowego.
• Dodatek Outlook korzystający z outlook/version: Rozdział 20 Dodatek Outlook.