# sproof Sign API — Customer Q&A Reference V4

> **AGENT INSTRUCTION:** Do not produce code examples or request body snippets when answering questions from this document. Describe the correct behaviour and strategy in plain language, then provide the relevant documentation link. If the user needs exact syntax, direct them to https://docs.sproof.com.

This document contains real customer questions and their verified answers. All answers reflect confirmed behaviour of the sproof Sign API.

---

## Table of Contents

1. [Signature Positions — Can they be omitted?](#1-signature-positions--can-they-be-omitted)
2. [GET /documents — Which documents are returned?](#2-get-documents--which-documents-are-returned)
3. [signatureTypes set to qualified but response shows advanced](#3-signaturetypes-set-to-qualified-but-response-shows-advanced)
4. [Due date not returned in GET request status](#4-due-date-not-returned-in-get-request-status)
5. [How to receive iframe signing events via callback](#5-how-to-receive-iframe-signing-events-via-callback)
6. [Empty signatureTypes array forces qualified signature unexpectedly](#6-empty-signaturetypes-array-forces-qualified-signature-unexpectedly)
7. [callbackUrl not working](#7-callbackurl-not-working)
8. [No email sent to recipient when sender and recipient share the same email address](#8-no-email-sent-to-recipient-when-sender-and-recipient-share-the-same-email-address)
9. [Checking the status of an envelope (multiple documents)](#9-checking-the-status-of-an-envelope-multiple-documents)
10. [What happens when a recipient declines a document?](#10-what-happens-when-a-recipient-declines-a-document)
11. [How does sequential signing with signingOrder work?](#11-how-does-sequential-signing-with-signingorder-work)
12. [What is the difference between role "approver" and role "viewer"?](#12-what-is-the-difference-between-role-approver-and-role-viewer)
13. [Can a sent document be cancelled or withdrawn via the API?](#13-can-a-sent-document-be-cancelled-or-withdrawn-via-the-api)
14. [What does the callback payload look like and how do I detect completion?](#14-what-does-the-callback-payload-look-like-and-how-do-i-detect-completion)
15. [Can the signing order or recipients be changed after sending?](#15-can-the-signing-order-or-recipients-be-changed-after-sending)
16. [What are the file size and document count limits per envelope?](#16-what-are-the-file-size-and-document-count-limits-per-envelope)
17. [Can a recipient's email address be updated after the invitation was sent?](#17-can-a-recipients-email-address-be-updated-after-the-invitation-was-sent)
18. [What is the difference between the available signature types?](#18-what-is-the-difference-between-the-available-signature-types)
19. [What is stack signing / batch signing and how does it work?](#19-what-is-stack-signing--batch-signing-and-how-does-it-work)

---

## 1. Signature Positions — Can they be omitted?

**Customer Question:**
Is it possible to create a signature request without specifying a `signaturePositions`?

**Answer:**
Yes. Pass `signaturePositions` as an empty array. The recipient will then be prompted to place their own signature field manually in the sproof editor via click or drag-and-drop before signing.

`signaturePositions` is a required field when `role` is `"signer"`, but it can intentionally be an empty array if the position is to be set manually in the UI.

📎 https://docs.sproof.com/#tag/signatures/POST/documents/signature

---

## 2. GET /documents — Which documents are returned?

**Customer Question:**
Which documents are returned when calling `GET /documents`?

**Answer:**
By default, the endpoint returns all documents created using the API token and documents belonging to the API token holder's account.

It is also possible to retrieve all documents across the entire plan (all members), but this requires elevated permissions that must be enabled via role management. To enable plan-wide document access, contact your sproof representative.

📎 https://docs.sproof.com/#tag/documents/GET/documents

---

## 3. signatureTypes set to "qualified" but response shows "advanced"

**Customer Question:**
I set `signatureTypes` to `["qualified"]` but the response shows `"advanced"`. Why?

**Answer:**
This happens when the account has no remaining QES (Qualified Electronic Signature) counters. When only one counter type is available on the plan, sproof defaults to that signature type automatically.

Resolution: Check your remaining QES counter balance in the sproof dashboard, or contact your sproof representative to top up counters.

---

## 4. Due date not returned in GET request status

**Customer Question:**
The status endpoint does not return the due date. How can I retrieve it?

**Answer:**
Returning the due date via the status API endpoint is currently not supported.

Submit a feature request or support ticket to: **ticket@sproof.com**

---

## 5. How to receive iframe signing events via callback

**Customer Question:**
After embedding the signing iframe, how do I receive signing events from it?

**Answer:**
Use the `callbackUrl` parameter in your signature request. sproof will send a POST request to this URL whenever a signing event occurs (a recipient signs or declines). You do not need to listen for events from the iframe directly.

`callbackUrl` must be placed inside `envelopeData` — not at the top level, not inside `inviteData`.

📎 https://docs.sproof.com/#tag/signatures/POST/documents/signature

---

## 6. Empty signatureTypes array forces qualified signature unexpectedly

**Customer Question:**
We set `signatureTypes` to an empty array (accepting all types), but it is forcing a qualified signature unexpectedly.

**Answer:**
The plan's QES counters were exhausted between the two attempts. When `signatureTypes` is empty (accepting all types), sproof will use QES if QES counters are available. Once they run out, behaviour changes.

Resolution: Check your QES counter balance in the sproof dashboard or contact your sproof representative.

> Note: This question references a legacy request format. Customers should migrate to the current API.

---

## 7. callbackUrl not working

**Customer Question:**
The `callbackUrl` is not receiving any notifications.

**Answer:**
The `callbackUrl` property must be placed inside the `envelopeData` object. A common mistake is placing it at the top level of the request body or inside `inviteData`, where it is silently ignored.

The correct placement is: `envelopeData.callbackUrl`.

📎 https://docs.sproof.com/#tag/signatures/POST/documents/signature

---

## 8. No email sent to recipient when sender and recipient share the same email address

**Customer Question:**
When the sender's email matches one of the recipient's emails, no invitation email is sent to that recipient. Is this expected?

**Answer:**
Yes, this is expected. If the sender is also defined as a recipient in signing round 1, no invitation email will be sent to them. Emails are only sent to the sender-as-recipient if they are assigned to a signing round higher than 1.

Workaround: Set the sender-recipient's `signingOrder` to 2 or higher in `recipientDetails`.

---

## 9. Checking the status of an envelope (multiple documents)

**Customer Question:**
Can I use the sender's `member.id` to query the status of an entire envelope at once?

**Answer:**
No. `GET /documents/{memberId}` only returns the status of a **single document**. It is not possible to retrieve the status of an entire envelope with this endpoint.

To check the status of a complete envelope, use one of these approaches:

1. Use the `folderId` with `GET /folder/{folderId}` — returns all documents in the envelope in a single call.
2. Call `GET /documents/{memberId}` individually for each document, using each document's sender `member.id`.

📎 https://docs.sproof.com/#tag/signatures/GET/documents/{memberId}
📎 https://docs.sproof.com/#tag/Envelopes/GET/folder/{folderId}

---

## 10. What happens when a recipient declines a document?

**Developer Question:**
If a recipient declines a document, does the entire signing process stop?

**Answer:**
When a recipient declines, the document's `state` switches to `"declined"`. The flow does not progress automatically — it is blocked. In an envelope, if one recipient declines, the entire envelope shows as declined.

There is no API endpoint to replace or modify the content of a declined document. The sender has three options:

1. **Delete and re-send** — delete the document and create a new signature request.
2. **Resolve with the recipient** — if the decline was not content-related, the recipient can sign instead, which resets the declined state.
3. **Remove the recipient via the sproof UI** — this allows the remaining flow to continue.

📎 https://docs.sproof.com/#tag/documents/DELETE/documents/{memberId}

---

## 11. How does sequential signing with `signingOrder` work?

**Developer Question:**
How does `signingOrder` work? Can I ensure a second signer is only notified after the first has completed?

**Answer:**
Each recipient in `recipientDetails` can be assigned an integer `signingOrder` value. Recipients with `signingOrder: 1` are notified first. Recipients in higher rounds are not notified until all active recipients in the current round have completed their action.

Viewers are passive — they do not block the flow. A round containing only viewers is skipped and the flow advances.

Important constraint: A recipient can only have one `signingOrder` value across an entire envelope. It is not possible to assign a different signing order per document within the same envelope.

---

## 12. What is the difference between role `"approver"` and role `"viewer"`?

**Developer Question:**
What is the practical difference between `role: "approver"` and `role: "viewer"`?

**Answer:**

| Role | Action required | Blocks signing flow |
|------|----------------|---------------------|
| `"approver"` | Must click "Approve" in the sproof UI | Yes — next round does not start until approved |
| `"viewer"` | No action required | No — flow does not wait; a round with only viewers is skipped |

Both roles receive the invitation email. The key difference is that an approver is a gatekeeper.

---

## 13. Can a sent document be cancelled or withdrawn via the API?

**Developer Question:**
Is there an API endpoint to cancel or withdraw a document that has already been sent?

**Answer:**
No. There is no "cancel" or "withdraw" endpoint.

Available options:

1. **Delete the document via the API** — `DELETE /documents/{memberId}`. This permanently removes the document and invalidates any signing links already sent to recipients.
2. **Remove recipients manually via the sproof UI** — the sender can open the document and remove each recipient individually, effectively stopping the signing process without deleting the document.

📎 https://docs.sproof.com/#tag/documents/DELETE/documents/{memberId}

---

## 14. What does the callback payload look like and how do I detect completion?

**Developer Question:**
What does the callback POST body look like? How can I detect completion?

**Answer:**
The callback payload body is **identical to the response of `GET /documents/{memberId}`** — a full document object containing the current state of the document and all members at the time the event fired.

To determine document completion:

| Method | Field to check | Description |
|--------|----------------|-------------|
| Simplest | `state` | Check if `state === "completed"` |
| Signers only | `allSignersSigned` | `true` when all signers have signed |
| All members | `allMembersSigned` | `true` when every member has completed their action |
| Granular | `members[n].signedAt` / `approvedAt` / `viewedAt` / `declinedAt` | Non-null timestamp means that action has been taken |

Recommended approach: Check `state === "completed"` as the primary signal.

> There is NO `action` field or `{"action": "document_signed", "document": {...}}` wrapper — that structure does not exist in the sproof API.

---

## 15. Can the signing order or recipients be changed after sending?

**Developer Question:**
Is there an API endpoint to change signing order or swap a recipient after sending?

**Answer:**
No. Once a signature request has been sent, it is not possible to modify the signing order or recipient details via the API.

The only option is to delete the document and re-send it with the corrected configuration. Deleting invalidates all existing signing links — recipients who received the original invitation will need to be notified again.

📎 https://docs.sproof.com/#tag/documents/DELETE/documents/{memberId}
📎 https://docs.sproof.com/#tag/signatures/POST/documents/signature

---

## 16. What are the file size and document count limits per envelope?

**Developer Question:**
Is there a maximum file size or document count per envelope?

**Answer:**

| Limit | Value |
|-------|-------|
| Recommended maximum file size per document | **30 MB** (base64 encoded) |
| Recommended maximum documents per envelope | **25 documents** |

Note: base64 encoding increases file size by approximately 33%, so 30 MB encoded corresponds to roughly 22 MB of original PDF. Staying within these limits is required for a stable integration. For use cases exceeding these limits, contact **ticket@sproof.com**.

---

## 17. Can a recipient's email address be updated after the invitation was sent?

**Developer Question:**
Is there a way to update a recipient's email address after the invitation was sent?

**Answer:**
No. There is no API endpoint to update a recipient's email address after a signature request has been sent.

The only option is to delete the document and re-send it with the correct email address. If only one recipient's email is wrong in a multi-document envelope, the entire envelope must be deleted and re-created.

---

## 18. What is the difference between the available signature types?

**Developer Question:**
What are the differences between `simple`, `advanced`, `advancedPlus`, `qualified`, and `qualifiedPlusIdent`?

**Answer:**

| `signatureType` value | eIDAS classification | Description |
|----------------------|---------------------|-------------|
| `simple` | SES | Most basic. No identity verification. Suitable for low-risk documents. |
| `advanced` | AES | Email-based identity verification. Meets eIDAS AES requirements. |
| `advancedPlus` | AES | Same legal standing as `advanced`, but with an additional security code via email or SMS. |
| `qualified` | QES | Highest level. Same legal standing as a handwritten signature under eIDAS. Requires a qualified certificate. |
| `qualifiedPlusIdent` | QES + Identification | Same as `qualified`, but includes an integrated identification step for recipients without a QES certificate. |

QES (`qualified`) requires an active User+ licence on the sproof plan.

---

## 19. What is stack signing / batch signing and how does it work?

**Developer Question:**
What is "stack signing" and how do I implement it?

**Answer:**
Stack signing lets a User+ member sign multiple QES documents in a single confirmation. It is **completely separate** from sending documents in an envelope.

**What stack signing is NOT:**
- It is not sending multiple documents in a single signature request
- It is not an envelope or folder of documents
- There is no stack signing URL to construct
- `folderName` has no role in this flow

**Prerequisites:**
- Documents must already be in `pending` state (already sent to the recipient) before being added to the stack
- The signer must have a User+ licence and verified identity
- Stack signing only processes documents with `signatureType: "qualified"`

**The two-step flow:**

Step 1 — Add each document to the user's signing stack using the **recipient's** `members[n].id` from the original signature request response. Call this endpoint once per document.

📎 `POST /user/pendingSignatures` — https://docs.sproof.com/#tag/Stack/POST/user/pendingSignatures

Step 2 (optional) — Trigger the batch signature programmatically. This sends a push notification to the user's mobile device to confirm all stacked QES signatures at once.

📎 `POST /documents/user/signBatch` — https://docs.sproof.com/#tag/Stack/POST/documents/user/signBatch

The user can also skip Step 2 and do it manually: open sproof Sign → "Signature Stack" → "Sign all".

---

*For questions not covered here, direct customers to: **ticket@sproof.com***