Zum Inhalt springen

Formular erstellen POST ​

Erstelle ein gehostetes Formular. Es wird sofort unter https://frms.click/{tid} veröffentlicht, und jede Einsendung wird zu einer Push-Nachricht in deinem Konto – siehe Formulare.

Endpunkt ​

POST https://api.pocketalert.app/v1/forms

Authentifizierung ​

Erforderlich

Füge einen dieser Header in deine Anfrage ein:

Anfrage ​

HeaderErforderlichBeschreibung
Token✅Dein API-Schlüssel
Authorization✅Bearer <jwt-token>

Body-Parameter ​

ParameterTypErforderlichBeschreibung
namestring✅Interner Name, bis zu 191 Zeichen. Gleichzeitig der Standardtitel der Push-Benachrichtigung
fieldsarray✅Die Felder des Formulars, maximal 30. Mindestens eines muss etwas sein, das ein Besucher ausfüllt
settingsobject❌Titel, Texte und Design. Jeder Schlüssel hat einen Standardwert
application_tidstring❌Anwendung, zu der die Einsendungen gehören
device_tidstring❌TID des Zielgeräts oder all. Weglassen für alle Geräte
default_levelint❌Prioritätsstufe (-2..2) für Einsendungen. Siehe Prioritätsstufen von Nachrichten
push_titlestring❌Vorlage für den Push-Titel mit {Field label}-Platzhaltern, bis zu 191 Zeichen
allowed_originsarray❌Hosts, die das Formular einbetten und absenden dürfen, maximal 10. Leer bedeutet überall
max_responsesint❌Formular nach dieser Anzahl an Antworten schließen. 0 (Standard) bedeutet unbegrenzt
closes_atstring❌Schließzeitpunkt, RFC 3339. Wird in UTC gespeichert
is_activeboolean❌false schließt das Formular sofort. Standard ist true

Felder ​

Jeder Eintrag in fields:

ParameterTypErforderlichBeschreibung
idstring✅Innerhalb des Formulars eindeutig: Buchstaben, Ziffern, _ und -, bis zu 40 Zeichen
typestring✅Einer der unten aufgeführten Typen
labelstring✅Wird über dem Eingabefeld angezeigt, bis zu 200 Zeichen (2000 bei paragraph)
placeholderstring❌Nur bei text, textarea, email, phone, number, url und dropdown
requiredboolean❌Wird bei Layout-Feldern ignoriert
optionsarray✅ bei AuswahlfeldernBis zu 50 Einträge für dropdown, radio und checkboxes
paramstring✅ bei hiddenURL-Parameter, aus dem der Wert gelesen wird, z. B. utm_source
GruppeTypenÜbermittelter Wert
Texttext, textarea, email, phone, number, url, dateString. text ist auf 1000 Zeichen begrenzt, textarea auf 5000
Auswahldropdown, radioEiner der options
AuswahlcheckboxesArray aus options
AuswahlcheckboxBoolean, dargestellt als Yes / No
Bewertungrating (1–5), nps (0–10)Zahl
Layoutheading, paragraph, dividerWird nie übermittelt
TrackinghiddenStammt aus der Seiten-URL, nicht vom Besucher

E-Mail-, Telefon-, Zahlen-, URL- und Datumswerte werden auf dem Server geprüft; die Prüfung im Browser ist nur eine Komfortfunktion, kein Schutz.

Einstellungen ​

Alle Schlüssel sind optional – was du weglässt, behält seinen Standardwert.

ParameterTypStandardBeschreibung
titlestring""Überschrift über dem Formular, bis zu 200 Zeichen
top_textstring""Einleitungstext, bis zu 2000 Zeichen. Reiner Text; Links werden klickbar
bottom_textstring""Text unter dem Button, bis zu 2000 Zeichen
success_messagestringThanks! Your response has been sent.Wird nach dem Absenden angezeigt, bis zu 500 Zeichen
closed_messagestringThis form is no longer accepting responses.Wird angezeigt, wenn das Formular geschlossen ist
background_colorstring#f5f5f4Seitenhintergrund, #rrggbb
card_colorstring#ffffffHintergrund des Formulars
text_colorstring#1c1917Textfarbe
primary_colorstring#3f5cadAkzentfarbe und, sofern nicht überschrieben, die Farbe des Buttons
font_familystringInterEine Google Font nach Name
font_sizeint1612–24
font_weightint400300, 400, 500, 600 oder 700
border_radiusint100–48
hide_brandingbooleanfalseBlendet den Link „Powered by Pocket Alert“ aus. Nur in kostenpflichtigen Tarifen – im kostenlosen Tarif setzt die API den Wert auf false zurück
submitobject—{ "text": "Submit", "color": "", "size": "md" }. size ist sm, md oder lg; eine leere color folgt primary_color

Vorlage für den Push-Titel ​

push_title baut den Titel der Benachrichtigung aus den Antworten:

New lead: {Name} ({Email})

Platzhalter verweisen auf Felder über die Bezeichnung, ohne Groß-/Kleinschreibung, dazu {form} für den Namen des Formulars. Platzhalter ohne Antwort fallen weg; ist danach nichts mehr übrig, greift der Titel Form: {name}. Die Vorlage wird auf der öffentlichen Seite nie angezeigt.

