Dropbox Sign → Embedded signing

This guide helps you move a Dropbox Sign embedded signing integration to Formable. You keep the same product shape (create a request, mint a URL, embed it) while swapping endpoints, auth, and how you open the signing UI. If you also embed template setup in your product, migrate that first with Dropbox Sign → Embedded templates. Signing always starts from a prepared Formable template.

New to Formable? Complete the Embedded signing walkthrough first, then use this page as a translation layer from Dropbox Sign terms and calls.

Prefer a white-glove migration? Email matt@formabledocs.com and we’ll handle moving your Dropbox Sign integration to the Formable API.

What you’re moving

In Dropbox Sign you typically:

Create an embedded signature request (create_embedded or create_embedded_with_template)
Fetch a per-signer sign_url with each signature_id
Open it with hellosign-embedded
React to callbacks such as signature_request_all_signed, then download files

In Formable you:

Upload and prepare a template (once, then reuse)
Create an embedded signature request from that templateId with a signers array (each signer has email, name, and role)
Mint a signingUrl from each signer’s recipientSignatureId and load it in a plain iframe
Handle document_completed (webhook or poll), then download the signed PDF

The journey is familiar: backend creates the send, backend mints a short-lived URL, frontend embeds it. The main mental shifts are template-first sending, Bearer API keys, and no Dropbox Sign client library.

Recommended order of work

Get a Formable API key

Create an organization and key in Settings. See Authentication.

Migrate templates

Recreate documents and fields in Formable. If you use embedded templates today, follow Embedded templates migration.

Swap create + signing URL calls

Replace create_embedded* and /embedded/sign_url/{signature_id} with POST /v1/signature-requests/embedded and POST /v1/recipient-signatures/{id}/url.

Replace hellosign-embedded with an iframe

Pass only the signingUrl from your backend to the browser.

Point webhooks at Formable

What’s similar

Much of the Dropbox Sign model still maps cleanly:

You still create a signature request on the server, then open a short-lived URL in the browser.
Templates remain the reusable document definition. One template powers many sends.
test_mode / testMode keeps integration traffic out of billing. Test mode documents are watermarked and are not legally binding.
You still download a completed PDF after everyone has signed.
Signing URLs are meant to be generated just in time, not stored long-term. Dropbox Sign sign_url values last about 60 minutes and same with Formable signingUrl.

Migrating from Dropbox Sign to Formable is almost a 1 to 1 mapping.

What’s different

Plan for these shifts early so you don’t recreate Dropbox Sign patterns that Formable doesn’t use:

Area	Dropbox Sign	Formable
Auth	API key	API key
App / client	API App + `client_id` on requests and in the JS client	Organization implied by the API key; omit `client_id`
Files on send	`create_embedded` can attach files inline	Upload a template first, then create the signature request
Signing URL scope	One `sign_url` per `signature_id`	One `signingUrl` per `recipientSignatureId`
Client embed	`hellosign-embedded` + `client.open(...)`	Plain `<iframe src={signingUrl}>` + `window.postMessage`
Completion signal	Client events + callbacks (`signature_request_all_signed`, etc.)	`onSigningComplete` iframe message for UI; prefer `document_completed` as source of truth
Webhook verification	`event_hash`	`Content-Sha256` HMAC — see Verifying webhooks

Formable is intentionally template-first. If your Dropbox Sign code uploads PDFs on every create_embedded, move that upload into a one-time (or occasional) template create/edit step, then send with templateId.

Concept map

Dropbox Sign	Formable	Notes
API key (HTTP Basic)	API key (`Authorization: Bearer fmbl_…`)	See Authentication.
API App + `client_id`	Organization	Implied by the API key — not sent on requests.
Signature request	Signature request	One send of a template to one or more signers.
`signature_id` (per signer)	`recipientSignatureId` (per signer)	Use it with create signing URL — same per-signer model as Dropbox Sign.
`sign_url`	`signingUrl`	Embed in an iframe. Expires after 1 hour.
`hellosign-embedded`	Plain `<iframe>` + `postMessage`	No Formable JS SDK. Listen for `onSigningComplete`.
`test_mode: true`	`testMode: true`	Excluded from billing. Documents are watermarked and not legally binding.
`signature_request_all_signed` / `downloadable`	`onSigningComplete` + `document_completed`	Use the iframe message for UI; webhook before download.

