Umschläge & Empfänger

Ein Umschlag ist ein Vertrag auf dem Weg zur Unterschrift: eine mit Ihren Variablen gerenderte Vorlagenversion, die Empfänger, die daran mitwirken, und der Nachweis über alles, was geschieht. Sie erstellen einen mit POST /v1/envelopes.

Umschlag erstellen

Feld	Typ	Hinweise
`template`	`tpl_…`	Erforderlich
`version`	Zahl oder `"latest"`	Standard `latest`; wird beim Erstellen aufgelöst und festgelegt. Muss veröffentlicht sein
`variables`	Objekt	Wird gegen das JSON Schema der Version validiert
`recipients`	Array	Einer pro Rolle (`role`, `name`, `email`; optional `externalUserId`, `verification`, `fields` zum Vorbelegen nach Feld-ID, `order`, um die Signaturreihenfolge zu ändern)
`subject`, `message`	String	Werden in den Signatur-E-Mails verwendet und auf der Signaturseite angezeigt
`delivery`	`email` · `embedded` · `none`	Standard `email`
`expiresAt`	RFC 3339	Muss in der Zukunft liegen; der Umschlag läuft dann ab, und Signatur- und Beobachterlinks funktionieren nicht mehr
`cc`	Array	Zusätzliche CC-Empfänger (`name`, `email`) über die CC-Rollen der Vorlage hinaus; bis zu 50
`viewers`	Array	Personen, die den Umschlag verfolgen, ohne zu unterschreiben (`name`, `email`, optional `notifyOnSignature`); Anzahl pro Umschlag je nach Tarif begrenzt
`viewerDocumentAccess`	Boolean	Beobachter dürfen das Dokument auf ihrer Statusseite öffnen. Standard `false` (nur Status); ab dem Team-Tarif
`reminders`	Objekt	`{ "enabled": false }` schaltet Erinnerungen aus; `{ "enabled": true, "intervalHours": 24 }` ändert das Intervall (1 bis 720)
`externalId`	String	Ihre eigene ID, bis zu 200 Zeichen
`dedupeOn`	`"external_id"`	Gibt den vorhandenen Umschlag mit dieser `externalId` zurück, statt einen weiteren zu erstellen
`metadata`	Objekt aus Strings	Bis zu 500 Zeichen pro Wert; wird am Umschlag und in Webhooks zurückgegeben

Jeder Empfänger braucht eine Rolle der Version; jede Nicht-CC-Rolle braucht genau einen Empfänger. Fehler werden gemeinsam gemeldet, mit Pointern wie /recipients/1/role oder /recipients/0/fields/start_date.

Antworten: 201 mit dem Umschlag und einem Location-Header; 200 mit dem vorhandenen Umschlag und x-deduplicated: true, wenn dedupeOn gegriffen hat; 200 mit einer Zusammenfassung des Probelaufs bei ?dry_run=true; 402, wenn ein Free-Workspace seine enthaltenen Umschläge verbraucht hat; 403 plan-upgrade-required, wenn die Beobachter das Kontingent des Tarifs überschreiten oder viewerDocumentAccess nicht im Tarif enthalten ist (Tarife & Limits). Auch Probeläufe prüfen die Limits des Tarifs.

Jedes nach der ersten Version hinzugekommene Feld ist optional: Eine Anfrage ohne diese Felder verhält sich genau wie zuvor.

Optionen beim Senden

Die Vorlage legt fest, wer in welcher Reihenfolge unterschreibt. Für einen einzelnen Umschlag können Sie das ändern, ohne die Vorlage anzufassen:

{
  "template": "tpl_9fK2mQ7xLp",
  "variables": { "client": { "name": "Jane Doe" } },
  "recipients": [
    { "role": "client", "name": "Jane Doe", "email": "jane@acme.dev", "order": 2 },
    { "role": "company", "name": "Sam Lee", "email": "sam@bonafide.dev", "order": 1 },
    { "role": "witness", "name": "Kim Park", "email": "kim@acme.dev", "order": 1 }
  ],
  "cc": [{ "name": "Legal", "email": "legal@acme.dev" }],
  "viewers": [{ "name": "Alex Chen", "email": "alex@acme.dev", "notifyOnSignature": true }],
  "reminders": { "enabled": true, "intervalHours": 48 },
  "expiresAt": "2026-11-30T23:59:59Z"
}

