Forms-API

Formulare erstellen, abrufen, aktualisieren, löschen, veröffentlichen und duplizieren.

Mit der Forms-API verwaltest du deine NueForm-Formulare programmatisch. Du kannst Formulare auflisten, erstellen, abrufen, aktualisieren, löschen, veröffentlichen, ihre Veröffentlichung aufheben und sie duplizieren.

Alle Request- und Antwort-Bodys verwenden Feldnamen in snake_case.

Endpoints

GET/api/v1/formsPOST/api/v1/formsGET/api/v1/forms/:idPUT/api/v1/forms/:idDELETE/api/v1/forms/:idPOST/api/v1/forms/:id/publishDELETE/api/v1/forms/:id/publishPOST/api/v1/forms/:id/duplicate

Formulare auflisten

GET/api/v1/forms

Gibt eine paginierte Liste der Formulare zurück, auf die der authentifizierte Nutzer Zugriff hat — inklusive persönlicher Formulare und Formulare aus Teams, denen der Nutzer angehört.

Query-Parameter

pageinteger

Seitennummer (Standard: 1)

per_pageinteger

Ergebnisse pro Seite (Standard: 50)

searchstring

Filtert Formulare nach Titel (Teiltreffer ohne Beachtung der Groß-/Kleinschreibung)

team_idstring

Gibt nur Formulare dieses Teams zurück

publishedboolean

Filtert nach Veröffentlichungsstatus (true oder false)

Antwort

json

{
  "forms": [
    {
      "id": "665a1b2c3d4e5f6a7b8c9d0e",
      "title": "Customer Feedback Survey",
      "description": "Quarterly satisfaction survey for Q1 2026",
      "slug": "a1b2c3d4e5f6",
      "published": true,
      "created_at": "2026-01-15T10:30:00.000Z",
      "updated_at": "2026-02-20T14:22:00.000Z",
      "theme_color": "#6366f1",
      "background_color": "#0a0a0a",
      "response_count": 142,
      "team": {
        "id": "665b2c3d4e5f6a7b8c9d0e1f",
        "name": "Marketing"
      }
    }
  ],
  "total": 24,
  "page": 1,
  "per_page": 50
}

Codebeispiele

bash

curl -X GET "https://api.nueform.io/api/v1/forms?page=1&per_page=10&published=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Formular erstellen

POST/api/v1/forms

Erstellt ein neues Formular. Optional kannst du ein Array von Fragen mitgeben, die zusammen mit dem Formular erstellt werden.

Request-Body

titlestring

Formulartitel (darf nicht leer sein)

descriptionstring

Formularbeschreibung

team_idstring

Weist das Formular einem Team zu (erfordert die Berechtigung create_forms)

publishedboolean

Ob das Formular veröffentlicht ist (Standard: false)

theme_colorstring

