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/formsAuthentifizierung
Erforderlich
Füge einen dieser Header in deine Anfrage ein:
Token: <your-api-key>— Hol ihn dir unter API-SchlüsselAuthorization: Bearer <jwt-token>— Aus Anmeldung
Anfrage
Header
| Header | Erforderlich | Beschreibung |
|---|---|---|
Token | ✅ | Dein API-Schlüssel |
Authorization | ✅ | Bearer <jwt-token> |
Body-Parameter
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
name | string | ✅ | Interner Name, bis zu 191 Zeichen. Gleichzeitig der Standardtitel der Push-Benachrichtigung |
fields | array | ✅ | Die Felder des Formulars, maximal 30. Mindestens eines muss etwas sein, das ein Besucher ausfüllt |
settings | object | ❌ | Titel, Texte und Design. Jeder Schlüssel hat einen Standardwert |
application_tid | string | ❌ | Anwendung, zu der die Einsendungen gehören |
device_tid | string | ❌ | TID des Zielgeräts oder all. Weglassen für alle Geräte |
default_level | int | ❌ | Prioritätsstufe (-2..2) für Einsendungen. Siehe Prioritätsstufen von Nachrichten |
push_title | string | ❌ | Vorlage für den Push-Titel mit {Field label}-Platzhaltern, bis zu 191 Zeichen |
allowed_origins | array | ❌ | Hosts, die das Formular einbetten und absenden dürfen, maximal 10. Leer bedeutet überall |
max_responses | int | ❌ | Formular nach dieser Anzahl an Antworten schließen. 0 (Standard) bedeutet unbegrenzt |
closes_at | string | ❌ | Schließzeitpunkt, RFC 3339. Wird in UTC gespeichert |
is_active | boolean | ❌ | false schließt das Formular sofort. Standard ist true |
Felder
Jeder Eintrag in fields:
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
id | string | ✅ | Innerhalb des Formulars eindeutig: Buchstaben, Ziffern, _ und -, bis zu 40 Zeichen |
type | string | ✅ | Einer der unten aufgeführten Typen |
label | string | ✅ | Wird über dem Eingabefeld angezeigt, bis zu 200 Zeichen (2000 bei paragraph) |
placeholder | string | ❌ | Nur bei text, textarea, email, phone, number, url und dropdown |
required | boolean | ❌ | Wird bei Layout-Feldern ignoriert |
options | array | ✅ bei Auswahlfeldern | Bis zu 50 Einträge für dropdown, radio und checkboxes |
param | string | ✅ bei hidden | URL-Parameter, aus dem der Wert gelesen wird, z. B. utm_source |
| Gruppe | Typen | Übermittelter Wert |
|---|---|---|
| Text | text, textarea, email, phone, number, url, date | String. text ist auf 1000 Zeichen begrenzt, textarea auf 5000 |
| Auswahl | dropdown, radio | Einer der options |
| Auswahl | checkboxes | Array aus options |
| Auswahl | checkbox | Boolean, dargestellt als Yes / No |
| Bewertung | rating (1–5), nps (0–10) | Zahl |
| Layout | heading, paragraph, divider | Wird nie übermittelt |
| Tracking | hidden | Stammt 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.
| Parameter | Typ | Standard | Beschreibung |
|---|---|---|---|
title | string | "" | Überschrift über dem Formular, bis zu 200 Zeichen |
top_text | string | "" | Einleitungstext, bis zu 2000 Zeichen. Reiner Text; Links werden klickbar |
bottom_text | string | "" | Text unter dem Button, bis zu 2000 Zeichen |
success_message | string | Thanks! Your response has been sent. | Wird nach dem Absenden angezeigt, bis zu 500 Zeichen |
closed_message | string | This form is no longer accepting responses. | Wird angezeigt, wenn das Formular geschlossen ist |
background_color | string | #f5f5f4 | Seitenhintergrund, #rrggbb |
card_color | string | #ffffff | Hintergrund des Formulars |
text_color | string | #1c1917 | Textfarbe |
primary_color | string | #3f5cad | Akzentfarbe und, sofern nicht überschrieben, die Farbe des Buttons |
font_family | string | Inter | Eine Google Font nach Name |
font_size | int | 16 | 12–24 |
font_weight | int | 400 | 300, 400, 500, 600 oder 700 |
border_radius | int | 10 | 0–48 |
hide_branding | boolean | false | Blendet den Link „Powered by Pocket Alert“ aus. Nur in kostenpflichtigen Tarifen – im kostenlosen Tarif setzt die API den Wert auf false zurück |
submit | object | — | { "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
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"
}
}'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}`);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']}")$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.
{
"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
| Status | Beschreibung |
|---|---|
400 | Validierungsfehler — das Feld error nennt das fehlerhafte Feld oder die fehlerhafte Einstellung |
401 | Nicht autorisiert — Token ungültig oder fehlend |
403 | Du hast die Anzahl an Formularen erreicht, die dein Tarif erlaubt |
500 | Formular konnte nicht erstellt werden |