# Migrating to Signclad

> Move a DocuSign, Dropbox Sign, or PandaDoc integration to the Signclad eSignature API: what maps to what, when a base-URL swap is enough, and the order to do it in.

Source: https://signclad.com/docs/migration/

Move your integration in stages: test document creation and signing, recreate your templates, then switch new documents to Signclad.

## Configure your integration

Create an API key in [Settings → API keys](https://app.signclad.com/app/settings/api-keys). API access requires Light or above.

```sh
SIGNCLAD_BASE_URL=https://api.signclad.com/api/v1
SIGNCLAD_API_KEY=sk_test_...
```

Use the [API reference](https://signclad.com/docs/api/) to map your existing requests and responses to Signclad. Verify recipient roles, field coordinates, signing order, metadata, and webhook handling before sending live documents.

## Test the full signing flow

Create a test document, send it to addresses you control, sign it, and download the completed PDF. Test mode sends real emails with an explicit test notice. Documents are watermarked as not legally binding and excluded from billing.

Register a webhook endpoint with `include_test_mode: true` and verify the request signature. Confirm that your integration handles repeated events without repeating work.

## Recreate templates

Upload your original files and recreate the recipients, fields, and settings in Signclad. Store the new template IDs alongside your internal records. Test each template before switching it into production.

See [Templates](https://signclad.com/docs/templates/) and [Text tags](https://signclad.com/docs/text-tags/).

## Switch new documents

Use a live key for production. Direct new signing requests to Signclad and let documents already sent through your previous provider finish there. Keep the provider and document ID on each internal record so status updates reach the correct document.

Archive completed PDFs and audit records before closing your previous account. Cancel and recreate unfinished requests only when that is appropriate for the parties involved.

## When a base-URL swap is enough

Signclad's `/api/v1` is wire-compatible with one existing third-party eSignature API — the
**compatibility target** described in the [compatibility reference](https://signclad.com/docs/compatibility/). If that
is the API you are on today, the migration really is two lines: point the base URL at
`https://api.signclad.com/api/v1` and use a Signclad key. Paths, request fields, response fields,
status strings, error envelopes, and webhook event names are all preserved, quirks included.

If you are coming from any other provider, the swap does not apply and this is a port: the concepts
line up closely, the field names do not. The sections below map the concepts so you know what you
are looking for in the [API reference](https://signclad.com/docs/api/).

## From DocuSign

| DocuSign | Signclad |
|---|---|
| Envelope | Document — `POST /documents` |
| `envelopeId` | `id` (UUID) |
| Recipients: signers, carbon copies, certified deliveries | `recipients[]`, each with your own `id`; copy-only parties are `copied_contacts[]` |
| Recipient `routingOrder` | `signing_order` on the recipient, with `apply_signing_order: true` on the document |
| Tabs (`signHere`, `dateSigned`, `text`, `checkbox`) | `fields[][]` entries with `type` `signature`, `date`, `text`, `checkbox` |
| Anchor text (`anchorString`) | [Text tags](https://signclad.com/docs/text-tags/) — `text_tags: true`, then `[sig\|signer1\|req]` in the file |
| Templates and template roles | Templates and `placeholders[]`; a role is filled by `placeholder_name` on the recipient |
| Composite templates | `template_ids[]` on `POST /document_templates/documents` — several templates composed into one document |
| Connect webhooks | [Webhook endpoints](https://signclad.com/docs/webhooks/) with `event_types[]` and an HMAC body signature |
| Envelope status `sent` / `delivered` / `completed` | Document status `Sent` / `Viewed` / `Completed` — **capitalised** |
| Combined document download | `GET /documents/{id}/completed_pdf` — `404` until every signer has finished |

Authentication is the biggest structural difference: there is no account-scoped base URI to
discover and no OAuth token to refresh. One `X-Api-Key` header, and the key identifies the
workspace and the mode. Field coordinates are absolute, in units of 0.75 pt from the top-left of
the page, rather than anchor-relative offsets — or skip coordinates entirely and use text tags.

## From Dropbox Sign

| Dropbox Sign | Signclad |
|---|---|
| Signature request | Document — `POST /documents` |
| `signature_request_id` | `id` |
| `signers[]` with `order` | `recipients[]` with `signing_order` |
| `file_url[]` / `file[]` | `files[]` with `file_url`, `file_base64`, or a `file_id` from `POST /files` |
| `send_with_template` | `POST /document_templates/documents` with `template_id` |
| Template signer roles | `placeholders[]` on the template, bound by `placeholder_name` |
| `custom_fields` / prefill | `template_fields: [{ api_id, value }]` |
| Text tags (`[sig\|req\|signer1]`) | Text tags — Signclad's own syntax is nearly identical, and the compatibility target's positional syntax is accepted too |
| `test_mode: 1` | `test_mode: true` on the create body, or — better — a sandbox key (`sk_test_`), which makes every document from that key a test one and takes the flag out of your code path. |
| Callbacks with `event_hash` | Webhook endpoints. Signclad emits a compatibility hash *and* a real body signature; verify the body signature. |
| `is_complete` / `is_declined` booleans | A single `status` string, plus per-recipient `status` |

API keys move over as a header rather than HTTP Basic auth, and every response carries
`X-Request-Id` and the rate-limit headers — the lowercase `x-ratelimit-*` trio the compatibility
target sends, plus the additive seconds-based `RateLimit-*` trio most client libraries look for.

## From PandaDoc

| PandaDoc | Signclad |
|---|---|
| Document | Document |
| `Authorization: API-Key <key>` | `X-Api-Key: <key>` |
| Recipients with `role` | `recipients[]` with `placeholder_name` matching a template role |
| Template + tokens | Template + `template_fields` prefill by `api_id` |
| `document.uploaded` → `document.draft` polling | The transient `Created` status on the create response, settled on the next `GET` — same idea, one hop shorter |
| `document.completed` webhook | `document_completed` |
| Download `/documents/{id}/download` | `GET /documents/{id}/completed_pdf` |
| Content-authoring blocks | Not a Signclad concept. Signclad signs the files you supply — PDF, DOCX, images, HTML — and places fields on them. |

PandaDoc's proposal and quoting features have no Signclad equivalent. If you use PandaDoc purely to
collect signatures on files you already generate, the port is small; if you author content inside
it, keep authoring there and send the rendered PDF to Signclad.

## Recipient and role vocabulary

Whatever you are coming from, three rules hold:

- **Recipient `id` is yours.** You choose the string, fields reference recipients by it, and it comes
  back unchanged. Do not wait for the server to hand you a recipient id.
- **A template role is a `placeholder`.** Recipients bind to it by `placeholder_name`, and inherit
  every field belonging to that role.
- **A finished recipient is `completed`, never `signed`** — and recipient statuses are lowercase
  while document statuses are capitalised. See the
  [compatibility reference](https://signclad.com/docs/compatibility/).

## Verify before retiring the old integration

- Every active template has a tested Signclad template ID.
- New documents use the production key and intended recipients.
- Webhook signatures are verified and repeated events are handled safely.
- Completed PDFs and audit records remain accessible.
- No in-flight documents depend on credentials you are about to revoke.

## Related

- [Compatibility reference](https://signclad.com/docs/compatibility/) — the measured wire behaviour, including the quirks.
- [Getting started](https://signclad.com/docs/getting-started/)
- [Sandbox and test mode](https://signclad.com/docs/sandbox-and-test-mode/)
- [Webhooks](https://signclad.com/docs/webhooks/)
- [Embedded signing](https://signclad.com/docs/embedded-signing/)