Docusign → Embedded signing

This guide helps you move a Docusign embedded signing integration to Formable. You still create a send, mint a recipient signing URL, embed it, and download the completed PDF. You drop OAuth account paths, clientUserId, and returnUrl redirects in favor of Bearer API keys, a simpler create payload, and webhook- or poll-driven completion. If you also prepare templates inside your product, migrate that first with Docusign → Embedded templates. Formable signing always starts from a prepared template.

New to Formable? Complete the Embedded signing walkthrough first, then use this page as a translation layer from Docusign envelopes and recipient views.

Prefer a white-glove migration? Email matt@formabledocs.com and we’ll handle moving your Docusign integration to the Formable API.

What you’re moving

In Docusign you typically:

Authenticate with OAuth and call account-scoped REST paths
Create an envelope with a recipient that has a clientUserId (embedded / captive signer)
Call EnvelopeViews:createRecipientView with matching identity fields plus a returnUrl
Redirect or iframe the view URL (often ~5 minute TTL)
Detect completion via Connect / eventNotification or the returnUrl query event, then download documents

In Formable you:

Authenticate with a Bearer API key (fmbl_…)
Create an embedded signature request from a templateId with a signers array (each with email, name, and role)
Mint a signingUrl from each signer’s recipientSignatureId (no clientUserId, no returnUrl)
Load it in a plain iframe (URL lasts 1 hour)
Handle document_completed or poll status, then download the signed envelope

The product journey stays the same: prepare a document, send it, embed signing, react when done. The API surface is smaller and organization-scoped by the key rather than by accountId in the path.

Recommended order of work

Get a Formable API key

Create an organization and key in Settings. See Authentication. You do not need JWT or Authorization Code exchange for the standard integration.

Migrate templates and field IDs

Re-upload documents and place fields in Formable. If you embed template editing, follow Embedded templates migration.

Replace Envelopes:create

Map template roles and tab values to signers, sender, and optional fields.

Replace createRecipientView

Call create signing URL; drop clientUserId, returnUrl, and authenticationMethod.

Swap Connect for Formable webhooks

What’s similar

Several Docusign ideas transfer directly:

A reusable template still backs many sends.
You still create a send unit (envelope → signature request), then open a short-lived URL for the signer.
Prefill / tab values still happen at send time; Formable uses fields: [{ fieldId, value }].
Demo / non-billing traffic maps to testMode: true (instead of relying only on a demo account). Test mode documents are watermarked and are not legally binding.
After completion you still fetch a combined signed PDF.

If your Docusign flow is “create envelope from template → create recipient view → iframe → Connect → download,” you are remapping objects and removing embedded-signer bookkeeping, not redesigning the user journey.

What’s different

These Docusign-specific pieces do not carry over:

Area	Docusign	Formable
Auth	OAuth access token + `/accounts/{accountId}/...`	Bearer `fmbl_…`; no `accountId` in the path
Embedded marker	Recipient `clientUserId`	Embedded by default once you mint a `signingUrl`
View request	Match email / userName / `clientUserId`; require `returnUrl`	POST create URL with the signer’s `recipientSignatureId`
Completion UX	Often `returnUrl` redirect with an `event` query param	`onSigningComplete` iframe message for UI; confirm with webhooks or polling
View TTL	Commonly ~5 minutes	1 hour
Webhooks	Connect / `eventNotification`, `X-DocuSign-Signature-1`	Org-level URL, `Content-Sha256`
Roles	`templateRoles` / `roleName`	`signers[].role` (match template field roles)

You no longer maintain a parallel “captive signer” identity. Create the request when you’re ready to send, mint the URL when the user is ready to sign, and listen for completion out of band.

Concept map

