sproof Sign: Vorbefüllen von Formularfeldern über Workflows (API)

Hallo Entwickler:in,

wir freuen uns, Ihnen zu zeigen, wie Sie unsere Signatur-Lösung nahtlos in Ihre Anwendungen integrieren und Formularfelder direkt beim Starten eines Signatur-Workflows vorbefüllen können.

Mit diesen Endpunkten können Sie Signaturanfragen versenden, bei denen ein Dokument mit einem vorkonfigurierten Workflow zusammengeführt wird. Dabei können Sie über das fieldValues-Array Formularfelder dynamisch mit Daten anreichern und festlegen, ob Empfänger:innen diese Werte noch bearbeiten dürfen.

Dieses Beispiel führt Sie durch den Prozess, wie Sie einen neuen Workflow mit Formularfeldern erstellen, die fieldId vergeben, Empfänger:innen einladen, das fieldValues-Array übergeben, Status-Updates inkl. Felddaten über einen Callback empfangen und das Dokument auslesen.

1. Workflow via UI erstellen, Signaturpositionen & Formularfelder konfigurieren und WorkflowId erhalten

Zuerst können Sie einen Workflow bequem über unsere Benutzeroberfläche erstellen:

1. Navigieren Sie zu Kontakte & Workflows → Workflows.

2. Klicken Sie auf Neuer Workflow erstellen.

3. Dokument: Laden Sie dort ein Dokument hoch, um die verschiedenen Einstellungen treffen zu können. Beim Einholen von Signaturen mit dem Workflow kann entweder das hier im Workflow hinterlegte Dokument verwendet werden oder zum Zeitpunkt des Einladens ein anderes Dokument stattdessen im Request-Body mitgegeben werden.

4. Personen-Platzhalter:

   • Personen-Platzhalter müssen definiert werden. Hier ist wichtig, dass dies der genauen Anzahl an Empfängern entspricht, die später eingeladen werden sollen.

   • Einstellungen für die Personen-Platzhalter wie Rolle am Dokument, Signaturtyp oder Reihenfolge können hier getroffen werden.

   • Bestimmen Sie die Signaturposition, indem Sie die Signaturkarte an die gewünschte Stelle im Dokument ziehen.

   • Jedem Platzhalter wird ein Index zugewiesen (beginnend bei 1). Wenn Sie den API-Request senden, verweist index: 1 auf den ersten Personen-Platzhalter, den Sie in der Benutzeroberfläche erstellt haben.

5. Formularfelder & fieldId zuweisen:

   • Ziehen Sie eines der unterstützten Formularfelder auf das Dokument.

   • Öffnen Sie die Formularfeldeinstellungen des jeweiligen Feldes.

   • Hinterlegen Sie im Attribut Field ID (fieldId) einen eindeutigen Wert für jedes Feld, das automatisiert per API vorbefüllt werden soll. Dieser Wert dient als Schlüssel (Key), um das Feld beim API-Request eindeutig zu referenzieren.

   • Unterstützte Feldtypen: textBox, textBoxMultiline, checkBox, iban, date.

6. Weitere Einstellungen: Auch andere Einstellungen wie E-Mail-Einstellungen, Erinnerungen und Fälligkeit können hier im Workflow einmalig definiert werden.

Nachdem der Workflow gespeichert wurde, kann die workflowId aus der URL herauskopiert werden. Diese entspricht dem hinteren Teil des Links: https://sign.sproof.com/#/workflowEditor/bb03b2627660b90dd1152ea957f949c300703195adc519afe5550d4e0def638b81ed50

Diese workflowId (bb03b2627660b90dd1152ea957f949c300703195adc519afe5550d4e0def638b81ed50 im Beispiel) wird für die Einladung im dritten Schritt benötigt.

2. Empfänger über den Workflow einladen und Formularfelder vorbefüllen

Sobald Sie Ihre workflowId und das vorbereitete Dokument bereit haben, können Sie die Anfrage starten.

Die Wahl des richtigen Endpunkts - je nachdem ob es sich um ein Dokument oder eine Dokumentenmappe handelt

• POST /invite-recipients-with-workflow API-Docs

• POST /invite-recipients-with-workflow-envelope  API-Docs

Das fieldValues-Array

Das fieldValues-Array wird als zusätzliche Top-Level-Property im Request-Body mitgegeben:

Beispiel-Body des Requests

JSON

