Przejdź do głównej zawartości

API

OctaForms udostępnia HTTP API do zarządzania formularzami i zgłoszeniami z Twojego serwera. Adresy w przykładach zaczynają się od https://app.octaforms.pl, podstaw adres swojej instancji.

Są dwie grupy endpointów:

  • Publiczne (/api/v1/public/...) bez uwierzytelniania, używa ich widget na stronie.
  • Zarządzające (/api/v1/admin/...) wymagają klucza API, to jest właściwe API integracyjne (formularze, pola, pobieranie zgłoszeń).

Endpointy /api/v1/admin/... wymagają klucza API. Prześlij go w nagłówku:

X-Api-Key: <twój-klucz>

Alternatywnie zadziała Authorization: Bearer <twój-klucz>.

Klucz tworzy administrator w panelu, w zakładce Klucze API: podaje nazwę (do czego klucz służy) i uprawnienia. Klucz jest pokazywany jeden raz, przy utworzeniu, więc od razu go skopiuj. Zgubionego klucza nie da się odzyskać: odbierz go w tej samej zakładce i utwórz nowy. Odebrany klucz przestaje działać od następnego zapytania, a lista pokazuje, kiedy każdy klucz był ostatnio użyty. Przy błędnym lub brakującym kluczu API zwraca 401 w formacie application/problem+json.

Odpowiedzi są w JSON. Błędy zwracane są jako application/problem+json (RFC 9457). Błąd walidacji to status 422 z listą violations:

{
"type": "about:blank",
"title": "Unprocessable Entity",
"status": 422,
"detail": "Validation failed.",
"violations": [
{ "field": "email", "message": "Email is required", "code": "required" }
]
}

violations pojawia się, gdy błąd da się przypisać do konkretnych pól. Przy błędzie struktury żądania (na przykład nieznany type pola przy tworzeniu formularza) cała informacja jest w detail, razem z nazwą pola, którego dotyczy, i listą dozwolonych wartości.

Najczęstsze statusy:

Status Znaczenie
401 brak lub błędny klucz API (endpointy admin)
404 formularz lub zgłoszenie nie istnieje
409 konflikt: np. nazwa formularza zajęta, formularz nieaktywny lub bez opublikowanej wersji
422 błąd walidacji (patrz violations)
429 przekroczony limit zapytań (endpoint publiczny)

POST /api/v1/admin/forms

Pola górnego poziomu: formName (wymagane), projectId (wymagane, identyfikator projektu z panelu), opcjonalnie submitLabel, thankYouPageUrl, thankYou ({title, text}) oraz inputs (pola formularza).

thankYouPageUrl przyjmuje też placeholdery wypełniane wartościami ze zgłoszenia, np. https://twoja-strona.pl/dziekujemy?f={form_id}. Zasady i ostrzeżenie o danych osobowych opisuje Osadzanie.

{
"formName": "Formularz kontaktowy",
"projectId": "0193aaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"submitLabel": "Wyślij",
"thankYouPageUrl": "https://twoja-strona.pl/dziekujemy",
"thankYou": { "title": "Dziękujemy!", "text": "Odezwiemy się wkrótce." },
"inputs": {
"name": {
"type": "text",
"options": {},
"rules": [
{ "rule": "required", "errorMessage": "Podaj imię" },
{ "rule": "max:120", "errorMessage": "Imię jest za długie" }
]
},
"email": {
"type": "email",
"options": {},
"rules": [
{ "rule": "required", "errorMessage": "Podaj adres e-mail" }
]
},
"topic": {
"type": "select",
"options": { "choices": ["Sprzedaż", "Wsparcie", "Inne"] },
"rules": [
{ "rule": "required", "errorMessage": "Wybierz temat" }
]
},
"consent": {
"type": "checkbox",
"options": {},
"rules": [
{ "rule": "required", "errorMessage": "Zgoda jest wymagana" }
]
}
}
}

Sukces: 201 Created, ciało to identyfikator nowego formularza (JSON string). Zduplikowana nazwa formularza zwraca 409.

inputs to mapa, w której klucz jest nazwą pola (tej nazwy użyjesz potem w danych zgłoszenia i w payloadzie webhooka). Każdy wpis to obiekt z trzema kluczami: type, options, rules. Wszystkie trzy są wymagane (options może być {}, rules może być []).

Typy pól (type):