Reihenfolge: recipients[].order ist der Schritt, in dem der Empfänger unterschreibt; Empfänger mit derselben Zahl unterschreiben gleichzeitig. Ohne Angabe gilt die order der Rolle aus der Vorlage. Reihenfolgen sind positive ganze Zahlen; CC-Rollen lassen sich nicht einordnen; jede Rolle braucht weiterhin ihren Empfänger (damit die Felder der Vorlage ihren Unterzeichner behalten); mindestens ein Empfänger muss unterschreiben. Das Event envelope.created hält routingOverridden: true fest.
CC: Zusätzliche CC-Empfänger erhalten die E-Mail mit dem abgeschlossenen Dokument und unterschreiben nie. Sie erscheinen in recipients mit kind: "cc" und der Rolle _cc.
Erinnerungen: Wer an der Reihe ist, wird alle intervalHours erinnert (Standard: das REMINDER_INTERVAL_HOURS der Installation, 72), höchstens dreimal; enabled: false sendet keine. Erinnerungen gelten für die Zustellung per email.
Authentifizierung der Unterzeichner erfolgt pro Empfänger: verification überschreibt die Methode der Rolle. Verfügbar sind derzeit none (nur der eindeutige Signaturlink, Standard für Rollen ohne eigene Angabe) und email_otp (der Link plus ein per E-Mail gesendeter Code); passkey und id_check werden als noch nicht verfügbar abgelehnt. Siehe Verifizierung der Unterzeichner.
Sprache: locale an einem Empfänger, CC oder Beobachter (oder am Umschlag, für alle ohne eigene Angabe) legt die Sprache der Signaturseite und der E-Mails fest, eine der 50 Signatursprachen. Ohne Angabe richtet sich die Signaturseite nach dem Browser, und E-Mails sind auf Englisch.

Der Sendebildschirm im Dashboard bietet dieselben Optionen: Schritte nach vorn oder hinten verschieben, Gleichzeitig unterschreiben ankreuzen, CCs und Beobachter hinzufügen, für jeden Unterzeichner Authentifizierung (Nur E-Mail-Link oder E-Mail-Link + Code) und Sprache wählen sowie ein Ablaufdatum und einen Erinnerungsplan festlegen.

Zustellung

email: Jeder Empfänger erhält per E-Mail einen Link zur gehosteten Signaturseite, sobald er an der Reihe ist. Empfänger, die noch nicht unterschrieben haben, werden alle paar Tage erinnert (bis zu dreimal), und alle erhalten eine E-Mail, wenn der Umschlag abgeschlossen ist.
embedded: keine E-Mail an Unterzeichner. Erzeugen Sie eine Signatursitzung, wenn der Unterzeichner in Ihrem Produkt ist. Beobachter erhalten ihren Statuslink weiterhin per E-Mail.
none: überhaupt keine E-Mail (auch nicht an Beobachter); verwenden Sie dies, wenn Sie Links selbst zustellen (gehostete Sitzungen).

POST /v1/envelopes/{id}/recipients/{recipient}/resend sendet einem Empfänger, der an der Reihe ist, einen neuen Link per E-Mail (höchstens einmal pro Minute).

Lebenszyklus

          ┌──────────── declined (a signer declined)
          │
sent ─────┼──────────── voided   (POST /v1/envelopes/{id}/void)
          │
          ├──────────── expired  (expiresAt passed)
          │
          └──────────── completed ──► seal: pending ──► sealed

`status`	Bedeutung
`rendering`	Wird vorbereitet
`sent`	In Bearbeitung: Empfänger unterschreiben in Routing-Reihenfolge
`completed`	Alle Empfänger sind fertig. Die Versiegelung beginnt
`declined`	Ein Empfänger hat abgelehnt; der Umschlag endet
`voided`	Sie haben ihn storniert (`{ "reason": "…" }`); offene Signatursitzungen funktionieren nicht mehr
`expired`	`expiresAt` ist vor dem Abschluss verstrichen

seal verfolgt das versiegelte PDF: not_started, pending (abgeschlossen, wird versiegelt), sealed oder failed. Die Versiegelung blockiert nie den Abschluss: Der Umschlag wird zuerst abgeschlossen und direkt danach versiegelt.

Empfänger und Routing

{
  "id": "rcp_5Jw0pLs9Xe",
  "role": "client",
  "name": "Jane Doe",
  "email": "jane@acme.dev",
  "order": 1,
  "status": "viewed",
  "verification": "email_otp",
  "completedAt": null
}

Der status eines Empfängers ist pending (noch nicht an der Reihe), sent, viewed, completed oder declined, und kind ist der Typ der Rolle: signer, approver, form_filler oder cc. Das Routing erfolgt nach order (der Rolle oder der Überschreibung beim Senden): Alle Empfänger der niedrigsten nicht abgeschlossenen Stufe handeln parallel, und die nächste Gruppe beginnt, wenn sie fertig sind. CC-Empfänger blockieren das Routing nie.

Beobachter

Ein Beobachter verfolgt einen Umschlag, ohne zu unterschreiben: eine Führungskraft, eine Rechtsanwaltsfachkraft, der Account-Verantwortliche auf Kundenseite. Beobachter sind keine Empfänger. Sie haben keine Rolle und sind nie an der Reihe, blockieren oder beenden nichts und erscheinen nie in der Liste der Unterzeichner auf dem Zertifikat.

