sproof Sign: Pre-filling form fields via workflows (API)

Hello developer,

we are pleased to show you how to seamlessly integrate our signature solution into your applications and prefill form fields directly when starting a signature workflow.

With these endpoints you can send signature requests where a document is merged with a preconfigured workflow. You can dynamically enrich form fields with data via the fieldValues array and specify whether recipients are still allowed to edit these values.

This example walks you through the process of creating a new workflow with form fields, assigning fieldIds, inviting recipients, passing the fieldValues array, receiving status updates including field data via a callback, and reading out the document.

1. Create a workflow via the UI, configure signature positions & form fields and obtain the WorkflowId

First you can conveniently create a workflow via our user interface:

1. Navigate to Contacts & Workflows → Workflows.

2. Click on Create new workflow.

3. Document: Upload a document there to be able to set the various options. When collecting signatures with the workflow, either the document stored in the workflow can be used, or a different document can be provided in the request body at the time of inviting.

4. Person placeholders:

   • Person placeholders must be defined. It is important that these correspond exactly to the number of recipients to be invited later.

   • Settings for the person placeholders such as role on the document, signature type, or order can be made here.

   • Determine the signature position by dragging the signature card to the desired spot in the document.

   • Each placeholder is assigned an index (starting at 1). When you send the API request, index: 1 refers to the first person placeholder you created in the UI.

5. Assign form fields & fieldId:

   • Drag one of the supported form fields onto the document.

   • Open the form field settings for the respective field.

   • In the attribute Field ID (fieldId) enter a unique value for each field that should be prefilled automatically via the API. This value serves as the key to reference the field uniquely in the API request.

   • Supported field types: textBox, textBoxMultiline, checkBox, iban, date.

6. Other settings: Other settings such as email settings, reminders and due dates can also be defined once here in the workflow.

After the workflow is saved, the workflowId can be copied from the URL. This corresponds to the trailing part of the link: https://sign.sproof.com/#/workflowEditor/bb03b2627660b90dd1152ea957f949c300703195adc519afe5550d4e0def638b81ed50

This workflowId (bb03b2627660b90dd1152ea957f949c300703195adc519afe5550d4e0def638b81ed50 in the example) is needed for the invitation in step three.

2. Invite recipients via the workflow and prefill form fields

As soon as you have your workflowId and the prepared document ready, you can start the request.

Choose the correct endpoint depending on whether it is a document or a document envelope

• POST /invite-recipients-with-workflowAPI Docs

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

The fieldValues array

The fieldValues array is passed as an additional top-level property in the request body:

Example request body

JSON

{
  "token": "{{token}}",
  "workflowId": "bb03b2627660b90dd1152ea957f949c300703195adc519afe5550d4e0def638b81ed50",
  "data": "{{pdf_in_base64_format}}",
  "callbackUrl": "https://webhook.site/your-own-callback-url",
  "fileName": "Important Contract",
  "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: Your API token

• workflowId: The ID of the workflow copied from the URL.

• data: The document as a Base64 string

• callbackUrl: URL for status updates and field data

• fileName: The file name of the document

• sender: Information about the sender.

• recipients: List of recipients including the position index from the UI workflow

• fieldValues: List of prefilled fields including key (fieldId), value and readOnly status.

3. Receive callback notifications

As soon as a document is signed or a recipient rejects it, we send a POST request to the URL you provided in callbackUrl.

All field data will be delivered automatically when a callback URL is configured – in the same structure as the response of the GET endpoint below (including the top-level boxes array and the recipient-specific members[n].boxes arrays).

4. Query document and field data

To query the current field data and the document, you can use the memberId of the sender.

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

• Replace {{memberId}} with the id of the sender that you received in the response from step 2 under responseObject.documents[0].member.id.

• Replace {{token}} again with your API token.

Structure of form fields in the response

• New top-level boxes array (general form fields): Form fields that are not assigned to a specific recipient are returned in the top-level boxes array directly on the document object.

• boxes array per member (individual form fields): Form fields assigned to a specific recipient are returned in members[n].boxes.

Full response example

{
  "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": "First name"
    },
    {
      "id": "familyName",
      "fieldId": "xxx",
      "value": "Mustermann",
      "type": "textBox",
      "label": "Last name"
    },
    {
      "id": "iban",
      "fieldId": "xxx",
      "value": "AT61 1904 3002 3457 3201",
      "type": "ibanBox",
      "label": "IBAN"
    },
    {
      "id": "notes",
      "fieldId": "xxx",
      "value": null,
      "type": "textBoxMultiLine",
      "label": "Notes"
    }
  ],
  "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": "Prefilled value",
          "type": "textBox",
          "label": "Recipient-specific field"
        }
      ]
    }
  ],
  "allSignersSigned": false,
  "allMembersSigned": false
}

We hope this example helps you get started with your integration for prefilling form fields!

If you have any questions, we are happy to assist you

Last updated: September 04, 2026