# sproof Sign API Integration Strategies

This guide summarizes the main integration strategies for placing signature fields and controlling recipient logic with the sproof Sign API.

The right strategy depends on how much control your application needs, whether documents are static or dynamically edited/created, when recipient data is known, and whether the signing process should be fully automated or reviewed manually.

## Overview

sproof Sign supports four common API integration strategies:

1. Programmatic placement through API request coordinates
2. Smart text placeholders embedded in the document (PDF, DOCX, or other supported exports)
3. Workflow placeholders that separate document layout from process logic
4. Manual draft mode where a user finalizes the request before sending

## 1. Programmatic Placement Through API Coordinates

Use this strategy when your application knows the exact signature position before sending the request.

Positions are supplied in the **create signature request** payload (per document), in each recipient’s details: `page`, `x`, `y`, `width`, and `height` for every signature box.

### How it works

Your system calculates or stores the signature geometry and sends it with the request. The API expects **normalized coordinates**: `x`, `y`, `width`, and `height` are fractions of the page width and height (between **0 and 1**), with the origin at the **top-left** of the page. The **page index is zero-based** (the first page is `0`). Optional `pageWidth` / `pageHeight` integers can be set to improve placement precision (see OpenAPI field descriptions).

Typical data includes:

- Page index (0-based)
- Normalized `x` / `y` / `width` / `height`
- Recipient identity and routing (email, name, signing order, and so on)
- Allowed **signature types** and related settings for each recipient

### Best for

- Static documents
- Standardized forms
- Documents where the layout rarely changes
- Fully automated backend-driven signing flows

### Advantages

- The document does not need embedded `{sproof{…}sproof}`-style placeholders
- The full placement logic is controlled by your application
- Works well for predictable layouts

### Limitations

- Sensitive to layout changes
- Coordinates must be updated if the document template changes
- Less suitable for dynamically generated documents with variable content length

## 2. Smart Text Placeholders in the Document

Use this strategy when the **file** should carry recipient data and signature placement (common for mail-merge or generated contracts).

Placeholders are recognized when the document is **uploaded** as part of the request. They are **not** limited to PDF: supported sources include PDF, Microsoft Word (DOCX), and Google Docs exports, as described in the OpenAPI guide.

### How it works

Your document generation pipeline embeds the placeholder string in the file. During processing, sproof Sign finds each placeholder, derives signature positions from the text layout, and builds the corresponding recipients and fields.

**Placeholder processing must be enabled** by setting `usePlaceholders` to `true` in the request envelope data (see **Create signature request** in the API reference).

Recognition constraints (from product documentation): placeholders need a **minimum font size of 4 pt**, must stay on a **single line** (no line breaks), and you can prefix with underscores `_` to control visual size; the text can be colored to blend with the background.

Example placeholder syntax:

```text
{sproof{first_name, last_name, email_address, signing_order, [optional] doNotSendEmail}sproof}
```

Example:

```text
{sproof{Max, Mustermann, max@example.com, 1}sproof}
```

The placeholder text is often rendered in white or otherwise hidden visually in the final document.

### Best for

- Dynamically generated documents
- CRM or ERP systems that generate signable files
- Cases where recipient information is known when the document is produced
- Documents where the layout can vary but the placeholder moves with the content

### Advantages

- The document carries its own placement and routing information
- Signature positions adapt naturally to dynamic document layout
- Reduces the need to calculate coordinates manually

### Limitations

- The authoring or generation pipeline must embed valid placeholders
- Placeholder syntax must be correct
- Recipient logic is coupled to the document content

## 3. Workflow Placeholder Strategy

Use this strategy when **where** people sign is driven by text in the document, but **how** they sign (roles, rounds, signature levels, reminders, and so on) is maintained in a **workflow** configured in the sproof Sign UI.

This separates layout from process logic.

### How it works

The document contains arbitrary **anchor text** you choose—often short tokens such as:

```text
{{signer1}}
```

The same string must appear in the PDF (or other supported upload format) **and** be sent in the API as each recipient’s `placeholderText`, so the service can locate signature positions via text search.

The workflow in the sproof Sign dashboard defines the process rules, for example:

- Recipient roles
- Signing order and rounds
- Required signature types
- Email content and compliance-oriented settings

The API identifies the workflow by its **workflow member ID** (`documentMembers.id` of the workflow—visible in the workflow URL in the UI). For each real recipient you provide:

- **`placeholderText`** – must match the anchor string in the document (placement).
- **`index`** – a **1-based** index that selects which workflow placeholder’s settings (role, signing order, signature types, and so on) apply to that recipient.

The recipient count and placeholder alignment must match what the workflow defines.

### Best for

- Dynamic documents
- Processes with stable compliance rules
- Organizations that want to manage signing rules centrally
- Workflows where document templates may change but business rules remain stable

### Advantages

- Separates document layout from compliance and process logic
- Workflow rules can be changed centrally
- Document template changes do not necessarily require API code changes
- Useful for Advanced Electronic Signature or Qualified Electronic Signature workflows

### Limitations

- Requires workflow configuration in sproof Sign
- Requires agreement between document anchors and workflow placeholders
- Slightly more setup than direct coordinate placement

## 4. Manual Draft Mode

Use this strategy when a human should review or finalize the signature request before invitations go out.

The API creates the document (or envelope) in **draft** state and **does not send invitation emails** until someone completes the flow in the UI.

### How it works

For the standard **create signature request** shape, call **`POST /documents/prepare`** instead of **`POST /documents/signature`**. The body matches the create endpoint; the backend stores a draft and does not invite recipients yet.

For **workflow-based** requests, use the prepare variants (for example **`POST /documents/prepare-recipients-with-workflow`**, or the envelope equivalents for multi-document workflows) so recipients and positions can be checked before sending.

From the response, take a document **`member.id`** and open the editor at:

```text
https://sign.sproof.com/#/editor/{memberId}
```

The user can adjust fields there and send when ready.

### Best for

- Complex one-off documents
- Exception cases
- Processes requiring manual review
- Four-eyes principle workflows
- Documents where automatic placement is too risky

### Advantages

- Human validation before sending
- Flexible for unusual document layouts
- Reduces risk in edge cases

### Limitations

- Not fully automated
- Requires manual user interaction
- Less suitable for high-volume straight-through processing

## Choosing the Right Strategy

| Scenario                                                                  | Recommended Strategy     |
| ------------------------------------------------------------------------- | ------------------------ |
| Static document with fixed layout                                         | Programmatic coordinates |
| Dynamic document where recipient data is known when the file is generated | Smart text placeholders  |
| Dynamic document with centrally managed signing rules                     | Workflow placeholders    |
| Complex or risky document requiring review                                | Manual draft mode        |

## Practical Recommendation

For simple, static templates, start with API coordinates.

For generated documents from CRM, ERP, or contract automation systems, use smart placeholders.

For reusable enterprise processes with compliance requirements, use workflow placeholders.

For exceptional cases or sensitive documents, use manual draft mode.

## Related Resources

- OpenAPI reference: [https://sign.sproof.com/api/v1/documentation/yaml](https://sign.sproof.com/api/v1/documentation/yaml)
- API documentation UI: [https://docs.sproof.com/](https://docs.sproof.com/)
- sproof Academy integration strategy article: [https://sproof.atlassian.net/wiki/spaces/Academy/pages/1635614721/sproof+Sign+Die+richtige+Integrationsstrategie+finden+API](https://sproof.atlassian.net/wiki/spaces/Academy/pages/1635614721/sproof+Sign+Die+richtige+Integrationsstrategie+finden+API)