Wenn der Umschlag gesendet wird (oder wenn Sie Beobachter später mit POST /v1/envelopes/{id}/viewers hinzufügen), erhält jeder Beobachter eine E-Mail in Ihrem Branding mit einem Link zu einer schreibgeschützten Statusseite: Titel des Umschlags, Absender, jeder Schritt mit Namen, Rollen, Status und Zeitstempeln seiner Empfänger, live aktualisiert, während unterschrieben wird. E-Mail-Adressen der Empfänger werden nicht angezeigt.
Beobachter erhalten erneut eine E-Mail, wenn der Umschlag abgeschlossen, abgelehnt oder storniert wird, und nach jeder Unterschrift, wenn notifyOnSignature auf true steht (standardmäßig aus).
Das Dokument ist nur auf der Seite, wenn Sie viewerDocumentAccess: true setzen (ab dem Team-Tarif): während der Bearbeitung das Original, nach der Versiegelung das versiegelte PDF. Andernfalls sehen Beobachter nur den Status.
DELETE /v1/envelopes/{id}/viewers/{viewer} widerruft einen Beobachter: Jeder an ihn gesendete Link funktioniert sofort nicht mehr.
Die Links sind persönliche Capability-URLs. Gespeichert wird nur ein SHA-256 jedes Link-Tokens. Ein Link funktioniert, bis der Umschlag abläuft (höchstens 90 Tage), noch 30 Tage nach Abschluss des Umschlags und nie mehr, sobald der Beobachter widerrufen ist.
Hinzufügen, Öffnen (erster Aufruf der Seite und des Dokuments) und Widerrufen werden im Audit-Trail als viewer.added, viewer.viewed, viewer.document_viewed und viewer.revoked erfasst und damit auch auf dem Zertifikat.

Die Antworten für einzelne Umschläge (Erstellen, Abrufen, Stornieren) führen sie auf:

{
  "viewers": [
    {
      "id": "vwr_2Hc8sQ1nVt",
      "name": "Alex Chen",
      "email": "alex@acme.dev",
      "notifyOnSignature": true,
      "status": "active",
      "invitedAt": "2026-10-13T13:58:04.512Z",
      "firstViewedAt": "2026-10-13T14:05:41.090Z",
      "lastViewedAt": "2026-10-13T15:12:09.337Z",
      "revokedAt": null,
      "createdAt": "2026-10-13T13:58:04.512Z"
    }
  ],
  "viewerDocumentAccess": false
}

Die Zahl der Beobachter pro Umschlag hängt vom Tarif ab (Free 1, Pay-as-you-go 2, Team 5, Business 20, Platform unbegrenzt); CC-Empfänger zählen nicht mit. Widerrufene Beobachter geben ihren Platz frei.

Dokumente

GET /v1/envelopes/{id}/document?version=… lädt ein PDF herunter, mit seinem SHA-256 in x-document-sha256:

`version`	Datei
`original` (Standard)	Das gerenderte Dokument, wie es zur Unterschrift versendet wurde
`sealed`	Das endgültige PDF: Werte eingebettet, Abschlusszertifikat angehängt, Dokumentzeitstempel. Nach `envelope.sealed`
`certificate`	Nur das Abschlusszertifikat

Der documentHash des Umschlags ist der SHA-256 des Originals, sealedDocumentHash der der versiegelten Datei; genau diese Werte schlägt die Verifizierung nach.

Audit-Trail

Jede Aktion ist ein Event in einer Hash-Kette pro Umschlag: hash = SHA-256(prevHash ‖ canonical JSON of the event), wobei der erste prevHash aus 64 Nullen besteht. GET /v1/envelopes/{id}/events liefert die Events und prüft die Kette:

{
  "data": [
    {
      "id": "evt_…",
      "envelope": "env_8Gm2kQ4rT1",
      "seq": 1,
      "type": "envelope.created",
      "createdAt": "2026-10-13T13:58:04.512Z",
      "recipient": null,
      "actor": { "kind": "api_key", "id": "…", "name": null, "email": null },
      "ip": "203.0.113.7",
      "userAgent": null,
      "data": { "template": "tpl_…", "templateVersion": 3, "documentHash": "9f2c…" },
      "hash": "4b1d…",
      "prevHash": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  ],
  "chain": { "valid": true, "brokenAt": null }
}

Neben den Webhook-Eventtypen enthält der Trail reine Audit-Einträge wie session.created, recipient.verified, recipient.reminded und die Beobachter-Events (Akteurtyp viewer, wenn ein Beobachter seine Seite öffnet).

Für einen Live-Status in einer Oberfläche ist GET /v1/envelopes/{id}/events/stream ein Server-Sent-Events-Stream: Der Eventname jedes Frames ist der type des Events und seine ID die seq; verbinden Sie sich mit Last-Event-ID erneut, um fortzufahren.

Auflisten

GET /v1/envelopes filtert nach status, seal, template und q (Freitext über Namen und E-Mail-Adressen der Empfänger, externalId und die Umschlag-ID). Wie jede Liste ist sie Cursor-paginiert:

{ "data": [ … ], "hasMore": true, "nextCursor": "…" }

Übergeben Sie nextCursor als cursor zurück; limit liegt zwischen 1 und 100 (Standard 20).