Primäre Theme-Farbe (Hex, Standard: #6366f1)

background_colorstring

Hintergrundfarbe (Hex, Standard: #0a0a0a)

text_colorstring

Textfarbe der Fragen (Hex)

answer_text_colorstring

Textfarbe der Antworteingaben (Hex)

placeholder_colorstring

Platzhalterfarbe der Eingabefelder (Hex)

button_colorstring

Hintergrundfarbe der Schaltflächen (Hex)

button_text_colorstring

Textfarbe der Schaltflächen (Hex)

title_colorstring

Textfarbe der Titel (Hex)

description_colorstring

Textfarbe der Beschreibungen (Hex)

option_text_colorstring

Textfarbe der Auswahloptionen (Hex)

indicator_bg_colorstring

Hintergrundfarbe des Schrittindikators (Hex)

indicator_text_colorstring

Textfarbe des Schrittindikators (Hex)

font_familystring

Schriftfamilie der Fragen

font_family_answerstring

Schriftfamilie der Antworteingaben

font_family_buttonstring

Schriftfamilie der Schaltflächen

font_family_descriptionstring

Schriftfamilie der Beschreibungen

font_family_optionstring

Schriftfamilie der Auswahloptionen

font_family_indicatorstring

Schriftfamilie des Schrittindikators

question_font_sizestring

Schriftgröße der Fragen (z. B. "24px")

custom_cssstring

Eigenes CSS, das in den Formular-Renderer injiziert wird

show_progress_barboolean

Zeigt einen Fortschrittsbalken (Standard: true)

branding_logo_urlstring

URL des Branding-Logos

branding_footer_textstring

Eigener Footer-Text

hide_brandingboolean

Blendet das NueForm-Branding aus (Standard: false)

top_logo_urlstring

URL für ein Logo am oberen Rand des Formulars

top_logo_sizestring

Größe des oberen Logos (z. B. "120px")

top_logo_alignmentstring

Ausrichtung des oberen Logos ("left", "center", "right")

top_logo_cssstring

Eigenes CSS für das obere Logo

watermark_cssstring

Eigenes CSS für das Wasserzeichen

welcome_titlestring

Titel des Willkommensbildschirms

welcome_descriptionstring

Beschreibung des Willkommensbildschirms

welcome_button_textstring

Schaltflächentext des Willkommensbildschirms (Standard: "Start")

thank_you_titlestring

Titel des Dankesbildschirms (Standard: "Thank you!")

thank_you_descriptionstring

Beschreibung des Dankesbildschirms

modestring

Formularmodus: "standard", "knowledge_quiz", "lead_qualification", "match_quiz" (Standard: "standard")

quiz_settingsobject

Quiz-Konfiguration (für Quiz-Modi)

variablesobject

Variablen auf Formularebene für die Logik

start_logic_jumpsarray

Logiksprung-Regeln, die beim Formularstart angewendet werden

webhook_urlstring

URL, die bei Übermittlung einen POST erhält (Pro-Plan erforderlich)

limit_one_responseboolean

Begrenzt auf eine Antwort pro Besucher (Standard: false)

incremental_submissionboolean

Speichert Antworten inkrementell, während der Teilnehmer voranschreitet (Standard: false)

questionsarray

Array der zu erstellenden Frageobjekte (siehe unten)

Request-Beispiel

json

{
  "title": "Customer Feedback Survey",
  "description": "Help us improve our product",
  "theme_color": "#2563eb",
  "background_color": "#ffffff",
  "show_progress_bar": true,
  "welcome_title": "We value your feedback",
  "welcome_description": "This survey takes about 3 minutes.",
  "welcome_button_text": "Let's go",
  "thank_you_title": "Thank you!",
  "thank_you_description": "Your feedback helps us build a better product.",
  "questions": [
    {
      "type": "short_text",
      "title": "What is your name?",
      "required": true
    },
    {
      "type": "multiple_choice",
      "title": "How did you hear about us?",
      "required": true,
      "properties": {
        "choices": [
          { "label": "Search engine" },
          { "label": "Social media" },
          { "label": "Friend or colleague" },
          { "label": "Other" }
        ],
        "allow_multiple": false
      }
    },
    {
      "type": "rating",
      "title": "How would you rate your overall experience?",
      "required": true,
      "properties": {
        "steps": 5,
        "shape": "star"
      }
    }
  ]
}

Antwort

Gibt das erstellte Formularobjekt mit allen Fragen zurück:

json

{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "description": "Help us improve our product",
  "slug": "a1b2c3d4e5f6",
  "published": false,
  "created_at": "2026-02-28T12:00:00.000Z",
  "updated_at": "2026-02-28T12:00:00.000Z",
  "theme_color": "#2563eb",
  "background_color": "#ffffff",
  "show_progress_bar": true,
  "welcome_title": "We value your feedback",
  "welcome_description": "This survey takes about 3 minutes.",
  "welcome_button_text": "Let's go",
  "thank_you_title": "Thank you!",
  "thank_you_description": "Your feedback helps us build a better product.",
  "questions": [
    {
      "id": "66a1b2c3d4e5f6a7b8c9d001",
      "type": "short_text",
      "title": "What is your name?",
      "description": null,
      "required": true,
      "order": 0,
      "properties": {},
      "logic_jumps": [],
      "validations": {}
    },
    {
      "id": "66a1b2c3d4e5f6a7b8c9d002",
      "type": "multiple_choice",
      "title": "How did you hear about us?",
      "description": null,
      "required": true,
      "order": 1,
      "properties": {
        "choices": [
          { "label": "Search engine" },
          { "label": "Social media" },
          { "label": "Friend or colleague" },
          { "label": "Other" }
        ],
        "allow_multiple": false
      },
      "logic_jumps": [],
      "validations": {}
    },
    {
      "id": "66a1b2c3d4e5f6a7b8c9d003",
      "type": "rating",
      "title": "How would you rate your overall experience?",
      "description": null,
      "required": true,
      "order": 2,
      "properties": {
        "steps": 5,
        "shape": "star"
      },
      "logic_jumps": [],
      "validations": {}
    }
  ]
}

Codebeispiele

bash

curl -X POST "https://api.nueform.io/api/v1/forms" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Customer Feedback Survey",
    "description": "Help us improve our product",
    "questions": [
      {
        "type": "short_text",
        "title": "What is your name?",
        "required": true
      }
    ]
  }'

Formular abrufen

GET/api/v1/forms/:id

Ruft ein einzelnes Formular per ID ab, inklusive aller Fragen in ihrer Positionsreihenfolge.

Pfad-Parameter

idstring

Die Formular-ID

Antwort

json

{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "description": "Help us improve our product",
  "slug": "a1b2c3d4e5f6",
  "published": true,
  "created_at": "2026-01-15T10:30:00.000Z",
  "updated_at": "2026-02-20T14:22:00.000Z",
  "theme_color": "#2563eb",
  "background_color": "#ffffff",
  "text_color": null,
  "answer_text_color": null,
  "placeholder_color": null,
  "button_color": null,
  "button_text_color": null,
  "font_family": null,
  "question_font_size": null,
  "custom_css": null,
  "show_progress_bar": true,
  "incremental_submission": false,
  "limit_one_response": false,
  "welcome_title": "We value your feedback",
  "welcome_description": "This survey takes about 3 minutes.",
  "welcome_button_text": "Let's go",
  "thank_you_title": "Thank you!",
  "thank_you_description": "Your feedback helps us build a better product.",
  "branding_logo_url": null,
  "branding_footer_text": null,
  "hide_branding": false,
  "mode": "standard",
  "webhook_url": null,
  "has_unpublished_changes": false,
  "published_version_id": "66c3d4e5f6a7b8c9d0e1f2a3",
  "response_count": 142,
  "questions": [
    {
      "id": "66a1b2c3d4e5f6a7b8c9d001",
      "type": "short_text",
      "title": "What is your name?",
      "description": null,
      "required": true,
      "order": 0,
      "properties": {},
      "logic_jumps": [],
      "validations": {}
    }
  ]
}

Codebeispiele

bash

curl -X GET "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer YOUR_API_KEY"

Formular aktualisieren

PUT/api/v1/forms/:id

Aktualisiert die Felder eines Formulars und synchronisiert seine Fragen. Wenn du ein questions-Array mitschickst, wird NueForm:

Bestehende Fragen aktualisieren (Zuordnung per id)
Neue Fragen erstellen (keine id oder unbekannte id)
Fragen löschen, die am Formular existieren, aber nicht im Array enthalten sind

Ist das Formular aktuell veröffentlicht, wird das Flag has_unpublished_changes automatisch auf true gesetzt.

Pfad-Parameter

idstring

Die Formular-ID

Request-Body

Akzeptiert alle Felder aus Formular erstellen außer team_id. Gib nur die Felder an, die du ändern möchtest.

Request-Beispiel

json

{
  "title": "Updated Survey Title",
  "description": "Revised description for Q2",
  "theme_color": "#10b981",
  "questions": [
    {
      "id": "66a1b2c3d4e5f6a7b8c9d001",
      "type": "short_text",
      "title": "What is your full name?",
      "required": true
    },
    {
      "type": "long_text",
      "title": "Any additional comments?",
      "required": false
    }
  ]
}

Antwort

Gibt das aktualisierte Formularobjekt mit allen Fragen zurück (gleiches Schema wie Formular abrufen).

Codebeispiele

bash

curl -X PUT "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Survey Title",
    "theme_color": "#10b981"
  }'

