Firma.dev API v1.3 + v1.4: Neue Feldtypen, Benutzerdefinierte E-Mail-Domains und Granulare Kontrolle

Wir haben zwei API-Releases direkt nacheinander veröffentlicht, nur in der letzten Woche. Nichts bahnbrechendes, aber neue Funktionen … alles im Februar 2026. 👊

Version 1.3 kam mit benutzerdefinierten E-Mail-Domains und Kostenverfolgung. Version 1.4 folgte mit drei neuen Feldtypen und granularen PATCH-Operationen für einzelne Felder.

Beide Releases teilen dasselbe Thema: mehr Kontrolle ohne mehr Komplexität. Und keines der Updates führt Änderungen ein, die Anpassungen erfordern, sodass Sie diese Features in Ihrem eigenen Tempo übernehmen können.

Wenn Sie nach einer API-Signaturlösung suchen, die Ihnen Flexibilität bietet, ohne Migrationen zu erzwingen, genau so sieht es aus.

Hier ist alles Neue in v1.3 und v1.4.

v1.4.0: Neue Feldtypen und Granulare Updates

Veröffentlichungsdatum: 31. Januar 2026

Version 1.4 erweitert, was Sie mit Dokumentfeldern tun können und wie Sie sie aktualisieren. Drei neue Feldtypen bieten mehr Möglichkeiten zur Sammlung von Daten. PATCH-Operationen unterstützen jetzt individuelle Feldaktualisierungen. Und ein neuer template_user_id-Parameter macht die Empfängermatchung explizit.

Drei Neue Feldtypen

Der Feldtyp-Enum enthält jetzt textarea, url und radio_buttons:

Der Typ radio funktioniert noch für Abwärtskompatibilität, aber radio_buttons ist der kanonische Name in Zukunft.

Der url Feldtyp

Der neue url Feldtyp erlaubt es Ihnen, klickbare Links direkt in Ihre Signaturdokumente einzubetten. Das Feld wird automatisch auf read_only: true gesetzt, da Unterzeichner den Link anklicken, anstatt ihn zu bearbeiten.

Verwenden Sie read_only_value, um die Ziel-URL festzulegen, und format_rules.urlDisplayText, um anzupassen, was die Unterzeichner sehen:

{
  "field": {
    "type": "url",
    "position": { "x": 100, "y": 200, "width": 150, "height": 30 },
    "page_number": 1,
    "read_only_value": "https://example.com/terms",
    "format_rules": { "urlDisplayText": "View Terms & Conditions" }
  }
}

{
  "field": {
    "type": "url",
    "position": { "x": 100, "y": 200, "width": 150, "height": 30 },
    "page_number": 1,
    "read_only_value": "https://example.com/terms",
    "format_rules": { "urlDisplayText": "View Terms & Conditions" }
  }
}

{
  "field": {
    "type": "url",
    "position": { "x": 100, "y": 200, "width": 150, "height": 30 },
    "page_number": 1,
    "read_only_value": "https://example.com/terms",
    "format_rules": { "urlDisplayText": "View Terms & Conditions" }
  }
}

Verwendungsfall: Eingebettete Bedingungen und Richtlinien. Wenn Ihr Signaturfluss verlangt, dass Unterzeichner die Geschäftsbedingungen, Datenschutzrichtlinien oder externe Verträge anerkennen, hält der url Feldtyp alles in einem Dokument. Unterzeichner klicken auf den Link, überprüfen den referenzierten Inhalt und setzen die Signatur fort. Es ist nicht notwendig, mehrere PDFs beizufügen oder Unterzeichner auf externe Seiten umzuleiten, bevor sie den Workflow abschließen können.

Dies ist besonders nützlich für SaaS-Plattformen, bei denen sich die Bedingungen häufig ändern. Aktualisieren Sie die verlinkte URL einmal, und jede neue Anfrage zur Unterzeichnung weist auf die aktuelle Version.

Der textarea Feldtyp

Der textarea Feldtyp unterstützt mehrzeilige Texteingaben. Verwenden Sie ihn, wenn Unterzeichner längere Antworten geben müssen: spezielle Anweisungen, Lieferhinweise oder jeglicher Freitext, der nicht in ein einzeiliges text Feld passt.