{
  "token": "{{token}}",
  "workflowId": "bb03b2627660b90dd1152ea957f949c300703195adc519afe5550d4e0def638b81ed50",
  "data": "{{pdf_im_base64_format}}",
  "callbackUrl": "https://webhook.site/ihre-eigene-callback-url",
  "fileName": "Wichtiger Vertrag",
  "sender": {
    "email": "{{email}}",
    "firstName": "sproof",
    "lastName": "Sender"
  },
  "recipients": [
    {
      "email": "max.mustermann@sproof.com",
      "firstName": "Max",
      "lastName": "Mustermann",
      "index": 1
    }
  ],
  "fieldValues": [
    {
      "key": "givenName",
      "value": "Max",
      "readOnly": true
    },
    {
      "key": "familyName",
      "value": "Mustermann",
      "readOnly": true
    },
    {
      "key": "iban",
      "value": "AT61 1904 3002 3457 3201",
      "readOnly": false
    }
  ]
}

• token: Ihr API-Token

• workflowId: Die aus der URL kopierte ID des Workflows.

• data: Das Dokument als Base64-String

• callbackUrl: URL für Status-Updates und Felddaten

• fileName: Der Dateiname des Dokuments

• sender: Informationen zum Absender.

• recipients: Liste der Empfänger:innen inkl. Positions-Index aus dem UI-Workflow

• fieldValues: Liste der vorbefüllten Felder inkl. key (fieldId), value und readOnly-Status.

3. Callback-Benachrichtigungen empfangen

Sobald ein Dokument signiert wird oder ein:e Empfänger:in es ablehnt, senden wir einen POST-Request an die von Ihnen in callbackUrl angegebene URL.

Alle Felddaten werden bei konfigurierter Callback-URL automatisch mitgeliefert – in derselben Struktur wie die Antwort des nachfolgenden GET-Endpunkts (inkl. dem allgemeinen boxes-Array und den empfängerspezifischen members[n].boxes-Arrays).

4. Dokument und Felddaten abfragen

Um die aktuellen Felddaten und das Dokument abzufragen, können Sie die memberId des Senders nutzen.

Endpunkt: GET https://sign.sproof.com/api/v1/documents/{{memberId}}?token={{token}}

• Ersetzen Sie {{memberId}} durch die id des senders, die Sie in der Response von Schritt 2 unter responseObject.documents[0].member.id erhalten haben.

• Ersetzen Sie {{token}} erneut durch Ihren API-Token.

Struktur der Formularfelder in der Response

• Neues Top-Level boxes-Array (allgemeine Formularfelder): Formularfelder, die nicht einem bestimmten Empfänger zugeordnet sind, werden im Top-Level-Array boxes direkt am Dokumentobjekt zurückgegeben.

• boxes-Array je Member (individuelle Formularfelder): Formularfelder, die einem bestimmten Empfänger zugeordnet sind, werden in members[n].boxes zurückgegeben.

Vollständiges Response-Beispiel

{
  "name": "Example File",
  "id": "c836edd65c8aadd6a853c8247b2826b5496f2b4059fa826ec1587da7426d2fd598a5e6",
  "language": "en",
  "updatedAt": "2026-05-19T06:41:45.506Z",
  "createdAt": "2026-05-19T06:34:18.588Z",
  "state": "pending",
  "member": {
    "id": "5b578cc30f082d5588cced118a0d538baa668d9775005670342bb4ce9ac69ea9fee536",
    "email": "sproof.sender@sproof.com",
    "firstName": "sproof",
    "lastName": "Sender",
    "isSigner": false,
    "signed": false,
    "signatures": []
  },
  "boxes": [
    {
      "id": "givenName",
      "fieldId": "xxx",
      "value": "Max",
      "type": "textBox",
      "label": "Vorname"
    },
    {
      "id": "familyName",
      "fieldId": "xxx",
      "value": "Mustermann",
      "type": "textBox",
      "label": "Nachname"
    },
    {
      "id": "iban",
      "fieldId": "xxx",
      "value": "AT61 1904 3002 3457 3201",
      "type": "ibanBox",
      "label": "IBAN"
    },
    {
      "id": "notes",
      "fieldId": "xxx",
      "value": null,
      "type": "textBoxMultiLine",
      "label": "Anmerkungen"
    }
  ],
  "members": [
    {
      "id": "46984342412febb9bc0d80669478b0f3e897b83346c438f1b105d4be39f7bfe02fe50f",
      "email": "max.mustermann@sproof.com",
      "firstName": "Max",
      "lastName": "Mustermann",
      "isSigner": true,
      "signed": false,
      "signaturePosition": {
        "x": 0.127,
        "y": 0.905,
        "width": 0.189,
        "height": 0.068,
        "page": 0
      },
      "signatures": [],
      "boxes": [
        {
          "id": "recipientField1",
          "fieldId": "xxx",
          "value": "Vorbefüllter Wert",
          "type": "textBox",
          "label": "Empfängerspezifisches Feld"
        }
      ]
    }
  ],
  "allSignersSigned": false,
  "allMembersSigned": false
}

Wir hoffen, dieses Beispiel hilft Ihnen beim Start Ihrer Integration zur Vorbefüllung von Formularfeldern!

Bei Fragen stehen wir Ihnen gerne zur Verfügung

Last updated: September 04, 2026