Typ Opis
text jednoliniowy tekst
textarea wieloliniowy tekst
email adres e-mail (reguła email dokładana automatycznie)
phone telefon (reguła phone dokładana automatycznie)
number liczba
select lista wyboru
radio przyciski jednokrotnego wyboru
checkboxes grupa pól zaznaczenia, wielokrotny wybór; wartość to lista zaznaczonych wariantów
checkbox pojedyncze pole zaznaczenia (np. zgoda)
date data
hidden pole ukryte

Dla select, radio i checkboxes warianty podajesz w options (np. {"choices": ["A", "B"]}). Ten sam wariant wpisany dwa razy (także różniący się tylko spacjami na brzegach) kończy się 422. Reguła bool_required dotyczy tylko checkbox, na innym typie pola to 422 (użyj required). checkboxes bez żadnego wariantu kończy się 422. options jest przekazywane do widgetu bez zmian.

W options są też opcjonalne ustawienia, które serwer sprawdza przy zapisie (błąd to 422 z opisem):

Klucz Znaczenie
default wartość na start: tekst dla pól tekstowych, jeden z wariantów dla select i radio, lista wariantów dla checkboxes, true dla checkbox
showIf pole pokazuje się dopiero po odpowiedzi w polu powyżej: {"field": "firma", "equals": "Tak"} albo dla checkbox {"field": "zgoda", "checked": false}; przy checkboxes equals znaczy „zaznaczono ten wariant”
hideLabel true chowa etykietę tylko wizualnie, czytniki ekranu, powiadomienia i panel dalej jej używają
description tylko checkbox: treść zgody pokazywana zamiast etykiety, najwyżej 2000 znaków. Link zapisujesz jako [tekst](adres), nowe linie zostają, innego formatowania nie ma
consent tylko checkbox: true zapisuje przy każdym zgłoszeniu dowód zgody RODO (patrz niżej), false mówi wprost, że to nie jest zgoda RODO. Na innym typie pola nic nie robi

showIf egzekwuje serwer: przed walidacją liczy, które pola były widoczne, a wartości ukrytych pól nie zapisuje i nie waliduje. Dzięki temu pole warunkowe może być required. Warunek musi wskazywać widoczne (nie hidden) pole powyżej, mieć dokładnie jedno z equals i checked, a equals przy polu z wariantami musi być jednym z nich. Przy sekcjach „powyżej” znaczy też powyżej na stronie: pole sterujące musi być w tej samej sekcji (wcześniej na jej liście fields) albo w sekcji wcześniejszej. Pola spoza sekcji stoją na końcu, w karcie bez tytułu.

Zgoda marketingowa to checkbox z treścią i linkiem do polityki prywatności:

"zgoda_marketing": {
"type": "checkbox",
"options": {
"label": "Zgoda marketingowa",
"description": "Wyrażam zgodę na kontakt w celach marketingowych zgodnie z [polityką prywatności](https://twoja-strona.pl/polityka).",
"consent": true
},
"rules": []
}

Widget pokazuje description zamiast etykiety. Link otwiera się w nowej karcie. Linkiem staje się tylko adres https://, http://, mailto: albo ścieżka na stronie z formularzem (np. /polityka), każdy inny (np. javascript:) zostaje zwykłym tekstem.

Przy consent: true każde zgłoszenie zapisuje dowód zgody dla każdego widocznego takiego checkboxa. Dowód widać w szczegółach zgłoszenia (GET /api/v1/admin/leads/{leadId}, pole lead.consents) i w panelu przy polu:

"consents": [
{
"field": "zgoda_marketing",
"label": "Wyrażam zgodę na kontakt w celach marketingowych zgodnie z [polityką prywatności](https://twoja-strona.pl/polityka).",
"value": true,
"ts": "2026-10-14T09:14:03+00:00"
}
]
  • label to treść, którą osoba widziała: description, a gdy jej nie ma, etykieta. Serwer bierze ją z opublikowanej wersji formularza, nigdy z wysłanego zgłoszenia.
  • value to odpowiedź. Odmowa (false) też jest zapisywana.
  • ts to czas zgłoszenia w UTC.
  • Checkbox ukryty warunkiem showIf nie ma wpisu, bo osoba go nie widziała.
  • Zgłoszenie bez takiej zgody ma consents: null.

Flagi nie wywnioskujemy z required: „potwierdzam, że dane są poprawne” jest wymagane i niczego nie dowodzi, a zgoda marketingowa zwykle jest opcjonalna. Dowód nie trafia do webhooka ani do e-maila. Znika razem ze zgłoszeniem (usunięcie, retencja).

Długi formularz można podzielić na karty. Obok inputs przekazujesz:

"sections": [
{ "title": "Dane firmy", "text": "Kilka pytań o działalność.", "fields": ["firma", "nip"] },
{ "title": "Kontakt", "fields": ["email"], "note": "Odpowiadamy w ciągu doby." }
],
"layout": "steps"
  • title, text i note są opcjonalne. fields to nazwy pól, każde pole najwyżej w jednej sekcji, bez pól hidden. Pola, których żadna sekcja nie wymienia, pokazują się na końcu w karcie bez tytułu.
  • Sekcje to wyłącznie układ: zapis leada, webhook i eksport widzą płaską listę pól.
  • layout: null (domyślnie) pokazuje wszystkie karty jedna pod drugą z jednym przyciskiem wysyłki, "steps" pokazuje je po jednej, z przyciskami Wstecz i Dalej. "steps" wymaga sekcji.
  • Edycja formularza zastępuje całą definicję, więc pominięcie sections usuwa sekcje.

Reguły (rules): lista obiektów { "rule": ..., "errorMessage": ... }. errorMessage musi mieć co najmniej 3 znaki. Obsługiwane reguły:

Reguła Znaczenie
required wartość wymagana
email poprawny e-mail
phone poprawny telefon
numeric wartość liczbowa
min:<n> długość tekstu ≥ n, a na polu z regułą numeric wartość ≥ n
max:<n> długość tekstu ≤ n, a na polu z regułą numeric wartość ≤ n
nip polski NIP
postCodePL polski kod pocztowy
minChecked:<n> tylko checkboxes: zaznaczono co najmniej n wariantów
maxChecked:<n> tylko checkboxes: zaznaczono najwyżej n wariantów

Przy długości n to liczba całkowita od 0. Na polu z regułą numeric n może być ujemne i mieć część dziesiętną po kropce (min:-10, max:2.5). Plus, sama część dziesiętna (.5), zapis wykładniczy (1e3) i przecinek kończą się 422.

Pole checkboxes przyjmuje wyłącznie required (co najmniej jeden zaznaczony wariant), minChecked i maxChecked. Wariant spoza listy w zgłoszeniu kończy się błędem in, a wartość, która nie jest listą wariantów, błędem invalid. Pojedynczy checkbox z wartością spoza zbioru true/false (i ich zapisów tekstowych, patrz własny frontend) też kończy się błędem invalid.

Nowy lub zmieniony formularz trzeba opublikować, żeby widget mógł go renderować:

  • POST /api/v1/admin/forms/{formId}/publish publikuje wersję, zwraca 201 { "version": <n>, "created": true }. Publikacja jest idempotentna: jeśli od ostatniej publikacji nic się w definicji nie zmieniło, nowa wersja nie powstaje, a odpowiedź to 200 { "version": <n>, "created": false } z numerem wersji, która nadal działa.
  • POST /api/v1/admin/forms/{formId}/enable włącza formularz
  • POST /api/v1/admin/forms/{formId}/disable wyłącza formularz
  • PUT /api/v1/admin/forms/{formId} edytuje formularz (to samo ciało co przy tworzeniu)
  • DELETE /api/v1/admin/forms/{formId} usuwa formularz (204)
  • GET /api/v1/admin/forms lista z paginacją. Parametry zapytania: limit (domyślnie 25), offset (domyślnie 0), formName, projectId, status (bool, domyślnie true). Każdy formularz niesie notifications.email[] i notifications.sms[]. Wpis e-mail ma recipients: { direct: [], cc: [], bcc: [] } w tym samym kształcie co w odpowiedzi pojedynczego formularza, plus replyTo i status (ACTIVE albo PAUSED). Wpis SMS ma recipient i status. Listing celowo pomija to, czego lista nie potrzebuje: szablony wiadomości, sender oraz anonymization znajdziesz wyłącznie w odpowiedzi pojedynczego formularza.
  • GET /api/v1/admin/forms/{formId} pojedynczy formularz.
  • GET /api/v1/public/forms/{formId} publiczna definicja opublikowanego formularza (bez klucza), tej używa widget. Zwraca m.in. nazwy pól, przydatne gdy budujesz własny frontend.
  • GET /api/v1/admin/leads lista zgłoszeń, od najnowszych. Parametry: limit (najwyżej 100), formName, projectId[], formId[], zakres dat from i to (dni włącznie, RRRR-MM-DD, oba albo żaden, najwyżej 1096 dni). Kolejne strony pobieraj kursorem: afterCreatedAt i afterId z ostatniego zgłoszenia poprzedniej strony. Kursor kosztuje tyle samo na każdej stronie; offset dalej działa, ale głęboka strona jest z nim coraz droższa i nie łączy się z kursorem.
  • GET /api/v1/admin/leads/{leadId} pojedyncze zgłoszenie wraz z historią dostaw (deliveries) i dowodem zgód RODO (lead.consents, patrz Zgody RODO).
  • DELETE /api/v1/admin/leads/{leadId} usuwa zgłoszenie (204).

