NueForm

Signing-Sessions-API

Elektronische Signatursitzungen für Vertragsfragen erstellen, verwalten und nachverfolgen.

Mit der Signing-Sessions-API erstellst und verwaltest du Signatursitzungen für Vertragsfragen programmatisch. Du kannst Sitzungen erstellen, den Signaturfortschritt verfolgen, Anfragen erneut senden, Sitzungen für ungültig erklären und signierte Dokumente herunterladen.

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

Endpoints
POST/api/v1/forms/:id/signing-sessionsGET/api/v1/forms/:id/signing-sessionsGET/api/v1/signing-sessions/:sessionIdPOST/api/v1/signing-sessions/:sessionId/voidPOST/api/v1/signing-sessions/:sessionId/resend/:slotNumberGET/api/v1/signing-sessions/:sessionId/documentsGET/api/v1/signing-sessions/:sessionId/documents/:docIdGET/api/v1/signing-sessions/:sessionId/auditGET/api/v1/s/:shortCodePOST/api/v1/s/:shortCode/verify-password

Sitzung erstellen

POST/api/v1/forms/:id/signing-sessions

Erstellt eine neue Signatursitzung für ein Formular, das eine oder mehrere Vertragsfragen enthält. Gibt die Sitzung mit eindeutigen Signaturlinks für jeden Unterzeichner-Slot zurück.

Pfad-Parameter

idstring

Die Formular-ID

Request-Body

signersarray

Array von Unterzeichner-Konfigurationen, eine pro Slot. Jedes Objekt kann slot_number (integer), first_name (string), last_name (string) und email (string) enthalten. Alle Felder außer slot_number sind optional.

signing_orderstring

"sequential" oder "any". Standard ist die Standard-Signaturreihenfolge der Frage.

expiry_daysinteger

Anzahl der Tage bis zum Ablauf der Sitzung. Standard: 30.

passwordstring

Passwort zum Schutz der Signaturlinks.

hide_other_signersboolean

Blendet die ausgefüllten Felder anderer Unterzeichner aus. Standard: false.

require_email_verificationboolean

Erfordert eine E-Mail-Verifizierung vor dem Signieren. Standard: false.

copy_modestring

"ask", "always" oder "disabled". Standard: "ask".

notify_emailsarray

Array von E-Mail-Adressen, die Statusbenachrichtigungen erhalten.

notify_eventsarray

Array von Ereignistypen: "each_signature", "all_complete", "decline", "expiry".

send_signing_emailsboolean

Sendet Signaturanfrage-E-Mails an Unterzeichner mit hinterlegter E-Mail-Adresse. Standard: false.

custom_email_bodystring

Eigene E-Mail-Vorlage. Unterstützt die Variablen: {slot_firstName}, {slot_lastName}, {slot_link}, {expiryDate}.

Antwort

json
{
  "id": "ses_abc123def456",
  "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "status": "active",
  "signing_order": "sequential",
  "total_slots": 2,
  "total_signed": 0,
  "expires_at": "2026-04-25T00:00:00.000Z",
  "hide_other_signers": false,
  "copy_mode": "ask",
  "signer_links": [
    {
      "slot_number": 1,
      "slot_label": "Buyer",
      "short_code": "xK9f2",
      "signing_url": "https://nue.fm/s/xK9f2",
      "first_name": "John",
      "last_name": "Smith",
      "email": "john@example.com",
      "status": "pending"
    },
    {
      "slot_number": 2,
      "slot_label": "Seller",
      "short_code": "mP3a7",
      "signing_url": "https://nue.fm/s/mP3a7",
      "first_name": null,
      "last_name": null,
      "email": null,
      "status": "pending"
    }
  ],
  "created_at": "2026-03-26T10:00:00.000Z"
}

Codebeispiele

bash
curl -X POST "https://api.nueform.io/api/v1/forms/FORM_ID/signing-sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signers": [
      {"slot_number": 1, "first_name": "John", "last_name": "Smith", "email": "john@example.com"},
      {"slot_number": 2, "first_name": "Jane", "last_name": "Doe"}
    ],
    "signing_order": "sequential",
    "expiry_days": 30,
    "send_signing_emails": true
  }'

Sitzungen auflisten

GET/api/v1/forms/:id/signing-sessions

Gibt alle Signatursitzungen eines Formulars zurück.

Query-Parameter

statusstring

Filtert nach Status: "active", "fully_signed", "declined", "voided", "expired".

pageinteger

Seitennummer (Standard: 1)

per_pageinteger

Ergebnisse pro Seite (Standard: 20)

Antwort

json
{
  "sessions": [
    {
      "id": "ses_abc123def456",
      "status": "active",
      "total_slots": 2,
      "total_signed": 1,
      "signing_order": "sequential",
      "expires_at": "2026-04-25T00:00:00.000Z",
      "created_at": "2026-03-26T10:00:00.000Z"
    }
  ],
  "total": 5,
  "page": 1,
  "per_page": 20
}

Codebeispiele

bash
curl -X GET "https://api.nueform.io/api/v1/forms/FORM_ID/signing-sessions?status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

Sitzung abrufen

GET/api/v1/signing-sessions/:sessionId

Gibt eine einzelne Signatursitzung mit allen Details zurück, inklusive Signaturlinks und deren Status.

Antwort

Gibt dasselbe Sitzungsobjekt wie der Erstellungs-Endpunkt zurück, mit aktualisierten Status und Zeitstempeln für jeden Signaturlink.

