Dropbox Sign web vs API: what embedded signing really needs

Use Dropbox Sign’s web app when someone on your team prepares and sends agreements there. Use the API when your software creates requests or handles signing as part of an application. Within the API, email-based signing starts at Essentials API; signing inside your own product starts at Standard API. An embedded template editor requires Premium API. Dropbox’s workflow tiers

The practical choice is what happens after a customer agrees to your terms. Can a staff member send the document manually? Should your software send an email? Does the customer need to sign while logged into your portal? Each answer leads to a different setup. A web subscription and an API subscription have separate allowances, even when their plan names sound similar.

A web plan can cover the manual job

A business owner who uploads an agreement, assigns signers, and sends it from the Sign web app has a web workflow. Paid Essentials, Standard, and Premium web plans permit unlimited signing and requesting of documents. Their allowances do not supply API requests. API pricing depends on monthly signature-request volume and the billing term. Dropbox’s web-plan limits

Before commissioning an integration, describe the repetitive work it would remove. If staff already have a finished agreement and only need to send it, the manual process may be sufficient. If a portal generates documents from customer data and needs the completed agreement back in the customer’s account, an API integration connects those steps. Its budget includes the relevant API request allowance and the developer’s work maintaining that connection; a web plan’s unlimited document count does not settle either cost.

Automated email signing does not need an embedded screen

The non-embedded API lets your software prepare and send a request while Dropbox Sign hosts the signing page. POST /v3/signature_request/send takes the document and signer details. The signer receives an email, follows the link, and completes the request on Dropbox Sign. Your application can receive completion events and retrieve documents afterward. Non-embedded signing walkthrough

For an illustrative service-agreement portal, the customer could select a service, supply their details, and receive an agreement by email. The portal would store the resulting request ID against the customer’s agreement. The customer need not remain in the portal while signing. This is an application design example, not a report of an integration we ran.

The simple files workflow appends a signature page. Explicit form fields control placement, while send_with_template uses an existing reusable template. Choose the document layout before building around the default: a signature beside a specific clause calls for different preparation from a signature page appended to the document. Document preparation options

Embedded signing changes the request you create

For signing inside the portal, the backend creates an embedded request using POST /v3/signature_request/create_embedded. Copying the link from a normal email request into an iframe will not convert it. Dropbox distinguishes normal requests, which are signed on its website, from embedded requests, which are signed in an embedded iframe. Create embedded signature request

This illustrative JSON body shows the small amount of data involved in a basic request. Replace both the client ID and document host before using it. The host must provide a non-confidential test PDF that Dropbox Sign can download; the URL below is a placeholder.

{
  "client_id": "YOUR_API_APP_CLIENT_ID",
  "title": "Sample service agreement",
  "file_urls": ["https://YOUR_DOCUMENT_HOST/service-agreement.pdf"],
  "signers": [{"name": "Sample signer", "email_address": "signer@example.com"}],
  "test_mode": true
}

The endpoint requires an API app’s client_id, a document supplied through files or file_urls, and signers supplied through signers or grouped_signers. Each pair is an alternative. Credentials belong in backend authentication, outside this JSON and browser code. Because this example omits form_fields_per_document, the documented default appends a signature page. A test_mode request is not legally binding. Request parameters

Keep request IDs and signer IDs separate

Creating the embedded request returns a signature_request_id for the whole transaction and a separate signature_id for each signer. When the customer opens the signing screen, the backend obtains a temporary sign_url through GET /v3/embedded/sign_url/{signature_id}. The browser opens that URL with hellosign-embedded and the app’s clientId. Embedded signing sequence

Keep the portal’s own agreement ID alongside these vendor IDs. That gives a callback a specific agreement to update and lets the backend identify the signer opening the screen. The backend should check that the logged-in customer is allowed to sign that agreement before issuing a URL. This authorization check belongs to your application; knowing an API ID does not establish a customer’s permission.

Job	ID to use	Application responsibility
Store the created agreement	signature_request_id plus each signature_id	Associate the request and signers with your customer records.
Open a customer’s signing screen	That customer’s signature_id	Authorize the customer, then fetch their signing URL.
Retrieve the request’s documents	signature_request_id	Retrieve files for the agreement, not an individual signer.

