Skip to content

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 SignSignatureAPINotes
API key as the HTTP Basic username, or an OAuth bearer token (authentication)API key in the X-API-Key headerA key_test_ key works in test mode, a key_live_ key in live mode. See Authentication.
Signature requestEnvelopeDocuments plus recipients. Creating an envelope sends it.
files or file_urls (send)Document urlA file URL per document: upload the file first, or link a file on a supported host.
signers with a zero-based orderRecipients with type: "signer" and a key you chooseWith routing: "sequential", recipients sign in the order of the recipients array. See Routing.
cc_email_addressesNo equivalentSigners 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_positionsA 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 templatesKeep the DOCX file in your storage. No template object is stored on the API side.
custom_fields merge valuesThe document’s dataValues 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_inNo 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 schemeJSON body; any 2XX response acknowledges the event.
signature_request_all_signed, then signature_request_downloadable (events)envelope.completed, then deliverable.generatedDownload the signed PDF after deliverable.generated.
signature_request/files (files)DeliverableOne PDF with the signed documents and, for the standard type, the audit log.
test_mode: true per request (send)Test mode by API keyA 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:

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. 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.

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 eventSignatureAPI event
signature_request_sentenvelope.started
signature_request_signedrecipient.completed
signature_request_all_signedenvelope.completed
signature_request_downloadabledeliverable.generated
signature_request_declinedrecipient.rejected
signature_request_canceledenvelope.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 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.