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ń).
Uwierzytelnianie
Dział zatytułowany „Uwierzytelnianie”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.
Format odpowiedzi i błędów
Dział zatytułowany „Format odpowiedzi i błędów”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) |
Formularze
Dział zatytułowany „Formularze”Tworzenie formularza
Dział zatytułowany „Tworzenie formularza”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.
Pola (inputs)
Dział zatytułowany „Pola (inputs)”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.
Zgody RODO (description, consent)
Dział zatytułowany „Zgody RODO (description, consent)”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" }]labelto 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.valueto odpowiedź. Odmowa (false) też jest zapisywana.tsto czas zgłoszenia w UTC.- Checkbox ukryty warunkiem
showIfnie 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).
Sekcje i kroki (sections, layout)
Dział zatytułowany „Sekcje i kroki (sections, layout)”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,textinotesą opcjonalne.fieldsto nazwy pól, każde pole najwyżej w jednej sekcji, bez pólhidden. 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
sectionsusuwa 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.
Publikacja i stan formularza
Dział zatytułowany „Publikacja i stan formularza”Nowy lub zmieniony formularz trzeba opublikować, żeby widget mógł go renderować:
POST /api/v1/admin/forms/{formId}/publishpublikuje wersję, zwraca201{ "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ź to200{ "version": <n>, "created": false }z numerem wersji, która nadal działa.POST /api/v1/admin/forms/{formId}/enablewłącza formularzPOST /api/v1/admin/forms/{formId}/disablewyłącza formularzPUT /api/v1/admin/forms/{formId}edytuje formularz (to samo ciało co przy tworzeniu)DELETE /api/v1/admin/forms/{formId}usuwa formularz (204)
Odczyt formularzy
Dział zatytułowany „Odczyt formularzy”GET /api/v1/admin/formslista z paginacją. Parametry zapytania:limit(domyślnie 25),offset(domyślnie 0),formName,projectId,status(bool, domyślnietrue). Każdy formularz niesienotifications.email[]inotifications.sms[]. Wpis e-mail marecipients: { direct: [], cc: [], bcc: [] }w tym samym kształcie co w odpowiedzi pojedynczego formularza, plusreplyToistatus(ACTIVEalboPAUSED). Wpis SMS marecipientistatus. Listing celowo pomija to, czego lista nie potrzebuje: szablony wiadomości,senderorazanonymizationznajdziesz 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.
Zgłoszenia (leady)
Dział zatytułowany „Zgłoszenia (leady)”GET /api/v1/admin/leadslista zgłoszeń, od najnowszych. Parametry:limit(najwyżej 100),formName,projectId[],formId[], zakres datfromito(dni włącznie,RRRR-MM-DD, oba albo żaden, najwyżej 1096 dni). Kolejne strony pobieraj kursorem:afterCreatedAtiafterIdz ostatniego zgłoszenia poprzedniej strony. Kursor kosztuje tyle samo na każdej stronie;offsetdalej 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).
Tworzenie zgłoszenia z serwera
Dział zatytułowany „Tworzenie zgłoszenia z serwera”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.
Wysyłka publiczna (bez klucza)
Dział zatytułowany „Wysyłka publiczna (bez klucza)”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:
- Pobierz token:
GET /api/v1/public/forms/{formId}/tokenzwraca{ "token": "..." }. - 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.
Ponowienie wysyłki (submissionId)
Dział zatytułowany „Ponowienie wysyłki (submissionId)”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
submissionIdi tymi samymi polami nie tworzy drugiego zgłoszenia ani drugiego powiadomienia. Odpowiedź jest taka sama jak za pierwszym razem:201i ten samredirectUrl. - Ten sam
submissionIdz 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
submissionIdalbo wartość w innym formacie znaczy, że każde żądanie jest nowym zgłoszeniem.
Pola checkbox
Dział zatytułowany „Pola checkbox”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"].
Metadane (meta)
Dział zatytułowany „Metadane (meta)”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.
Interaktywna dokumentacja
Dział zatytułowany „Interaktywna dokumentacja”Na działającej instancji dostępny jest interaktywny podgląd API (Swagger UI):
GET /api/public/docendpointy publiczneGET /api/admin/docendpointy zarządzające