Docusign	Formable	Notes
OAuth access token	API key (`Authorization: Bearer fmbl_…`)	No JWT / Auth Code for the standard integration.
Account (`accountId`)	Organization	Implied by the API key.
Envelope	Signature request	Formable’s send unit.
Recipient + `clientUserId`	`signers[]` with `email`, `name`, and `role`	Embedded by default — no `clientUserId`. Save each `recipientSignatureId`.
Recipient view URL	`signingUrl`	Expires after 1 hour (Docusign ~5 minutes).
`returnUrl`	`onSigningComplete` `postMessage`	Close the iframe from the client event; confirm via webhooks or polling.
Connect / `eventNotification`	Webhooks	Org-level URL + `Content-Sha256`.
Envelope `completed`	`document_completed` / status `Completed`	Then fetch the signed PDF.

Endpoint map

Docusign	Formable
`POST /v2.1/accounts/{accountId}/envelopes`	`POST /v1/signature-requests/embedded`
`POST .../envelopes/{envelopeId}/views/recipient`	`POST /v1/recipient-signatures/{id}/url`
Get document / combined PDF	`GET /v1/signature-requests/{id}/signed-envelope`
Connect / `eventNotification`	Webhook URL in Settings

Auth

Docusign:

Authorization: Bearer {access_token}

against /restapi/v2.1/accounts/{accountId}/.... Formable:

curl https://api.formabledocs.com/v1/signature-requests \
  --header "Authorization: Bearer fmbl_YOUR_API_KEY"

No accountId in the path. Create the key in Settings and keep it on the server. Full details: Authentication.

Migrate the flow

1. Create the signature request (was: create envelope)

Docusign (simplified):

{
  "templateId": "DOCUSIGN_TEMPLATE_ID",
  "templateRoles": [
    {
      "email": "jane@example.com",
      "name": "Jane Doe",
      "roleName": "Signer",
      "clientUserId": "1000",
      "tabs": {
        "textTabs": [
          { "tabLabel": "company", "value": "Acme Corporation" }
        ]
      }
    }
  ],
  "status": "sent"
}

Formable:

curl --request POST \
  --url https://api.formabledocs.com/v1/signature-requests/embedded \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "templateId": "abc123xyz",
    "signers": [
      { "email": "jane@example.com", "name": "Jane Doe", "role": "Signer" }
    ],
    "sender": { "email": "you@yourcompany.com", "name": "Your Company" },
    "fields": [
      { "fieldId": "field_company_name", "value": "Acme Corporation" }
    ],
    "testMode": true
  }'

Response

{
  "signatureRequestId": "sr_456def",
  "signers": [
    {
      "email": "jane@example.com",
      "name": "Jane Doe",
      "recipientSignatureId": "rsig_789ghi"
    }
  ]
}

Pass a signers array on every create. Each signer needs email, name, and role. sender is optional and defaults to the org owner. Map tab / merge values to fields using Formable fieldIds from the template editor (not Docusign tabLabels). Save each signer’s recipientSignatureId to mint their signing URL.

Docusign	Formable
`templateId`	`templateId`
`templateRoles[].email` / `name`	`signers[].email` / `name`
`roleName`	`signers[].role`
`clientUserId`	Omit
Tab values on the role	`fields: [{ fieldId, value }]`
`status: "sent"`	Create, then mint the URL when ready
Demo account testing	`testMode: true` (watermarked, not legally binding)

2. Create the signing URL (was: recipient view)

Docusign:

POST /v2.1/accounts/{accountId}/envelopes/{envelopeId}/views/recipient

{
  "returnUrl": "https://yourapp.com/signing-complete",
  "authenticationMethod": "none",
  "email": "jane@example.com",
  "userName": "Jane Doe",
  "clientUserId": "1000"
}

Formable:

curl --request POST \
  --url https://api.formabledocs.com/v1/recipient-signatures/rsig_789ghi/url \
  --header "Authorization: Bearer $TOKEN"

Response

{
  "signingUrl": "https://app.formabledocs.com/sign/embedded/xyz789abc",
  "expiresAt": "2024-01-16T10:30:00.000Z"
}

