Hello developer,
we are pleased to show you how to seamlessly integrate our signature solution into your applications.
With this endpoint you can send signature requests where a dynamic document is merged with a preconfigured workflow.
This example walks you through the process of creating a new workflow, inviting recipients to sign documents through this workflow, receiving status updates via a callback, and finally downloading the signed document.
1. Create a workflow via the UI and obtain the WorkflowId
First, you can conveniently create a workflow via our user interface https://sign.sproof.com/#/dashboard:
-
Navigate to Contacts & Workflows → Workflows.
-
Click on Create new workflow.
Document: There you upload a placeholder document to be able to configure the various settings. 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. Collecting signatures with workflows using this endpoint works only for single documents. For document envelopes there is a separate endpoint available.
Person placeholders: Person placeholders must be defined. It is important that these match the exact number of recipients you intend to invite later. You can configure settings for the person placeholders such as role on the document, signature type, or order here. 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. The signature position is defined dynamically within the document itself (see step 2).
Further settings: Other settings like email settings, reminders, and due date can also be defined once here in the workflow.
After the workflow has been 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 required for the invitation in step three.
2. Prepare the dynamic document
Before sending the API request, you must prepare the PDF document to be signed. Instead of working with fixed coordinates, our system uses so-called text anchors.
-
Placeholder text: Place a unique text string at the location where the signature should appear (e.g.
{{signer1}}). -
Formatting: You can set the text color to white or minimize the font size to make the placeholder invisible. However, it is important that the text in the PDF remains "selectable" (technically readable).
-
Dynamic generation: You can generate these documents on the fly and place the placeholder text
{{signer1}}anywhere you like.
3. Invite recipients to sign via the workflow
Once you have your workflowId and the prepared document ready, you can start the signature request. Depending on whether you want to send the invitations immediately or first edit the document as a draft in the sproof UI, there are two different endpoints available:
Choosing the right endpoint
-
Immediate sending: Use
/invite-recipients-with-workflowif the invitation emails should be sent to all recipients (according to the workflow order) immediately after the API call. -
Prepare as draft: Use
/prepare-recipients-with-workflowif the document should only be prepared. The document will then appear in the user's sproof dashboard as a draft. Additionally, you can use theeditorUrlprovided in the API response to direct the user straight to the editor. This allows final adjustments to be made in the UI and the sending to be started manually.
The merging logic
This process performs a three-way merge: it combines your API recipient data, the signature positions in the document, and the settings from your workflow. Each object in the recipients array links these components via two identifiers:
-
The document link (
placeholderText): Assigns the recipient to a specific text string (e.g.{{signer1}}) in your PDF to determine the signature position. -
The workflow link (
index): Links the recipient to a "person placeholder" from your UI workflow. This ensures the recipient inherits the correct role, order, and signature type.
Endpoint: POST https://sign.sproof.com/api/v1/documents/invite-recipients-with-workflow
or
Endpoint: POST https://sign.sproof.com/api/v1/documents/prepare-recipients-with-workflow
Example request body:
{
"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",
"placeholderText": "{{signer1}}",
"index": 1
}
]
}
-
token: Your API token. -
workflowId: The workflow ID you copied earlier. -
data: As described, a different document (instead of the one stored in the workflow) can be provided at the time of inviting. This is inserted here as a Base64 string. -
callbackUrl: A required field so that we can send status updates to this URL. -
fileName: The filename of the document. -
sender: Information about the sender of the invitation. -
recipients: A list of recipients to be invited to the workflow.-
placeholderText: The text identifier that maps this recipient to the signature position set in the document (e.g.{{signer1}}). -
index: The placeholder's positional index in the workflow (starting at 1). This ensures the recipient receives the settings defined in the UI (role, signature type, etc.).
-
4. Receive callback notifications
As soon as a document is signed or a recipient declines it, we send a POST request to the URL you provided in callbackUrl. This request contains an object with relevant information about the document's status, including the memberId.
Example callback object:
{
"name": "Important Contract",
"id": "c95302c896a19179e61341740c19cbd4089600e0d83c3b4401b1e63414e55f336ba87a",
"language": "en",
"updatedAt": "2025-07-24T07:35:42.854Z",
"createdAt": "2025-07-24T07:21:54.472Z",
"signaturesTypes": [
"qualified"
],
"callbackUrl": "https://webhook.site/b27d2a2c-cb8b-42fd-b5a3-364af6f0bffe",
"returnUrl": null,
"returnBtnText": null,
"inPersonSigning": false,
"signingRound": 1,
"member": {
"id": "40e49b1ebaaaa8655ba531b5c86f3bab48d191723d8d3ac220ae8dcc12326e07695d98",
"email": "sender@sproof.com",
"firstName": "sproof",
"lastName": "Sender",
"lastActivityAt": "2025-07-24T07:21:54.482Z",
"createdAt": "2025-07-24T07:21:54.482Z",
"signed": false,
"isAdmin": true,
"isSigner": false,
"signaturePosition": [],
"signedAt": null,
"signingOrder": 1,
"declinedAt": null,
"signatures": []
},
"boxes": [],
"members": [
{
"id": "f30a1be1864f591f6720a423e64393bc274a679d9d80106dfee7f7d7c3279eb3c88368",
"isSigner": true,
"email": "max.mustermann@sproof.com",
"firstName": "Max",
"lastName": "Mustermann",
"isAdmin": false,
"signedAt": "2025-07-24T07:35:42.679Z",
"declinedAt": null,
"signingOrder": 1,
"signaturePosition": null,
"signed": true,
"signatures": [
{
"signatureType": "qes_idaustria",
"signedAt": "2025-07-24T07:35:42.679Z"
}
]
}
],
"allSignersSigned": true,
"allMembersSigned": false
}
Important note: In case of a failure, a retry mechanism is implemented to ensure the request is attempted again.
5. Download the signed document
With the memberId you receive in the callback object, you can download the signed document as a binary PDF or as a Base64-encoded file.
Endpoint: GET https://sign.sproof.com/api/v1/documents/download/{{memberId}}?token={{token}}
-
Replace
{{memberId}}with the ID you received in the callback undermember.id(40e49b1ebaaaa8655ba531b5c86f3bab48d191723d8d3ac220ae8dcc12326e07695d98in this example). -
Replace
{{token}}again with your API token.
We hope this example helps you get started with your integration!
If you have any questions, we are happy to assist you.