> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.hellosign.com/llms.txt.
> For full documentation content, see https://developers.hellosign.com/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.hellosign.com/_mcp/server.

# Workflows

> Embedded signing, embedded unclaimed drafts, bulk send, and OAuth flows in the Dropbox Sign API.

# Workflows

Major workflow patterns in Dropbox Sign: how documents get signed in different contexts, how to send at scale, and how OAuth enables third-party integrations.

---

## Signature Request Creation

**Brief:** The process of creating and sending a Signature Request to signers, either through the API or the Dropbox Sign web application.

**Description:**
There are multiple ways to create and send a Signature Request:

1. **Via the Dropbox Sign web application** — A user prepares documents, places fields, adds signers, and sends directly from the Dropbox Sign UI (the "Prep and Send" flow).
2. **Via API (direct send)** — An application creates and sends a Signature Request in a single API call, with documents and field placements specified programmatically.
3. **Via API with Template** — An application creates a Signature Request from a pre-configured Template, mapping signer roles to actual signers and filling merge fields.
4. **Via Unclaimed Draft** — An application creates a draft that is then finalized either through the Dropbox Sign website or an embedded iframe.

**API Endpoints:**
- `POST /signature_request/send` — Send directly with documents
- `POST /signature_request/send_with_template` — Send using a Template
- `POST /unclaimed_draft/create` — Create a draft for later finalization
- `POST /unclaimed_draft/create_embedded` — Create a draft for embedded finalization

---

## Embedded Signing

**Brief:** A signing flow where the signer completes their signature within the integrating application (via iframe) rather than on the Dropbox Sign website.

**Description:**
Embedded Signing hosts the signing experience directly within an application. Instead of signers receiving an email and being directed to the Dropbox Sign website, a short-lived signing URL is generated and displayed in an iframe. This creates a seamless, branded experience without the signer leaving the integrating application.

**How It Works:**
1. Create a Signature Request with `client_id` (from an API App)
2. Get the `signature_id` for the signer from the response
3. Call the **Get Embedded Sign URL** endpoint with the `signature_id`
4. Receive a short-lived `sign_url` (valid for ~60 minutes)
5. Open the URL in an iframe using the Dropbox Sign embedded.js library
6. Handle client-side events (signed, declined, error, etc.)

**Key Requirements:**
- Must have an **API App** with a valid `client_id`
- The API App's domain must match where the iframe is embedded
- The `sign_url` is single-use and expires quickly
- The official embedded.js JavaScript library must be used

**Embedded.js Client Events:**
| Event | Description |
| --- | --- |
| `sign` | Signer completed signing |
| `cancel` | Signer closed without completing |
| `decline` | Signer declined to sign |
| `error` | An error occurred |
| `finish` | Redirect after signing completed |
| `message` | Generic message from the iframe |

**Embedded vs. Email-based Signing:**
| Aspect | Embedded | Email-based |
| --- | --- | --- |
| Signer notification | The application shows the UI | Dropbox Sign sends email |
| Signing location | Within the application (iframe) | Dropbox Sign website |
| Branding | Application's look & feel | Dropbox Sign branding |
| Client ID required | Yes | No |
| Signer must have account | No | No |

**Important Distinctions:**
- The `sign_url` expires quickly and is single-use. Do not store it for later.
- The `cancel` event means the signer closed the iframe without signing — this is not the same as declining.
- A `client_id` must be included when creating the request for embedded mode to work.
- When using signing order, a sign URL can only be generated for the currently-active signer.

**Related docs:** See the [Embedded Signing walkthrough](/docs/walkthroughs/embedded-signing).

---

## Embedded Unclaimed Draft

**Brief:** A flow where document preparation (field placement, signer assignment) happens within the integrating application via an embedded iframe, using an Unclaimed Draft.

**Description:**
Embedded Unclaimed Draft allows embedding the Dropbox Sign document preparation experience into an application. End users can drag-and-drop fields onto documents, assign fields to signers, and configure the request — all within the integrating application's UI. This is used when end users (not just developers) need to create signature requests with custom field placement.

**How It Works:**
1. Create an **Embedded Unclaimed Draft** with `client_id`; optionally include `requester_email_address` when the resulting request should belong to a specific account
2. Get the `claim_url` from the response
3. Open the claim URL in an iframe using embedded.js
4. The user places fields, assigns signers, and sends
5. The draft becomes a Signature Request owned by the requester account

**`requester_email_address`:** Optional. It does not need to be defined unless the resulting Signature Request should be owned/sent by a specific account instead of the default requester context. When provided, the email address must belong to an account that has access to the API App being used, or be in the same team/subscription. If the account does not yet exist, it may be created automatically depending on subscription settings.

**Use Case:** An application allows non-technical users to create and send their own signature requests with custom field placement. If ownership should be assigned to a specific user, pass that user's email as `requester_email_address`; otherwise omit it.

**Important Distinctions:**
- The `claim_url` (for draft preparation) is different from `sign_url` (for signing). They serve different purposes.
- Unclaimed Drafts expire and must be recreated if not claimed in time.
- `requester_email_address` is optional; use it only when the resulting request should be owned by a specific account.

**Related docs:** See the [Embedded Requesting walkthrough](/docs/walkthroughs/embedded-requesting) and [Unclaimed Draft API reference](/api/unclaimed-draft).