Formular löschen

DELETE/api/v1/forms/:id

Löscht ein Formular dauerhaft samt allen zugehörigen Daten, einschließlich Fragen, Antworten, Versionen und Changelog-Einträgen. Zugehörige Datei-Uploads werden asynchron bereinigt.

Diese Aktion ist unumkehrbar. Alle für dieses Formular erfassten Antworten werden dauerhaft gelöscht.

Pfad-Parameter

idstring

Die Formular-ID

Antwort

json

{
  "success": true
}

Codebeispiele

bash

curl -X DELETE "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer YOUR_API_KEY"

Formular veröffentlichen

POST/api/v1/forms/:id/publish

Veröffentlicht ein Formular, indem ein versionierter Snapshot des aktuellen Formulars und seiner Fragen erstellt wird. Jede Veröffentlichung erhöht die Versionsnummer. Das Formular wird unter seiner teilbaren URL öffentlich zugänglich.

Pfad-Parameter

idstring

Die Formular-ID

Antwort

Gibt das Formularobjekt mit einem Feld published_version zurück, das die neue Versionsnummer angibt:

json

{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "slug": "a1b2c3d4e5f6",
  "published": true,
  "has_unpublished_changes": false,
  "published_version_id": "66c3d4e5f6a7b8c9d0e1f2a3",
  "published_version": 3,
  "questions": [ ... ]
}