PATCH-Operationen für Einzelne Felder

Bisher bedeutete das Aktualisieren eines einzelnen Feldes in einer Vorlage, dass die gesamte Vorlage gesendet oder der umfassende PUT-Endpunkt verwendet werden musste. Jetzt unterstützen sowohl Vorlagen- als auch Anforderungs-PATCH-Endpunkte Einzeloperationsfelder.

Vorlagen-PATCH (PATCH /templates/{id}) kann aktualisieren:

• Vorlageneigenschaften

• Einen einzelnen Benutzer

• Ein einzelnes Feld (neu in v1.4)

Anforderungs-PATCH (PATCH /signing-requests/{id}) kann aktualisieren:

• Anforderungseigenschaften

• Einen einzelnen Empfänger

• Ein einzelnes Feld (neu in v1.4)

Um ein neues Feld zu erstellen, schließen Sie das field-Objekt ohne eine id ein:

{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}

{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}

{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}

Um ein bestehendes Feld zu aktualisieren, fügen Sie die field.id hinzu:

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

Dieser granulare Ansatz vereinfacht das Feldmanagement, wenn Sie die Position eines einzelnen Feldes anpassen, den erforderlichen Status eines Feldes ändern oder ein neues Feld hinzufügen müssen, ohne die gesamte Vorlagen-Nutzlast zu rekonstruieren.

Vorlagen-Benutzermatchung mit template_user_id

Bei der Erstellung von Anfragen aus Vorlagen können Sie jetzt template_user_id verwenden, um Empfänger explizit mit Vorlagenbenutzern abzugleichen:

{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}

{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}

{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}

Vor v1.4 basierte das Empfängermatching auf dem order-Attribut. Das funktioniert weiterhin als Rückfallebene, aber template_user_id beseitigt Unklarheiten. Wenn Ihre Vorlage mehrere Unterzeichner hat und Sie garantieren möchten, dass Jane die Rolle als "Käuferin" (nicht die Rolle als "Verkäuferin") erhält, sorgt das explizite Matching dafür, dass die richtige Person die richtigen Felder bekommt.

v1.4 Schemaänderungen

Feldtyp-Enum aktualisiert von:

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]

Zu:

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]

Empfänger-Schema enthält jetzt template_user_id für explizites Matchen von Vorlagenbenutzern bei Erstellung von Anfragen.

v1.3.0: Benutzerdefinierte E-Mail-Domains und Verwendungssichtbarkeit

Version 1.3 führte die E-Mail-Domains-API für White-Label-E-Mail-Versand, Kostenverfolgung zur Sichtbarkeit der Nutzung und Ablehnungsstatus für Anfragen ein.

E-Mail-Domains API

Eine komplette API-Kategorie zur Konfiguration von benutzerdefinierten E-Mail-Domains. Anstatt dass Signaturanfragen von noreply@Firma.dev gesendet werden, können sie von signing@IhrMarke.com kommen.

Acht neue Endpunkte:

Neue Schemata:

• Domain: E-Mail-Domänenkonfiguration mit Verifizierungsstatus

• DomainDnsRecord: DNS-Eintragsdetails zur Domain-Verifizierung

Der Verifizierungsablauf funktioniert wie die meisten E-Mail-Domäneneinrichtungen: Fügen Sie Ihre Domain hinzu, verifizieren Sie das Eigentum mit einem TXT-Eintrag, konfigurieren Sie SPF/DKIM/DMARC, schließen Sie mit dem E-Mail-Anbieter ab und setzen Sie Ihre Hauptsendedomäne.

Verwendungsfall: White-Label-Signaturanfragen. Wenn Sie eine elektronische Signatur-API-Integration für Ihr SaaS-Produkt entwickeln, erwarten Ihre Kunden, dass E-Mails von Ihrer Marke kommen. Eine Signaturanfrage von contracts@IhrPlattform.com baut Vertrauen auf. Eine E-Mail von noreply@Firma.dev wirft Fragen auf.

Benutzerdefinierte E-Mail-Domains passen gut zu Customer Workspaces für vollständige White-Label-Bereitstellungen. Jeder Ihrer Kunden erhält einen isolierten Arbeitsbereich mit Vorlagen und Signaturanfragen, die in der Unterzeichnererfahrung niemals Firma.dev referenzieren.

