NueForm

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

Setze den Wert auf true, um das Formular direkt nach dem Erstellen zu veröffentlichen. Die Veröffentlichung führt dieselben Prüfungen aus wie Formular veröffentlichen. Schlägt eine Prüfung fehl, wird das Formular trotzdem als Entwurf erstellt: Die Antwort ist 201 mit published: false und einem publish_error-Objekt (reason, message, question_ids, upgrade_required). Erstelle das Formular nicht erneut – behebe das Problem und rufe dann „Formular veröffentlichen“ auf. Standard: false (Entwurf)

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)

auto_translateboolean

NueLingo — übersetzt das veröffentlichte Formular auf Abruf in jede unterstützte Sprache für Teilnehmer (Pro+; auf anderen Plänen als false gespeichert). Erfordert eine Standardsprache; wirksam mit dem Veröffentlichen.

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,
  "auto_translate": 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: Deine Änderungen werden als Entwurf gespeichert, und Teilnehmer sehen weiterhin die veröffentlichte Version, bis du erneut veröffentlichst.

published ändert den Zustand des Formulars, statt als Feld gespeichert zu werden:

  • Bei einem Entwurf veröffentlicht published: true das Formular, nachdem deine Änderungen gespeichert wurden – mit denselben Prüfungen wie Formular veröffentlichen. Schlägt eine Prüfung fehl, werden deine Änderungen trotzdem gespeichert, und die API gibt 409 Conflict mit form_id und saved_as_draft: true zurück.
  • Bei einem Formular, das bereits live ist, ändert published: true nichts – rufe Formular veröffentlichen auf, um deine Änderungen live zu schalten.
  • published: false nimmt ein live geschaltetes Formular offline, genau wie Veröffentlichung aufheben.

Bei Team-Formularen können nur Team-Admins und -Owner published ändern.

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

Query-Parameter

delete_signed_contractsboolean

Muss true sein, um ein Formular mit abgeschlossenen unterschriebenen Verträgen zu löschen. Diese werden mit dem Formular dauerhaft gelöscht, samt den unterschriebenen PDFs und Audit-Trails. Ohne den Parameter wird ein solches Formular nicht gelöscht: Die API antwortet mit 409, reason: form_has_signed_contracts und signed_contracts (Anzahl).

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 – derselbe Ablauf wie beim Veröffentlichen-Button im Builder. Jede Veröffentlichung erhöht die Versionsnummer, und das Formular wird unter seiner teilbaren URL öffentlich zugänglich.

Bevor etwas veröffentlicht wird, prüft NueForm, dass:

  • Team-Formulare nur von Team-Admins und -Ownern veröffentlicht werden und persönliche Formulare nur von ihrem Owner (alle anderen erhalten 403 Forbidden – oder 404 Not Found, wenn sie nicht Mitglied im Team des Formulars sind);
  • Pro-Funktionen (Buchungsfragen, E-Signatur-Verträge, Datenknoten, Formular-Webhooks und Zahlungen auf dein eigenes Stripe-Konto) im Plan des Formularinhabers enthalten sind (bei Team-Formularen im Plan des Team-Owners);
  • Buchungs-, E-Mail-Schritt-, Fuse- und Composite-Fragen vollständig eingerichtet sind.

Schlägt eine Prüfung fehl, wird das Formular nicht veröffentlicht, und die API gibt 409 Conflict mit einem reason-Code und den zu korrigierenden question_ids zurück (siehe Fehlerbehandlung). Erfolgreiche Antworten enthalten published_version und ein warnings-Array mit nicht blockierenden Hinweisen.

Pfad-Parameter

idstring

Die Formular-ID

Antwort

Gibt das veröffentlichte Formular mit published_version (der neuen Versionsnummer) und warnings (nicht blockierende Hinweise, oft leer) zurück:

json
{
  "data": {
    "id": "665a1b2c3d4e5f6a7b8c9d0e",
    "title": "Customer Feedback Survey",
    "slug": "a1b2c3d4e5f6",
    "published": true,
    "has_unpublished_changes": false,
    "published_version_id": "66c3d4e5f6a7b8c9d0e1f2a3",
    "published_version": 3,
    "warnings": [
      {
        "code": "booking_attendee_ask",
        "question_id": "66a1b2c3d4e5f6a7b8c9d004",
        "question_title": "Book a demo",
        "message": "Booking question \"Book a demo\" has no attendee email mapping, so respondents will be asked for their email when they book."
      }
    ],
    "questions": [ ... ]
  }
}

Veröffentlichung blockiert (409)

Es wird nichts veröffentlicht. reason nennt die fehlgeschlagene Prüfung, question_ids listet die zu korrigierenden Fragen auf; upgrade_required ist true, wenn der Plan des Formularinhabers ein Upgrade braucht:

json
{
  "error": {
    "code": "CONFLICT",
    "message": "E-signature contracts need a Pro plan to go live. Upgrade to publish this form, or remove the contract question.",
    "status": 409,
    "reason": "contract_requires_pro",
    "question_ids": ["66a1b2c3d4e5f6a7b8c9d001"],
    "upgrade_required": true
  }
}

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. Die Veröffentlichung von Team-Formularen können nur Team-Admins und -Owner aufheben, die von persönlichen Formularen nur ihr Owner; alle anderen erhalten 403 Forbidden – oder 404 Not Found, wenn sie nicht Mitglied im Team des Formulars sind.

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

409Conflict

Veröffentlichung blockiert: Eine Veröffentlichungsprüfung ist fehlgeschlagen (siehe Formular veröffentlichen)

500Server Error

Interner Serverfehler

Fehlerbeispiel

json
{
  "error": "Title is required"
}
Zuletzt aktualisiert: 30. Oktober 2026