Migrate to SignatureAPI
Migrate from Dropbox Sign
Map Dropbox Sign (HelloSign) signature requests, form fields, text tags, templates, callbacks and embedded signing to SignatureAPI envelopes and webhooks.
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) | 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. |
| Signature request | Envelope | Documents plus recipients. Creating an envelope sends it. |
files or file_urls (send) | Document url | A file URL per document: upload the file first, or link a file on a supported host. |
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. |
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 plus 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) | 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) | DOCX document 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) | Custom authentication 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. |
Callbacks with event_hash and the “Hello API Event Received” response (events walkthrough) | Webhooks signed with the Standard Webhooks scheme | JSON body; any 2XX response acknowledges the event. |
signature_request_all_signed, then signature_request_downloadable (events) | envelope.completed, then deliverable.generated | Download the signed PDF after deliverable.generated. |
signature_request/files (files) | Deliverable | One PDF with the signed documents and, for the standard type, the audit log. |
test_mode: true per request (send) | 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 reference:
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:
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. 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:
{
"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.
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). 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.
Event names come from the Dropbox Sign 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_modefrom requests and use a test key. - No client ID for embedding. The origins you list in
embeddable_inare 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
- Create a test API key in the Dashboard and send it in
X-API-Key. - Move files to uploads or a supported host, and convert text tags to
[[place_key]]placeholders. - Rewrite each signature request as an envelope: signers with keys, form fields as places.
- Convert templates to DOCX files with
{{field}}merge fields. - Add a webhook endpoint in the Dashboard and switch verification to Standard Webhooks.
- Run your flows in test mode, then switch to a live key.