Endpoint map

Dropbox Sign	Formable
`POST /v3/signature_request/create_embedded_with_template`	`POST /v1/signature-requests/embedded`
`POST /v3/signature_request/create_embedded` (files inline)	Upload a template first, then create the signature request
`GET /v3/embedded/sign_url/{signature_id}`	`POST /v1/recipient-signatures/{id}/url`
`GET /v3/signature_request/files/{signature_request_id}`	`GET /v1/signature-requests/{id}/signed-envelope`

Auth

Dropbox Sign typically uses HTTP Basic:

curl https://api.hellosign.com/v3/account -u 'YOUR_API_KEY:'

Formable uses Bearer tokens that start with fmbl_:

curl https://api.formabledocs.com/v1/signature-requests \
  --header "Authorization: Bearer fmbl_YOUR_API_KEY"

Create the key in Settings and call the API only from your backend. Full details: Authentication.

Migrate the flow

1. Create the signature request

Dropbox Sign (create_embedded_with_template):

curl https://api.hellosign.com/v3/signature_request/create_embedded_with_template \
  -u 'YOUR_API_KEY:' \
  -F 'client_id=YOUR_CLIENT_ID' \
  -F 'template_ids[]=TEMPLATE_ID' \
  -F 'signers[0][role]=Client' \
  -F 'signers[0][email_address]=jane@example.com' \
  -F 'signers[0][name]=Jane Doe' \
  -F 'test_mode=1'

Formable:

curl --request POST \
  --url https://api.formabledocs.com/v1/signature-requests/embedded \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "templateId": "abc123xyz",
    "signers": [
      { "email": "jane@example.com", "name": "Jane Doe", "role": "Client" }
    ],
    "sender": { "email": "you@yourcompany.com", "name": "Your Company" },
    "testMode": true
  }'

Response

{
  "signatureRequestId": "sr_456def",
  "signers": [
    {
      "email": "jane@example.com",
      "name": "Jane Doe",
      "recipientSignatureId": "rsig_789ghi"
    }
  ]
}

Pass a signers array on every create. Each signer needs email, name, and role (matching template field roles). sender is optional and defaults to the org owner. Use fields: [{ fieldId, value }] for prefills (field IDs come from the template editor). Save each signer’s recipientSignatureId to mint their signing URL.

Dropbox Sign field	Formable field
`template_ids[]`	`templateId` (one template per request)
`signers[].email_address` / `name`	`signers[].email` / `name`
`signers[].role`	`signers[].role`
`client_id`	Omit
`test_mode`	`testMode`
Custom / merge fields	`fields: [{ fieldId, value }]`

2. Generate the signing URL

Dropbox Sign — per-signer signature_id:

curl https://api.hellosign.com/v3/embedded/sign_url/SIGNATURE_ID \
  -u 'YOUR_API_KEY:'

Formable — per-signer recipientSignatureId:

curl --request POST \
  --url https://api.formabledocs.com/v1/recipient-signatures/rsig_789ghi/url \
  --header "Authorization: Bearer $TOKEN"

Response

{
  "signingUrl": "https://app.formabledocs.com/sign/embedded/xyz789abc",
  "expiresAt": "2024-01-16T10:30:00.000Z"
}

Generate the URL just before the signer is ready. Formable URLs expire after one hour. Creating a URL for an already completed request returns 409.

3. Embed on the client

Dropbox Sign:

import HelloSign from "hellosign-embedded";

const client = new HelloSign({ clientId: "YOUR_CLIENT_ID" });
client.open(signUrl, { skipDomainVerification: true });

Formable — plain iframe + postMessage (no SDK, no client_id, no skipDomainVerification):