Generate the signing URL when the customer reaches the screen. The documented lifetime is 60 minutes, and the URL expires once accessed. A saved URL is therefore unsuitable as a permanent link in a customer’s account. Keep the signer ID and obtain a fresh URL when needed. Signing-link lifetime

A sender’s editor and a template editor are separate features

Embedded requesting puts the document-preparation interface inside your application. A user can create and send requests from an iframe, including preparing documents and identifying signers. It requires Standard API for production. This is useful when portal users must prepare their own requests. A customer signing an agreement your back office already prepared needs embedded signing instead. Embedded requesting

Preparing a request inside the portal also does not force its recipients to sign there. Dropbox’s default embedded-requesting flow sends recipients an email to complete signing on Dropbox Sign. Choose the sender’s interface and the recipient’s interface separately. Requesting workflow

Embedded templates let users create or edit reusable templates inside your application. That workflow requires Premium API. Merely sending an agreement from an existing template is a different operation. A fixed agreement prepared by your staff does not acquire an embedded template editor just because its contents are reused. Embedded templates · Production tier requirements

A signature event is not the finished PDF

The events have different meanings. signature_request_signed reports that one signer completed their required fields. signature_request_all_signed reports completion by all signers, but document generation can still take additional time. signature_request_downloadable reports an updated file available for download; earlier downloadable versions can exist before everyone has signed. Archive the final agreement only after all signers have completed and the finished file is ready. Events and completion timing

For the portal, suggested application states are awaiting_signatures, all_signed, file_pending, and archived. These are your labels, not Dropbox Sign status names. A browser sign event can refresh the customer’s screen, while authenticated backend callbacks update the agreement record and trigger final file retrieval.

Callbacks use multipart form data with the event payload in a field named json. Verify the event using the official SDK’s callback helper or the documented HMAC method before trusting it. The payload’s signature_request.signature_request_id connects it to your stored agreement. HTTPS is required, and acknowledgment needs HTTP 200 with a body containing Hello API Event Received. Callback implementation

Persist an accepted event before doing slow file work. Because callbacks can be retried, make processing safe to repeat: an event should update an existing agreement and queue its document retrieval, not create another agreement or another signature request. That is a suggested application design, which your developer must implement.

Read a 409 error in the context of its endpoint

On the signing-URL endpoint, HTTP 409 can mean the signer has already signed or, for ordered signing, that their turn has not arrived. Creating a fresh URL will not make an out-of-order signer eligible. Show their current signing state instead of treating every failure as an expired link. Embedded signing errors

On GET /v3/signature_request/files/{signature_request_id}, 409 means the files are still being prepared. Preserve the request ID and retry document retrieval after the appropriate completion signal. Sending another agreement to solve this error would create another signing task. The files endpoint supports a merged PDF or a ZIP containing individual documents. Download files reference

Once downloaded, store the final file against the agreement record and then mark it archived. Keeping only a request ID leaves the retrieval and storage work unfinished. No PDF download or completed signing request was performed for this explanation.

Going live requires a plan and an app’s production state

Dropbox allows test mode to exercise every endpoint and most features, even from a free account. Production still requires the API tier for the actual workflow. A prototype’s successful embedded screen does not establish a paid entitlement. Test mode and API plans

The current embedded-app process supports self-publishing from the Sign website’s API settings: create the app with its name, domain, and callback URL, then select Publish. Publishing must happen through the website even if the app was created through the API. OAuth apps still require the support-assisted approval process. Self-publishing API apps

Non-embedded workflows do not require app approval, while OAuth remains subject to its own approval requirement. An embedded app’s published state and a paid API subscription are separate requirements. You can complete approval before buying a plan, but production calls need the paid plan activated. App approval overview

For production embeds, check that the application’s HTTPS host matches the API app’s configured domain. skipDomainVerification only applies to test-mode requests. After confirming production access, remove backend test_mode and the frontend domain-skip flag as directed in the go-live documentation. Embedding requirements · Go-live instructions

Official documentation checked October 7, 2026. The request body and portal design are illustrative. No live API request, paid subscription, or production app publication was performed for this article.