---

## Unclaimed Draft

**Brief:** A Signature Request in draft state that has not yet been finalized for signing.

**Description:**
A pre-created Signature Request that hasn't been "claimed" yet. Documents are uploaded and potentially configured, but the request isn't active. Unclaimed Drafts can be used in two ways:

1. **Embedded** — Created via the embedded API endpoints and claimed through an iframe within the integrating application (see Embedded Unclaimed Draft above).
2. **Non-embedded (simple)** — Created via the standard API endpoint and claimed by accessing the `claim_url` directly on the Dropbox Sign website. The first authenticated user to access the URL claims the draft and is shown the "Sign and send" or "Request signature" page with the draft pre-loaded.

**Lifecycle:**
```
Created (Draft) → Claimed (via iframe or Dropbox Sign website) → Active Signature Request
       │
       └── Expired (if not claimed in time)
```

**Types of Unclaimed Drafts:**
| Type | Description |
| --- | --- |
| `send_document` | User prepares and sends a new request |
| `request_signature` | Similar to send_document with additional options |
| `edit_and_resend` | User edits an existing request and sends |

**Important Distinctions:**
- An Unclaimed Draft is not a final Signature Request until it has been claimed.
- Unclaimed Drafts expire and must be recreated if not claimed in time.

**Related docs:** See the [Unclaimed Draft API reference](/api/unclaimed-draft).

---

## Bulk Send

**Brief:** Sending the same document(s) to many different signers in a single API call using a Template.

**Description:**
Creates multiple Signature Requests from a single Template in one operation. Each request goes to different signers with potentially different merge field values. Ideal for scenarios like sending the same contract to many different clients, each with personalized details.

**How It Works:**
1. Create a **Template** with signer roles and merge fields
2. Prepare a list of signers and their corresponding merge field values
3. Call the **Bulk Send with Template** endpoint
4. Dropbox Sign creates individual Signature Requests for each signer set

**Limits:**
- Maximum signers per bulk send varies by plan
- Each item in the signer list creates a separate, independent Signature Request
- Callback events fire individually for each created request

**Important Distinctions:**
- Each created request in a bulk send triggers its own callback events independently — there is no single callback for the entire batch.
- Bulk send creates N separate Signature Requests. This is different from a multi-signer request, which is one request with N signers.

**Related docs:** See [Bulk Send with Template](/api/signature-request/bulk-send-with-template) and the [Bulk Send Job API reference](/api/bulk-send-job).

---

## OAuth

**Brief:** An authorization flow that lets an application act on behalf of other Dropbox Sign users without accessing their credentials.

**Description:**
OAuth allows third-party applications to obtain limited access to a user's Dropbox Sign account. The user grants permission through a consent screen, and the application receives tokens to make API calls on their behalf.

**Flow:**
```
1. Application → Redirects user to Dropbox Sign authorization URL
2. User → Grants permission on consent screen
3. Dropbox Sign → Redirects back to the application with authorization code
4. Application → Exchanges code for access_token + refresh_token
5. Application → Uses access_token for API calls on user's behalf
6. (When expired) → Uses refresh_token to get new access_token
```

**OAuth Scopes:**
| Scope | Description |
| --- | --- |
| `request_signature` | Create and manage signature requests |
| `basic_account_info` | Read account information |
| `account_access` | Full account access |
| `signature_request_access` | Access to signature requests |
| `template_access` | Access to templates |
| `team_access` | Access to team management |
| `api_app_access` | Access to API App management |

**Key Requirements:**
- Must have an **API App** with OAuth configured
- API App must specify allowed redirect URIs
- Access tokens expire; use refresh tokens to renew

**Important Distinctions:**
- API Key = authenticating as one's own account. OAuth = acting on behalf of other users who have granted permission.
- Refresh tokens provide long-lived access and must be stored securely.
- Access tokens expire; use refresh tokens to obtain new access tokens.

**Related docs:** See the [OAuth walkthrough](/docs/guides/o-auth/walkthrough) and [API authentication reference](/api/api-reference-authentication).

---

## Test Mode

**Brief:** A sandbox mode for testing API integrations without consuming quotas, sending real emails, or creating legally-binding documents.

**Description:**
Test Mode allows development and testing without real-world side effects. Requests created in test mode don't count against quotas, don't send actual emails to signers, and produce documents watermarked as "TEST".

**How to Enable:**
Set `test_mode: 1` (or `true`) in the API request body.

**Test Mode Behaviors:**
| Behavior | Test Mode | Production |
| --- | --- | --- |
| Emails sent to signers | Yes for non-embedded workflows; depends on account email notification settings | Yes; depends on account email notification settings |
| Counts against quota | No | Yes |
| Documents watermarked | Yes ("TEST") | No |
| Legally binding | No | Yes |
| Callbacks sent | Yes (to configured URL) | Yes |
| Embedded signing works | Yes | Yes |

**Important Distinctions:**
- Test mode requests still appear in the dashboard (watermarked as "TEST").
- Callbacks DO fire in test mode, making it useful for testing webhook endpoints.
- `test_mode` must be removed from requests when going to production.

**Related docs:** See the [API overview](/docs/overview) for plan and testing details.