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:

Embedded vs. Email-based Signing:

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.

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 and Unclaimed Draft API reference.

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:

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.

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 and the Bulk Send Job API reference.

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:

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 and API authentication reference.

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:

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 for plan and testing details.