> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formabledocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dropbox Sign → Embedded signing

> Migrate Dropbox Sign embedded signing (create_embedded, sign_url) to the Formable API.

This guide helps you move a [Dropbox Sign embedded signing](https://developers.hellosign.com/docs/walkthroughs/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](/migrations/dropbox-sign/embedded-templates). Signing always starts from a prepared Formable template.

<Info>
  New to Formable? Complete the [Embedded signing walkthrough](/walkthroughs/embedded-signing) first, then use this page as a translation layer from Dropbox Sign terms and calls.
</Info>

<Tip>
  Prefer a white-glove migration? Email [matt@formabledocs.com](mailto:matt@formabledocs.com) and we'll handle moving your Dropbox Sign integration to the Formable API.
</Tip>

## What you're moving

In Dropbox Sign you typically:

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

In Formable you:

1. Upload and prepare a **template** (once, then reuse)
2. Create an **embedded signature request** from that `templateId` with a `signers` array (each signer has `email`, `name`, and `role`)
3. Mint a `signingUrl` from each signer's `recipientSignatureId` and load it in a plain iframe
4. 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

<Steps>
  <Step title="Get a Formable API key">
    Create an organization and key in [Settings](https://app.formabledocs.com/settings). See [Authentication](/authentication).
  </Step>

  <Step title="Migrate templates">
    Recreate documents and fields in Formable. If you use embedded templates today, follow [Embedded templates migration](/migrations/dropbox-sign/embedded-templates).
  </Step>

  <Step title="Swap create + signing URL calls">
    Replace `create_embedded*` and `/embedded/sign_url/{signature_id}` with [`POST /v1/signature-requests/embedded`](/api-reference/endpoint/create-signature-request) and [`POST /v1/recipient-signatures/{id}/url`](/api-reference/endpoint/create-signing-url).
  </Step>

  <Step title="Replace hellosign-embedded with an iframe">
    Pass only the `signingUrl` from your backend to the browser.
  </Step>

  <Step title="Point webhooks at Formable">
    Register a URL in Settings. See [Webhooks](/webhooks/overview).
  </Step>
</Steps>

## 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](/walkthroughs/embedded-templates) 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`](/webhooks/events#document_completed) as source of truth |
| Webhook verification | `event_hash`                                                     | `Content-Sha256` HMAC — see [Verifying webhooks](/webhooks/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](/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`](/api-reference/endpoint/create-signature-request)       |
| `POST /v3/signature_request/create_embedded` (files inline) | Upload a [template](/walkthroughs/embedded-templates) first, then create the signature request   |
| `GET /v3/embedded/sign_url/{signature_id}`                  | [`POST /v1/recipient-signatures/{id}/url`](/api-reference/endpoint/create-signing-url)           |
| `GET /v3/signature_request/files/{signature_request_id}`    | [`GET /v1/signature-requests/{id}/signed-envelope`](/api-reference/endpoint/get-signed-envelope) |

## Auth

Dropbox Sign typically uses HTTP Basic:

```bash theme={null}
curl https://api.hellosign.com/v3/account -u 'YOUR_API_KEY:'
```

Formable uses Bearer tokens that start with `fmbl_`:

```bash theme={null}
curl https://api.formabledocs.com/v1/signature-requests \
  --header "Authorization: Bearer fmbl_YOUR_API_KEY"
```

Create the key in [Settings](https://app.formabledocs.com/settings) and call the API only from your backend. Full details: [Authentication](/authentication).

## Migrate the flow

### 1. Create the signature request

**Dropbox Sign** (`create_embedded_with_template`):

```bash theme={null}
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:**

```bash theme={null}
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
  }'
```

```json Response theme={null}
{
  "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`:

```bash theme={null}
curl https://api.hellosign.com/v3/embedded/sign_url/SIGNATURE_ID \
  -u 'YOUR_API_KEY:'
```

**Formable** — per-signer `recipientSignatureId`:

```bash theme={null}
curl --request POST \
  --url https://api.formabledocs.com/v1/recipient-signatures/rsig_789ghi/url \
  --header "Authorization: Bearer $TOKEN"
```

```json Response theme={null}
{
  "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:**

```javascript theme={null}
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`):

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

```javascript theme={null}
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](/walkthroughs/embedded-signing#detect-completion) for the full event list.

### 4. Detect completion and download the PDF

Use `onSigningComplete` to update the client immediately. Prefer the [`document_completed`](/webhooks/events#document_completed) webhook (or poll signature request `status` until `Completed`) before downloading. You can also read the [event stream](/api-reference/endpoint/get-signature-request-events).

```bash theme={null}
curl --request GET \
  --url https://api.formabledocs.com/v1/signature-requests/sr_456def/signed-envelope \
  --header "Authorization: Bearer $TOKEN"
```

```json Response theme={null}
{
  "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](/webhooks/verifying-webhooks) and [Webhooks overview](/webhooks/overview).

## Differences to plan for

<AccordionGroup>
  <Accordion title="Template-first, not file-on-send">
    Dropbox Sign can attach files on `create_embedded`. Formable expects a prepared [template](/walkthroughs/embedded-templates) first. Upload once, place fields, then send with `templateId`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Checklist

<Steps>
  <Step title="Create a Formable API key">
    In [Settings](https://app.formabledocs.com/settings). Store it as a server secret.
  </Step>

  <Step title="Prepare templates">
    Recreate documents and fields — or migrate the [embedded template flow](/migrations/dropbox-sign/embedded-templates) separately.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Replace hellosign-embedded with an iframe">
    Pass only the `signingUrl` from your backend.
  </Step>

  <Step title="Point webhooks at Formable">
    Handle `document_completed` / `document_viewed` and verify `Content-Sha256`.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Embedded templates migration" icon="file-lines" href="/migrations/dropbox-sign/embedded-templates">
    Map `create_embedded_draft` and `edit_url` to Formable.
  </Card>

  <Card title="Non-embedded signing migration" icon="envelope" href="/migrations/dropbox-sign/non-embedded-signing">
    Map `send` / `send_with_template` to Formable email delivery.
  </Card>

  <Card title="Embedded signing walkthrough" icon="window-maximize" href="/walkthroughs/embedded-signing">
    Full Formable signing walkthrough.
  </Card>

  <Card title="Webhooks" icon="bell" href="/webhooks/overview">
    Register endpoints and understand delivery.
  </Card>
</CardGroup>