---
title: "Migrate from DocuSign"
description: "Map DocuSign eSignature REST API envelopes, tabs, templates, Connect and embedded signing to SignatureAPI envelopes, places, webhooks and ceremonies."
canonical: "https://signatureapi.com/docs/migrate/docusign"
source: "https://signatureapi.com/docs/migrate/docusign.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T17:33:13Z"
---

# Migrate from DocuSign

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

_Last verified against API version 1.18.0._

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

| DocuSign                                                                                                                                                                               | SignatureAPI                                                                                                              | Notes                                                                                                                                                                                                                                                 |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| OAuth access token in `Authorization: Bearer` ([auth](https://developers.docusign.com/docs/esign-rest-api/esign101/auth/))                                                             | API key in the `X-API-Key` header                                                                                         | No token exchange or refresh. A `key_test_` key works in test mode, a `key_live_` key in live mode. See [Authentication](https://signatureapi.com/docs/api/authentication).                                                                           |
| Account ID in every path (`/accounts/{accountId}/...`) ([base paths](https://developers.docusign.com/platform/api-endpoint-base-paths))                                                | Not needed                                                                                                                | The API key identifies the account. Every request goes to `https://api.signatureapi.com/v1`.                                                                                                                                                          |
| Envelope                                                                                                                                                                               | [Envelope](https://signatureapi.com/docs/api/resources/envelopes/object)                                                  | Same idea: documents plus recipients. Creating an envelope sends it.                                                                                                                                                                                  |
| Document with `documentBase64` ([create envelope](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/create/))                                          | [Document](https://signatureapi.com/docs/api/resources/documents/object) with a `url`                                     | Upload the file first with [`POST /v1/uploads`](https://signatureapi.com/docs/api/resources/uploads/create) and pass the returned URL, or link a file on a [supported host](https://signatureapi.com/docs/api/resources/documents/url). PDF and DOCX. |
| Signer recipient with `routingOrder`                                                                                                                                                   | Recipient with `type: "signer"`                                                                                           | With `routing: "sequential"`, recipients sign in the order of the `recipients` array. See [Routing](https://signatureapi.com/docs/api/resources/envelopes/routing).                                                                                   |
| Other recipient types (carbon copies, certified deliveries, editors, and more) ([recipients](https://developers.docusign.com/docs/esign-rest-api/esign101/concepts/recipients/))       | `signer`, `approver`, `preparer`, `automatic_signer`                                                                      | There 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](https://signatureapi.com/docs/api/resources/recipients/object).                  |
| Tabs (`signHereTabs`, `textTabs`, ...)                                                                                                                                                 | [Places](https://signatureapi.com/docs/api/resources/places/object)                                                       | Places belong to a document and name their recipient with `recipient_key`.                                                                                                                                                                            |
| Anchor tabs (`anchorString` plus offsets) ([auto-place](https://developers.docusign.com/docs/esign-rest-api/esign101/concepts/tabs/auto-place/))                                       | [Placeholders](https://signatureapi.com/docs/api/resources/places/positioning#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](https://developers.docusign.com/docs/esign-rest-api/esign101/concepts/tabs/fixed/))                                       | [`fixed_positions`](https://signatureapi.com/docs/api/resources/places/positioning#fixed-positions)                       | `top` and `left` in points from the top-left corner of the page.                                                                                                                                                                                      |
| Server templates with roles ([templates](https://developers.docusign.com/docs/esign-rest-api/esign101/concepts/templates/))                                                            | DOCX [document templates](https://signatureapi.com/docs/api/resources/documents/templates)                                | Keep 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](https://developers.docusign.com/docs/esign-rest-api/esign101/concepts/tabs/prefilled-tabs/))                                          | Template fields `{{field}}` filled from `data`                                                                            | The values become part of the document text before signing.                                                                                                                                                                                           |
| Embedded signing with `clientUserId` and `createRecipientView` ([embedded signing](https://developers.docusign.com/docs/esign-rest-api/esign101/concepts/embedding/embedded-signing/)) | [Custom authentication](https://signatureapi.com/docs/api/resources/ceremonies/authentication/custom) and `embeddable_in` | The ceremony URL comes back on the recipient, with no extra call. See [Embedding in a Web Application](https://signatureapi.com/docs/embedded/web-app).                                                                                               |
| Connect with HMAC headers `X-DocuSign-Signature-1` ([HMAC](https://developers.docusign.com/platform/webhooks/connect/hmac/))                                                           | [Webhooks](https://signatureapi.com/docs/api/webhooks) signed with the Standard Webhooks scheme                           | Verify `webhook-id`, `webhook-timestamp` and `webhook-signature` over the raw body. Endpoints are set up in the Dashboard.                                                                                                                            |
| `envelope-completed` event ([event triggers](https://developers.docusign.com/platform/webhooks/connect/event-triggers/))                                                               | `envelope.completed`, then `deliverable.generated`                                                                        | Download the signed PDF after `deliverable.generated`.                                                                                                                                                                                                |
| `documents/combined` and `documents/certificate` ([get document](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopedocuments/get/))                      | [Deliverable](https://signatureapi.com/docs/api/resources/deliverables/object)                                            | One PDF with the signed documents and, for the `standard` type, the audit log.                                                                                                                                                                        |
| Developer environment on `demo.docusign.net` ([base paths](https://developers.docusign.com/platform/api-endpoint-base-paths))                                                          | [Test mode](https://signatureapi.com/docs/api/test-mode)                                                                  | Same 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](https://developers.docusign.com/docs/esign-rest-api/how-to/request-signature-email-remote/) 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](https://signatureapi.com/docs/api/resources/uploads/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](https://signatureapi.com/docs/api/resources/envelopes/lifecycle).

## Embedded signing

DocuSign creates the envelope with a `clientUserId` on the recipient, then calls `createRecipientView` for a short-lived URL ([reference](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopeviews/createrecipient/)). 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](https://signatureapi.com/docs/api/resources/ceremonies/create). The [tutorials](https://signatureapi.com/docs/tutorials/node) build the whole flow in seven languages.

## Webhooks

DocuSign Connect signs each message with one `X-DocuSign-Signature-N` header per HMAC key ([validate](https://developers.docusign.com/platform/webhooks/connect/validate/)). SignatureAPI follows the [Standard Webhooks](https://github.com/standard-webhooks/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](https://signatureapi.com/docs/api/webhooks#authentication).

Map the events you handle (Connect names from DocuSign's [event triggers](https://developers.docusign.com/platform/webhooks/connect/event-triggers/)):

| Connect event         | SignatureAPI event    |
| --------------------- | --------------------- |
| `envelope-sent`       | `envelope.started`    |
| `envelope-completed`  | `envelope.completed`  |
| `envelope-declined`   | `recipient.rejected`  |
| `envelope-voided`     | `envelope.canceled`   |
| `recipient-completed` | `recipient.completed` |

Every event is listed in [Events](https://signatureapi.com/docs/api/resources/events/object).

## What works differently

- **Documents are fetched, not embedded.** Requests carry a file URL, not base64 bytes. Upload private files with [`POST /v1/uploads`](https://signatureapi.com/docs/api/resources/uploads/create).
- **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](https://dashboard.signatureapi.com) 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.