POST /api/v1/admin/forms/{formId}/leads (z kluczem API) tworzy zgłoszenie bez zabezpieczeń antybotowych, do integracji server-to-server:

{
"fields": { "name": "Jan Kowalski", "email": "jan@example.com", "consent": true },
"meta": { "source": "import-crm" }
}

Wartości fields są walidowane regułami formularza, tak samo jak przy wysyłce publicznej. Klucze, które nie są polami opublikowanej wersji formularza, nie są zapisywane. Dane spoza formularza (źródło, identyfikator z CRM) wysyłaj w meta.

Widget na stronie wysyła zgłoszenia na POST /api/v1/public/forms/{formId}/leads. Zwykle nie robisz tego ręcznie, od tego jest osadzanie formularza. Jeśli jednak wysyłasz z własnego frontendu, pamiętaj o zabezpieczeniu antybotowym:

  1. Pobierz token: GET /api/v1/public/forms/{formId}/token zwraca { "token": "..." }.
  2. Wyślij zgłoszenie, dołączając antibot:
{
"fields": { "email": "jan@example.com", "name": "Jan" },
"meta": {},
"antibot": { "hp": "", "t": "<token-z-kroku-1>" }
}

Zasady: pole honeypot hp musi być puste, a od pobrania tokenu do wysyłki muszą minąć co najmniej 2 sekundy (parametr instancji ANTIBOT_MIN_SECONDS, widget czeka 3 sekundy na zapas). Token jest ważny 6 godzin. Sukces to 201 z { "redirectUrl": ... }. Przy wykryciu bota odpowiedź jest udawanym sukcesem o tym samym kształcie (201 i redirectUrl jak przy prawdziwym zapisie), a przy odrzuceniu tokenu 403.

Jeśli ponawiasz wysyłkę po zerwanym połączeniu, dołącz submissionId: losowy identyfikator (np. UUID, 16 do 64 znaków A-Z, a-z, 0-9 i -), jeden na jedno kliknięcie „Wyślij”, ten sam przy każdym ponowieniu.

{
"fields": { "email": "jan@example.com", "name": "Jan" },
"meta": {},
"antibot": { "hp": "", "t": "<token>" },
"submissionId": "0b6f8a52-91c4-4d3e-8f27-6a1c9e0d4b73"
}
  • Ponowienie z tym samym submissionId i tymi samymi polami nie tworzy drugiego zgłoszenia ani drugiego powiadomienia. Odpowiedź jest taka sama jak za pierwszym razem: 201 i ten sam redirectUrl.
  • Ten sam submissionId z innymi polami to nowe zgłoszenie. Nie używaj więc jednego identyfikatora dla wielu osób (np. identyfikatora sesji): każde zgłoszenie dostaje swój.
  • Brak submissionId albo wartość w innym formacie znaczy, że każde żądanie jest nowym zgłoszeniem.

Pojedynczy checkbox przyjmuje true albo false. Zaznaczenie to też 1, "1", "true", "on" i każdy inny niepusty tekst (np. "tak"), a brak zaznaczenia to false, 0, "0", "false", pusty tekst albo brak pola. Widoczny checkbox, którego nie wysłano, zapisuje się jako false. Grupę checkboxów (checkboxes) wysyłaj jako listę zaznaczonych wariantów, np. ["Montaż", "Serwis"].

meta przenosi kontekst zgłoszenia do webhooków i panelu. Wartości nie są walidowane, długi tekst jest przycinany, a nie odrzucany. Dwa klucze mają ustalone znaczenie:

Klucz Znaczenie
source źródło wizyty: etykieta, np. Google Ads, Google Organic, Facebook, albo adres strony odsyłającej; adres zapisywany bez części po ? i #; tylko tekst, najwyżej 500 znaków
referrer adres strony, z której przyszedł gość; zapisywany bez części po ? i #, najwyżej 500 znaków; przy wejściu bezpośrednim pusty tekst

source, który nie jest tekstem albo jest pusty, nie jest zapisywany. Tak samo referrer, który nie jest tekstem.

Na działającej instancji dostępny jest interaktywny podgląd API (Swagger UI):

  • GET /api/public/doc endpointy publiczne
  • GET /api/admin/doc endpointy zarządzające