Skip to content

Migrate to SignatureAPI

Migrate from DocuSign

Map DocuSign eSignature REST API envelopes, tabs, templates, Connect and embedded signing to SignatureAPI envelopes, places, webhooks and ceremonies.

This guide maps the parts of a DocuSign eSignature REST API v2.1 integration to SignatureAPI, with a before-and-after request for the most common call. DocuSign facts link to DocuSign’s developer documentation; check them against your own integration, since accounts differ in settings and plan features.

Concept map

DocuSignSignatureAPINotes
OAuth access token in Authorization: Bearer (auth)API key in the X-API-Key headerNo token exchange or refresh. A key_test_ key works in test mode, a key_live_ key in live mode. See Authentication.
Account ID in every path (/accounts/{accountId}/...) (base paths)Not neededThe API key identifies the account. Every request goes to https://api.signatureapi.com/v1.
EnvelopeEnvelopeSame idea: documents plus recipients. Creating an envelope sends it.
Document with documentBase64 (create envelope)Document with a urlUpload the file first with POST /v1/uploads and pass the returned URL, or link a file on a supported host. PDF and DOCX.
Signer recipient with routingOrderRecipient with type: "signer"With routing: "sequential", recipients sign in the order of the recipients array. See Routing.
Other recipient types (carbon copies, certified deliveries, editors, and more) (recipients)signer, approver, preparer, automatic_signerThere is no carbon-copy type. Signers receive the signed PDF by email by default; approvers and preparers can opt in with delivery_type: "email". See Recipients.
Tabs (signHereTabs, textTabs, …)PlacesPlaces belong to a document and name their recipient with recipient_key.
Anchor tabs (anchorString plus offsets) (auto-place)Placeholders [[place_key]]The place renders over the placeholder text. There are no offsets: put the placeholder where the field goes.
Fixed tabs (xPosition, yPosition, pageNumber) (fixed)fixed_positionstop and left in points from the top-left corner of the page.
Server templates with roles (templates)DOCX document templatesKeep the DOCX file in your own storage and send its values in the document’s data. No template object is stored on the API side.
Prefilled tabs (prefillTabs) (prefilled tabs)Template fields {{field}} filled from dataThe values become part of the document text before signing.
Embedded signing with clientUserId and createRecipientView (embedded signing)Custom authentication and embeddable_inThe ceremony URL comes back on the recipient, with no extra call. See Embedding in a Web Application.
Connect with HMAC headers X-DocuSign-Signature-1 (HMAC)Webhooks signed with the Standard Webhooks schemeVerify webhook-id, webhook-timestamp and webhook-signature over the raw body. Endpoints are set up in the Dashboard.
envelope-completed event (event triggers)envelope.completed, then deliverable.generatedDownload the signed PDF after deliverable.generated.
documents/combined and documents/certificate (get document)DeliverableOne PDF with the signed documents and, for the standard type, the audit log.
Developer environment on demo.docusign.net (base paths)Test modeSame base URL, a test key. Test envelopes are free, send no emails and are not legally binding.

Send a document for signature

Before. DocuSign’s request a signature by email example sends one document to one signer, with a signature tab anchored to the text /sn1/:

HTTP
POST /restapi/v2.1/accounts/{accountId}/envelopes HTTP/1.1
Host: demo.docusign.net
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "emailSubject": "Please sign this document set",
  "documents": [{ "documentBase64": "<base64>", "name": "Battle Plan", "fileExtension": "docx", "documentId": "1" }],
  "recipients": {
    "signers": [{
      "email": "{SIGNER_EMAIL}", "name": "{SIGNER_NAME}", "recipientId": "1", "routingOrder": "1",
      "tabs": { "signHereTabs": [{ "anchorString": "/sn1/", "anchorUnits": "pixels", "anchorXOffset": "20", "anchorYOffset": "10" }] }
    }]
  },
  "status": "sent"
}

After. The same envelope in SignatureAPI. The document is a URL, the signature tab is a place, and the place’s position is set with fixed_positions:

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" }
  ]
}

To keep text-based positioning, replace each anchor string in your files with a placeholder such as [[client_signature]] and drop fixed_positions. To check which placeholders a file contains, call Retrieve upload structure on the upload.

The signer gets an email with a link to the ceremony. The envelope starts in processing and moves to in_progress when it is ready to sign. See the envelope lifecycle.

Embedded signing

DocuSign creates the envelope with a clientUserId on the recipient, then calls createRecipientView for a short-lived URL (reference). In SignatureAPI, give the recipient custom authentication and list your page’s origin in embeddable_in:

JSON
{
  "type": "signer",
  "key": "client",
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "delivery_type": "none",
  "ceremony": {
    "authentication": [{ "type": "custom", "provider": "Acme Corp Portal", "data": { "user_id": "usr_1042" } }],
    "embeddable_in": ["https://app.acme.example"]
  }
}

Read recipients[].ceremony.url once the envelope is in_progress, add embedded=true, and load it in an iframe. When the URL expires, read the envelope again or call Create Ceremony. The tutorials build the whole flow in seven languages.

Webhooks

DocuSign Connect signs each message with one X-DocuSign-Signature-N header per HMAC key (validate). SignatureAPI follows the Standard Webhooks scheme: compute an HMAC-SHA256 over webhook-id.webhook-timestamp.body with the endpoint’s signing secret and compare it with webhook-signature. Verification code is in Webhooks.

Map the events you handle (Connect names from DocuSign’s event triggers):

Connect eventSignatureAPI event
envelope-sentenvelope.started
envelope-completedenvelope.completed
envelope-declinedrecipient.rejected
envelope-voidedenvelope.canceled
recipient-completedrecipient.completed

Every event is listed in Events.

What works differently

  • Documents are fetched, not embedded. Requests carry a file URL, not base64 bytes. Upload private files with POST /v1/uploads.
  • No stored templates. DOCX templates live in your storage; each envelope sends the values it needs in data.
  • No carbon-copy recipients. Send the signed PDF to other people from your app after deliverable.generated.
  • Recipient keys, not IDs. You choose each recipient’s key and places refer to it, so there are no numeric recipientId or documentId values to track.

Migration checklist

  1. Create a test API key in the Dashboard and replace the OAuth flow with the X-API-Key header.
  2. Move documents to uploads or a supported host, and convert anchor strings to [[place_key]] placeholders.
  3. Rewrite each envelope request: recipients with keys, tabs as places.
  4. Convert server templates to DOCX templates 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.