<iframe
  src="https://app.formabledocs.com/sign/embedded/xyz789abc"
  width="100%"
  height="800"
  allow="fullscreen"
  style="border: none;"
></iframe>

window.addEventListener("message", (event) => {
  if (event.origin !== "https://app.formabledocs.com") return;
  if (!event.data || typeof event.data !== "object") return;

  if (event.data.type === "onSigningComplete") {
    // signer finished — close the iframe or show success
  }
  if (event.data.type === "onSigningError") {
    // signing failed — show an error or retry
  }
});

Mint the URL on your backend and pass only the URL to the browser. Never call Formable with your API key from client-side code. See Embedded signing for the full event list.

4. Detect completion and download the PDF

Use onSigningComplete to update the client immediately. Prefer the document_completed webhook (or poll signature request status until Completed) before downloading. You can also read the event stream.

curl --request GET \
  --url https://api.formabledocs.com/v1/signature-requests/sr_456def/signed-envelope \
  --header "Authorization: Bearer $TOKEN"

Response

{
  "signedEnvelopePresignedUrl": "https://s3.amazonaws.com/bucket/signed-envelope.pdf?..."
}

Download that presigned URL promptly. Requesting it before signing finishes returns 409. Webhook verification differs from Dropbox Sign’s event_hash. Formable signs the raw body with HMAC-SHA256 and sends the digest in Content-Sha256. See Verifying webhooks and Webhooks overview.

Differences to plan for

Template-first, not file-on-send

Dropbox Sign can attach files on create_embedded. Formable expects a prepared template first. Upload once, place fields, then send with templateId.

No hellosign-embedded — use iframe postMessage

Load signingUrl in an iframe. Listen for onSigningComplete / onSigningError instead of Dropbox Sign client events such as sign or finish. Confirm completion with webhooks or status polling before downloading the PDF.

Signing URL is per signer

Dropbox Sign issues a sign_url per signature_id. Formable does the same: use each signer’s recipientSignatureId from the create response with create signing URL.

Roles map directly

Dropbox Sign signers[].role maps to Formable signers[].role. Assign matching roles to required fields in the template editor, then pass the same role names when you create the embedded signature request.

Checklist

Create a Formable API key

In Settings. Store it as a server secret.

Prepare templates

Recreate documents and fields — or migrate the embedded template flow separately.

Swap create + sign URL calls

Replace create_embedded* and embedded/sign_url with Formable endpoints. Use signers with roles on create; mint URLs from each recipientSignatureId.

Replace hellosign-embedded with an iframe

Pass only the signingUrl from your backend.

Point webhooks at Formable

Handle document_completed / document_viewed and verify Content-Sha256.

Next steps

Embedded templates migration

Map create_embedded_draft and edit_url to Formable.

Non-embedded signing migration

Map send / send_with_template to Formable email delivery.

Embedded signing walkthrough

Full Formable signing walkthrough.

Getting Started

Walkthroughs

SDKs

Migrations

Webhooks

Dropbox Sign → Embedded signing

What you’re moving

Recommended order of work

What’s similar

What’s different

Concept map

Endpoint map

Auth

Migrate the flow

1. Create the signature request

2. Generate the signing URL

3. Embed on the client

4. Detect completion and download the PDF

Differences to plan for

Checklist

Next steps

Embedded templates migration

Non-embedded signing migration

Embedded signing walkthrough

Webhooks

​What you’re moving

​Recommended order of work

​What’s similar

​What’s different

​Concept map

​Endpoint map

​Auth

​Migrate the flow

​1. Create the signature request

​2. Generate the signing URL

​3. Embed on the client

​4. Detect completion and download the PDF

​Differences to plan for

​Checklist

​Next steps

Embedded templates migration

Non-embedded signing migration

Embedded signing walkthrough

Webhooks

What you’re moving

Recommended order of work

What’s similar

What’s different

Concept map

Endpoint map

Auth

Migrate the flow

1. Create the signature request

2. Generate the signing URL

3. Embed on the client

4. Detect completion and download the PDF

Differences to plan for

Checklist

Next steps