---
title: "Migrate from Dropbox Sign"
description: "Map Dropbox Sign (HelloSign) signature requests, form fields, text tags, templates, callbacks and embedded signing to SignatureAPI envelopes and webhooks."
canonical: "https://signatureapi.com/docs/migrate/dropbox-sign"
source: "https://signatureapi.com/docs/migrate/dropbox-sign.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T17:33:13Z"
---

# Migrate from Dropbox Sign

Map Dropbox Sign (HelloSign) signature requests, form fields, text tags, templates, callbacks and embedded signing to SignatureAPI envelopes and webhooks.

_Last verified against API version 1.18.0._

This guide maps the parts of a Dropbox Sign API v3 integration (formerly HelloSign) to SignatureAPI, with a before-and-after request for the most common call. Dropbox Sign facts link to the Dropbox Sign developer documentation.

## Concept map

| Dropbox Sign                                                                                                                                                                     | SignatureAPI                                                                                                                                                                 | Notes                                                                                                                                                                                                          |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API key as the HTTP Basic username, or an OAuth bearer token ([authentication](https://developers.hellosign.com/api/reference/authentication/))                                  | API key in the `X-API-Key` header                                                                                                                                            | A `key_test_` key works in test mode, a `key_live_` key in live mode. See [Authentication](https://signatureapi.com/docs/api/authentication).                                                                  |
| Signature request                                                                                                                                                                | [Envelope](https://signatureapi.com/docs/api/resources/envelopes/object)                                                                                                     | Documents plus recipients. Creating an envelope sends it.                                                                                                                                                      |
| `files` or `file_urls` ([send](https://developers.hellosign.com/api/reference/operation/signatureRequestSend/))                                                                  | [Document](https://signatureapi.com/docs/api/resources/documents/object) `url`                                                                                               | A file URL per document: [upload the file](https://signatureapi.com/docs/api/resources/uploads/create) first, or link a file on a [supported host](https://signatureapi.com/docs/api/resources/documents/url). |
| `signers` with a zero-based `order`                                                                                                                                              | Recipients with `type: "signer"` and a `key` you choose                                                                                                                      | With `routing: "sequential"`, recipients sign in the order of the `recipients` array. See [Routing](https://signatureapi.com/docs/api/resources/envelopes/routing).                                            |
| `cc_email_addresses`                                                                                                                                                             | No equivalent                                                                                                                                                                | Signers receive the signed PDF by email by default. Send copies to other people from your app.                                                                                                                 |
| `form_fields_per_document` (`x`, `y`, `width`, `height`, `signer` index)                                                                                                         | [Places](https://signatureapi.com/docs/api/resources/places/object) plus [`fixed_positions`](https://signatureapi.com/docs/api/resources/places/positioning#fixed-positions) | A place names its recipient with `recipient_key`. Positions use `top` and `left` in points.                                                                                                                    |
| Text tags such as `[sig\|req\|signer1]` with `use_text_tags` ([text tags](https://developers.hellosign.com/docs/guides/pre-filled-document-data/text-tags.md))                   | [Placeholders](https://signatureapi.com/docs/api/resources/places/positioning#placeholders) `[[place_key]]`                                                                  | Placeholders are always on: a `[[key]]` in the file positions the place with that key. Set the text white to hide it.                                                                                          |
| Templates and `send_with_template` with `template_ids` and roles ([send with template](https://developers.hellosign.com/api/signature-request/send-with-template.md))            | DOCX [document templates](https://signatureapi.com/docs/api/resources/documents/templates)                                                                                   | Keep the DOCX file in your storage. No template object is stored on the API side.                                                                                                                              |
| `custom_fields` merge values                                                                                                                                                     | The document's `data`                                                                                                                                                        | Values replace `{{field}}` merge fields in the DOCX file.                                                                                                                                                      |
| `create_embedded` plus `embedded/sign_url` and the `hellosign-embedded` library ([embedded signing](https://developers.hellosign.com/docs/embedded-signing/walkthrough/))        | [Custom authentication](https://signatureapi.com/docs/api/resources/ceremonies/authentication/custom) and `embeddable_in`                                                    | No client ID or client library: the ceremony URL comes back on the recipient and loads in a plain iframe. See [Embedding in a Web Application](https://signatureapi.com/docs/embedded/web-app).                |
| Callbacks with `event_hash` and the "Hello API Event Received" response ([events walkthrough](https://developers.hellosign.com/docs/guides/events-and-callbacks/walkthrough.md)) | [Webhooks](https://signatureapi.com/docs/api/webhooks) signed with the Standard Webhooks scheme                                                                              | JSON body; any `2XX` response acknowledges the event.                                                                                                                                                          |
| `signature_request_all_signed`, then `signature_request_downloadable` ([events](https://developers.hellosign.com/docs/events/overview/))                                         | `envelope.completed`, then `deliverable.generated`                                                                                                                           | Download the signed PDF after `deliverable.generated`.                                                                                                                                                         |
| `signature_request/files` ([files](https://developers.hellosign.com/api/signature-request/files.md))                                                                             | [Deliverable](https://signatureapi.com/docs/api/resources/deliverables/object)                                                                                               | One PDF with the signed documents and, for the `standard` type, the audit log.                                                                                                                                 |
| `test_mode: true` per request ([send](https://developers.hellosign.com/api/reference/operation/signatureRequestSend/))                                                           | [Test mode](https://signatureapi.com/docs/api/test-mode) by API key                                                                                                          | A test key makes every request a test. Test envelopes are free, send no emails and are not legally binding.                                                                                                    |

## Send a document for signature

**Before.** A Dropbox Sign request with one file URL, one signer and one signature field, built from the parameters on the [send signature request](https://developers.hellosign.com/api/reference/operation/signatureRequestSend/) reference:

```http
POST /v3/signature_request/send HTTP/1.1
Host: api.hellosign.com
Authorization: Basic {base64(API_KEY:)}
Content-Type: application/json

{
  "test_mode": true,
  "file_urls": ["https://example.com/doc.pdf"],
  "signers": [{ "name": "Jack", "email_address": "jack@example.com", "order": 0 }],
  "form_fields_per_document": [
    { "type": "signature", "document_index": 0, "api_id": "sig1", "signer": 0,
      "x": 100, "y": 600, "width": 200, "height": 40, "required": true, "page": 1 }
  ]
}
```

**After.** The same envelope in SignatureAPI. The field becomes a place, and the signer index becomes the recipient's `key`:

```http
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "title": "Service Agreement",
  "documents": [
    {
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "places": [
        { "key": "client_signature", "type": "signature", "recipient_key": "client" }
      ],
      "fixed_positions": [
        { "place_key": "client_signature", "page": 1, "top": 172, "left": 210 }
      ]
    }
  ],
  "recipients": [
    { "type": "signer", "key": "client", "name": "Jane Doe", "email": "jane.doe@example.com" }
  ]
}
```

A signature place takes an optional `height` in points (20 to 60, default 60) and gets its width from a 5:2 ratio, so there is no `width`. See [Signature](https://signatureapi.com/docs/api/resources/places/signature). If your files use text tags, replace each tag with a placeholder such as `[[client_signature]]` and drop `fixed_positions`.

## Templates and merge fields

Dropbox Sign templates hold the file, the roles and the fields, and `custom_fields` fills merge fields at send time. In SignatureAPI, the DOCX file is the template: write `{{candidateName}}` where a value goes and `[[candidate_signature]]` where a field goes, then pass the values in `data`:

```json
{
  "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/offer-letter-template.docx",
  "format": "docx",
  "data": {
    "date": "November 17, 2026",
    "candidateName": "Jane Doe",
    "jobTitle": "Product Designer",
    "startDate": "January 11, 2027",
    "salary": "$95,000"
  },
  "places": [
    { "key": "candidate_signature", "type": "signature", "recipient_key": "candidate" }
  ],
  "fixed_positions": [
    { "place_key": "candidate_signature", "page": 1, "top": 300, "left": 72 }
  ]
}
```

Conditions, loops and tables are covered in [Document Templates](https://signatureapi.com/docs/api/resources/documents/templates).

## Webhooks

Dropbox Sign posts callbacks as `multipart/form-data`, signs them with an `event_hash` keyed with your API key, and expects a body that contains "Hello API Event Received" ([walkthrough](https://developers.hellosign.com/docs/guides/events-and-callbacks/walkthrough.md)). SignatureAPI posts JSON, signs it with the endpoint's own signing secret, and accepts any `2XX` response. Verify the `webhook-id`, `webhook-timestamp` and `webhook-signature` headers over the raw body, as shown in [Webhooks](https://signatureapi.com/docs/api/webhooks#authentication).

Event names come from the Dropbox Sign [events overview](https://developers.hellosign.com/docs/events/overview/):

| Dropbox Sign event               | SignatureAPI event      |
| -------------------------------- | ----------------------- |
| `signature_request_sent`         | `envelope.started`      |
| `signature_request_signed`       | `recipient.completed`   |
| `signature_request_all_signed`   | `envelope.completed`    |
| `signature_request_downloadable` | `deliverable.generated` |
| `signature_request_declined`     | `recipient.rejected`    |
| `signature_request_canceled`     | `envelope.canceled`     |

## What works differently

- **Test mode is a key, not a flag.** Remove `test_mode` from requests and use a test key.
- **No client ID for embedding.** The origins you list in `embeddable_in` are the only setup.
- **No carbon copies.** Send the signed PDF to other people from your app after `deliverable.generated`.
- **Endpoints, not account callbacks.** Each webhook endpoint in the Dashboard has its own events and signing secret.

## Migration checklist

1. Create a test API key in the [Dashboard](https://dashboard.signatureapi.com) and send it in `X-API-Key`.
2. Move files to uploads or a supported host, and convert text tags to `[[place_key]]` placeholders.
3. Rewrite each signature request as an envelope: signers with keys, form fields as places.
4. Convert templates to DOCX files with `{{field}}` merge fields.
5. Add a webhook endpoint in the Dashboard and switch verification to Standard Webhooks.
6. Run your flows in test mode, then switch to a live key.