Codebeispiele

bash
curl -X GET "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456" \
  -H "Authorization: Bearer YOUR_API_KEY"

Sitzung für ungültig erklären

POST/api/v1/signing-sessions/:sessionId/void

Erklärt eine aktive Signatursitzung für ungültig. Alle ausstehenden Signaturlinks werden invalidiert. Bereits unterzeichnende Parteien werden benachrichtigt, und PDFs erhalten das Wasserzeichen „VOIDED".

Request-Body

reasonstring

Grund für die Ungültigerklärung der Sitzung.

Antwort

json
{
  "id": "ses_abc123def456",
  "status": "voided",
  "voided_at": "2026-03-27T15:30:00.000Z",
  "void_reason": "Terms changed, new agreement required"
}

Codebeispiele

bash
curl -X POST "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456/void" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Terms changed, new agreement required"}'

Signaturanfrage erneut senden

POST/api/v1/signing-sessions/:sessionId/resend/:slotNumber

Sendet die Signaturanfrage-E-Mail erneut an einen bestimmten Unterzeichner. Für den Unterzeichner muss eine E-Mail-Adresse hinterlegt sein.

Antwort

json
{
  "success": true,
  "sent_to": "john@example.com",
  "slot_number": 1
}

Codebeispiele

bash
curl -X POST "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456/resend/1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Signierte Dokumente auflisten

GET/api/v1/signing-sessions/:sessionId/documents

Gibt eine Liste der signierten Dokumente einer abgeschlossenen Sitzung zurück. Jedes Dokument entspricht einer Vertragsfrage im Formular.

Antwort

json
{
  "documents": [
    {
      "id": "doc_xyz789",
      "question_id": "q_abc123",
      "question_title": "Service Agreement",
      "document_url": "https://storage.nueform.io/signed/doc_xyz789.pdf",
      "document_hash": "sha256:a1b2c3d4e5f6...",
      "generated_at": "2026-03-28T12:00:00.000Z"
    }
  ]
}

Codebeispiele

bash
curl -X GET "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456/documents" \
  -H "Authorization: Bearer YOUR_API_KEY"

Signiertes Dokument abrufen

GET/api/v1/signing-sessions/:sessionId/documents/:docId

Lädt ein bestimmtes signiertes Dokument als PDF-Datei herunter.

Antwort

Gibt die PDF-Datei mit Content-Type: application/pdf zurück.

Codebeispiele

bash
curl -X GET "https://api.nueform.io/api/v1/signing-sessions/ses_abc123/documents/doc_xyz789" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o signed-document.pdf

Prüfpfad abrufen

GET/api/v1/signing-sessions/:sessionId/audit

Gibt den vollständigen Prüfpfad einer Signatursitzung zurück, inklusive Anzeigeereignissen, Signaturen, Ablehnungen und Systemereignissen.

Antwort

json
{
  "entries": [
    {
      "id": "aud_001",
      "action": "session_created",
      "timestamp": "2026-03-26T10:00:00.000Z",
      "actor_email": "owner@company.com",
      "ip_address": "192.168.1.1",
      "user_agent": "Chrome 120 / macOS"
    },
    {
      "id": "aud_002",
      "action": "document_viewed",
      "slot_number": 1,
      "actor_email": "john@example.com",
      "timestamp": "2026-03-26T15:44:00.000Z",
      "ip_address": "10.0.0.1",
      "user_agent": "Chrome 120 / macOS"
    },
    {
      "id": "aud_003",
      "action": "signed",
      "slot_number": 1,
      "actor_name": "John Smith",
      "actor_email": "john@example.com",
      "timestamp": "2026-03-26T15:45:00.000Z",
      "ip_address": "10.0.0.1",
      "user_agent": "Chrome 120 / macOS"
    }
  ]
}

Codebeispiele

bash
curl -X GET "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456/audit" \
  -H "Authorization: Bearer YOUR_API_KEY"

Kurzcode auflösen

GET/api/v1/s/:shortCode

Öffentlicher Endpunkt (keine Authentifizierung erforderlich). Löst einen Signatur-Kurzcode zum Formular- und Sitzungskontext auf, der zum Rendern des Signaturerlebnisses benötigt wird.

Antwort

json
{
  "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "session_id": "ses_abc123def456",
  "slot_number": 1,
  "slot_label": "Buyer",
  "status": "pending",
  "requires_password": true,
  "requires_email_verification": false,
  "signing_order": "sequential",
  "is_turn": true
}

Codebeispiele

bash
curl -X GET "https://api.nueform.io/api/v1/s/xK9f2"

Passwort verifizieren

POST/api/v1/s/:shortCode/verify-password

Öffentlicher Endpunkt. Verifiziert das Passwort einer passwortgeschützten Signatursitzung. Gibt bei Erfolg ein temporäres Zugriffstoken zurück.

Request-Body

passwordstring

Das Sitzungspasswort.

Antwort

json
{
  "success": true,
  "access_token": "tmp_abc123..."
}

Fehlerantwort (401)

json
{
  "error": "Invalid password"
}

Codebeispiele

bash
curl -X POST "https://api.nueform.io/api/v1/s/xK9f2/verify-password" \
  -H "Content-Type: application/json" \
  -d '{"password": "mySecretPass123"}'
Zuletzt aktualisiert: 20. Juli 2026