Für einen tieferen Einblick in White-Labeling-Optionen, siehe unsere Anleitungen zu White-Label-Dokumentensignatur-API und White-Label-E-Signatur-E-Mails.

Kostenverfolgung

Zwei neue Felder bieten Sichtbarkeit in die Kreditnutzung:

• credit_cost im Template-Schema: Anzahl der Credits, die beim Senden einer Signaturanfrage aus dieser Vorlage verbraucht werden

• credit_cost im SigningRequest-Schema: Credits, die beim Senden dieser Signaturanfrage verbraucht wurden

Eine neue Arbeitsbereichseinstellung, show_credit_cost_in_editor, lässt Sie umschalten, ob Kreditkosten im eingebetteten Vorlagen- und Signaturanfragen-Editor angezeigt werden.

Dies ist wichtig für SaaS-Plattformen, die Kosten an Kunden weitergeben oder die Nutzung pro Arbeitsbereich verfolgen müssen. Da Kreditkosten auf Vorlage- und Signaturanfragenebene sichtbar sind, können Sie Abrechnungs-Dashboards erstellen, Nutzungswarnungen festlegen oder Kunden ihren Verbrauch anzeigen, ohne separate Analytik-Endpunkte abfragen zu müssen.

Bei einem Preis von $0,029 pro Umschlag bleiben die Kosten vorhersehbar. Aber die Sichtbarkeit davon, wohin diese Credits gehen, hilft Ihnen, zu optimieren.

Abgelehnter Status für Signaturanfragen

Signaturanfragen unterstützen jetzt einen declined-Status:

• declined zum SigningRequest.status-Enum-Werte hinzugefügt

• date_declined-Feld zum SigningRequest-Schema hinzugefügt

Wenn ein Unterzeichner ablehnt zu signieren, wird dies im Status und Zeitstempel reflektiert. Dies ergänzt die declined_on- und decline_reason-Felder bei SigningRequestUser, die in v1.2 eingeführt wurden.

v1.3 Schema-Verbesserungen

Vorlagenfelder:

• date_default-Feld zum Standardisieren von Datumsvorgaben (ISO 8601 Format)

• Verstärkte multi_group_id-Beschreibung zur Erklärung gegenseitig exklusiver Feldgruppen für Checkboxen und Radio-Buttons

• Klarstellung, dass page_number 1-indiziert ist und nicht die Dokumentseitenzahl überschreiten darf

Signaturanfragefelder:

• Gleiche multi_group_id-Verbesserungen wie bei den Vorlagenfeldern

Migrationshinweise

Weder v1.3 noch v1.4 führen Änderungen ein, die Anpassungen erfordern.

Migrieren von v1.2 auf v1.3:

• E-Mail-Domänenkonfiguration ist verfügbar, aber optional

• declined-Status zur Signaturanfrage-Status-Enum hinzugefügt

• Kostenverfolgung bei Vorlagen und Signaturanfragen verfügbar

Migrieren von v1.3 auf v1.4:

• radio-Feldtyp zu radio_buttons umbenannt (beide zur Abwärtskompatibilität akzeptiert)

• Neue PATCH-Funktionen für granulare Feldaktualisierungen

• template_user_id verfügbar für explizite Empfängermatching

Sie können diese Features schrittweise übernehmen. Bestehende Integrationen funktionieren weiterhin ohne Änderungen.

Bauen Sie Ihre Elektronische Signatur-API-Integration

irma.dev ist für Entwickler gemacht, die Dokumentensignatur zu ihren Produkten hinzufügen müssen, ohne den Aufwand von Unternehmensverträgen oder komplexen Integrationen. Pay-as-you-go-Preise bei $0.029 pro Umschlag. Keine Mindestvoraussetzungen. Keine Verträge.

Diese Releases spiegeln wider, was wir von Kunden hören: mehr Feldflexibilität, besseres White-Labeling und granulare Kontrolle über Vorlagen und Signaturanfragen.

Sehen Sie sich das vollständige API-Changelog für Versionsverlauf und Migrationsanleitungen an. Oder starten Sie jetzt mit dem Bauen.

Starten Sie kostenlos mit Firma.dev – keine Kreditkarte erforderlich.