No clientUserId, returnUrl, or authenticationMethod. You do not re-send the signer’s email and name on the URL call — pass their recipientSignatureId from the create response. Formable URLs last 1 hour. Creating a URL for an already completed request returns 409.

3. Embed on the client

<iframe
  src="https://app.formabledocs.com/sign/embedded/xyz789abc"
  width="100%"
  height="800"
  allow="fullscreen"
  style="border: none;"
></iframe>

window.addEventListener("message", (event) => {
  if (event.origin !== "https://app.formabledocs.com") return;
  if (!event.data || typeof event.data !== "object") return;

  if (event.data.type === "onSigningComplete") {
    // signer finished — close the iframe or show success
  }
});

Use onSigningComplete instead of a Docusign returnUrl redirect for client UX. Confirm completion with document_completed or by polling status until Completed before downloading. See Embedded signing.

4. Download the signed PDF

curl --request GET \
  --url https://api.formabledocs.com/v1/signature-requests/sr_456def/signed-envelope \
  --header "Authorization: Bearer $TOKEN"

Response

{
  "signedEnvelopePresignedUrl": "https://s3.amazonaws.com/bucket/signed-envelope.pdf?..."
}

Webhook verification uses Content-Sha256 instead of X-DocuSign-Signature-1. See Verifying webhooks and Webhooks overview.

Differences to plan for

API keys instead of OAuth

Drop JWT / Auth Code token exchange for a Bearer API key on your server. The organization is implied by the key, so paths omit accountId.

No clientUserId

Embedded is the default. Create the request, then mint the URL when the user is ready. You do not mark recipients as captive at create time.

No returnUrl redirect

Listen for onSigningComplete to update the client immediately. Confirm with a webhook or poll before downloading, then build any “signing finished” screen in your own app.

Longer-lived signing URLs

Plan refresh logic around a 1 hour TTL instead of Docusign’s shorter recipient-view window. Still mint just in time; don’t store URLs for later sessions.

Checklist

Create a Formable API key

In Settings.

Prepare templates and field IDs

Or migrate the embedded template flow separately.

Replace Envelopes:create

Use create embedded signature request with signers (including role), optional sender, and optional fields.

Replace createRecipientView

Call create signing URL with each signer’s recipientSignatureId; drop clientUserId, returnUrl, and authenticationMethod.

Swap Connect for Formable webhooks

Handle document_completed and download the signed envelope.

Next steps

Embedded templates migration

Map Docusign template edit views to Formable.

Embedded signing walkthrough

Full Formable signing walkthrough.

Webhooks

Authentication

Bearer fmbl_ API keys.

Getting Started

Walkthroughs

SDKs

Migrations

Webhooks

Docusign → Embedded signing

What you’re moving

Recommended order of work

What’s similar

What’s different

Concept map

Endpoint map

Auth

Migrate the flow

1. Create the signature request (was: create envelope)

2. Create the signing URL (was: recipient view)

3. Embed on the client

4. Download the signed PDF

Differences to plan for

Checklist

Next steps

Embedded templates migration

Embedded signing walkthrough

Webhooks

Authentication

​What you’re moving

​Recommended order of work

​What’s similar

​What’s different

​Concept map

​Endpoint map

​Auth

​Migrate the flow

​1. Create the signature request (was: create envelope)

​2. Create the signing URL (was: recipient view)

​3. Embed on the client

​4. Download the signed PDF

​Differences to plan for

​Checklist

​Next steps

Embedded templates migration

Embedded signing walkthrough

Webhooks

Authentication

What you’re moving

Recommended order of work

What’s similar

What’s different

Concept map

Endpoint map

Auth

Migrate the flow

1. Create the signature request (was: create envelope)

2. Create the signing URL (was: recipient view)

3. Embed on the client

4. Download the signed PDF

Differences to plan for

Checklist

Next steps