Codebeispiele

bash

curl -X POST "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/publish" \
  -H "Authorization: Bearer YOUR_API_KEY"

Veröffentlichung aufheben

DELETE/api/v1/forms/:id/publish

Hebt die Veröffentlichung eines Formulars auf, sodass es unter seiner öffentlichen URL nicht mehr erreichbar ist. Der veröffentlichte Versions-Snapshot bleibt erhalten, damit du später erneut veröffentlichen kannst.

Pfad-Parameter

idstring

Die Formular-ID

Antwort

Gibt das aktualisierte Formularobjekt mit published auf false zurück.

json

{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "published": false,
  "questions": [ ... ]
}

Codebeispiele

bash

curl -X DELETE "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/publish" \
  -H "Authorization: Bearer YOUR_API_KEY"

Formular duplizieren

POST/api/v1/forms/:id/duplicate

Erstellt eine Kopie eines bestehenden Formulars, inklusive aller Fragen. Logiksprung-Referenzen werden automatisch auf die neuen Frage-IDs umgemappt. Das duplizierte Formular wird immer im unveröffentlichten Zustand erstellt.

Pfad-Parameter

idstring

Die ID des zu duplizierenden Formulars

Request-Body

titlestring

Titel für das neue Formular (Standard: "Original Title (Copy)")

team_idstring

Weist das Duplikat einem anderen Team zu

Request-Beispiel

json

{
  "title": "Customer Feedback Survey v2",
  "team_id": "665b2c3d4e5f6a7b8c9d0e1f"
}

Antwort

Gibt das neu erstellte Formularobjekt zurück (gleiches Schema wie Formular abrufen) mit published auf false.

Codebeispiele

bash

curl -X POST "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/duplicate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Customer Feedback Survey v2" }'

Fehlerantworten

Alle Endpunkte geben Standard-Fehlerantworten zurück.

Fehlercodes

400Bad Request

Validierungsfehler oder fehlendes Pflichtfeld

401Unauthorized

Fehlender oder ungültiger API-Schlüssel

403Forbidden

Unzureichende Berechtigungen bei Team-Formularen

404Not Found

Formular nicht gefunden

500Server Error

Interner Serverfehler

Fehlerbeispiel

json

{
  "error": "Title is required"
}

Zuletzt aktualisiert: 20. Juli 2026