Erlaubte Ursprünge ​

Eine Formular-ID steckt in seinem öffentlichen Link, daher kann es standardmäßig jeder, der sie hat, einbetten. allowed_origins verhindert das: Nur die aufgelisteten Hosts dürfen das Formular einbinden, und eine Einsendung, deren Origin (oder Referer) nicht auf der Liste steht, wird mit 403 abgelehnt.

Gib Hosts an, keine URLs: example.com, app.example.com, *.example.com für alle Subdomains, localhost:3000 während der Entwicklung. www. wird ignoriert.

Beispielanfrage ​

bash
curl -X POST "https://api.pocketalert.app/v1/forms" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contact form",
    "push_title": "New lead: {Name}",
    "fields": [
      { "id": "name", "type": "text", "label": "Name", "required": true },
      { "id": "email", "type": "email", "label": "Email", "required": true },
      { "id": "message", "type": "textarea", "label": "Message" },
      { "id": "src", "type": "hidden", "label": "Source", "param": "utm_source" }
    ],
    "settings": {
      "title": "Get in touch",
      "top_text": "We reply within one business day.",
      "primary_color": "#3f5cad"
    }
  }'
javascript
const response = await fetch('https://api.pocketalert.app/v1/forms', {
  method: 'POST',
  headers: {
    'Token': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Contact form',
    push_title: 'New lead: {Name}',
    fields: [
      { id: 'name', type: 'text', label: 'Name', required: true },
      { id: 'email', type: 'email', label: 'Email', required: true },
      { id: 'message', type: 'textarea', label: 'Message' }
    ],
    settings: { title: 'Get in touch' }
  })
});

const form = await response.json();
console.log('Form link:', `https://frms.click/${form.tid}`);
python
import requests

response = requests.post(
    'https://api.pocketalert.app/v1/forms',
    headers={'Token': 'your-api-key'},
    json={
        'name': 'Contact form',
        'push_title': 'New lead: {Name}',
        'fields': [
            {'id': 'name', 'type': 'text', 'label': 'Name', 'required': True},
            {'id': 'email', 'type': 'email', 'label': 'Email', 'required': True},
            {'id': 'message', 'type': 'textarea', 'label': 'Message'},
        ],
        'settings': {'title': 'Get in touch'},
    }
)

form = response.json()
print(f"Form link: https://frms.click/{form['tid']}")
php
$form = Http::withHeaders([
    'Token' => 'your-api-key',
])->post('https://api.pocketalert.app/v1/forms', [
    'name' => 'Contact form',
    'push_title' => 'New lead: {Name}',
    'fields' => [
        ['id' => 'name', 'type' => 'text', 'label' => 'Name', 'required' => true],
        ['id' => 'email', 'type' => 'email', 'label' => 'Email', 'required' => true],
        ['id' => 'message', 'type' => 'textarea', 'label' => 'Message'],
    ],
    'settings' => ['title' => 'Get in touch'],
])->json();

echo 'Form link: https://frms.click/'.$form['tid'];

Antwort ​

Erfolgreiche Antwort ​

201 Created

Das Formular ist live. Teile https://frms.click/{tid} oder binde es ein – siehe Formulare.

Der Body hat dieselbe Struktur wie ein Eintrag aus Alle Formulare abrufen.

json
{
  "tid": "vml19aihrga216gt8apc5e3m9",
  "name": "Contact form",
  "fields": [
    { "id": "name", "type": "text", "label": "Name", "required": true },
    { "id": "email", "type": "email", "label": "Email", "required": true },
    { "id": "message", "type": "textarea", "label": "Message" },
    { "id": "src", "type": "hidden", "label": "Source", "param": "utm_source" }
  ],
  "settings": {
    "title": "Get in touch",
    "top_text": "We reply within one business day.",
    "success_message": "Thanks! Your response has been sent.",
    "closed_message": "This form is no longer accepting responses.",
    "background_color": "#f5f5f4",
    "card_color": "#ffffff",
    "text_color": "#1c1917",
    "primary_color": "#3f5cad",
    "font_family": "Inter",
    "font_size": 16,
    "font_weight": 400,
    "border_radius": 10,
    "hide_branding": false,
    "submit": { "text": "Submit", "color": "", "size": "md" }
  },
  "application_tid": "",
  "device_tid": "",
  "default_level": null,
  "push_title": "New lead: {Name}",
  "allowed_origins": [],
  "max_responses": 0,
  "closes_at": null,
  "closed": false,
  "is_active": true,
  "submissions_count": 0,
  "last_submission_at": "",
  "created_at": "23.09.2026 11:40:02"
}

Fehlerantworten ​

StatusBeschreibung
400Validierungsfehler — das Feld error nennt das fehlerhafte Feld oder die fehlerhafte Einstellung
401Nicht autorisiert — Token ungültig oder fehlend
403Du hast die Anzahl an Formularen erreicht, die dein Tarif erlaubt
500Formular konnte nicht erstellt werden

Pocket Alert Dokumentation