Embedded Signing

Overview

Embedded signing lets your recipients sign documents inside your own application, for example in an iframe, instead of following an email link to the hosted signing UI. You control the whole experience. No automatic emails are sent to embedded recipients, signing links are generated on demand through the API, and the session hands control back to your application when it ends.

The flow has four steps. Create an envelope with an embedded recipient, send the envelope, create a short-lived embed link, and render it inside your application.

Create an envelope with an embedded recipient

Mark a recipient for embedded signing by setting embedded: true when creating the envelope. You can mix embedded and email recipients on the same document. Email recipients receive the normal signature request email, embedded recipients do not.

1curl \2  -H "Content-Type: application/json" \3  -H "Authorization: Bearer YOUR_API_KEY" \4  --request POST \5  --data '{6    "requesterName": "Your App",7    "documents": [8      {9        "sourceDocumentId": "69c2da76486b40749734ab00",10        "name": "Rental Agreement",11        "recipients": [12          {13            "email": "RECIPIENT_EMAIL",14            "name": "John Peterson",15            "embedded": true16          }17        ]18      }19    ]20  }' \21  https://api.pdfgate.com/envelope

The response includes a recipientId for every recipient. Store it, because the embed link is created with it. The same person keeps the same recipientId across envelopes, and you can attach your own user id to the recipient with the Update Recipient endpoint's metadata.

Send the envelope

Sending activates the envelope. Embedded recipients receive no email; for them, sending simply makes the envelope signable.

1curl \2  -H "Authorization: Bearer YOUR_API_KEY" \3  --request POST \4  https://api.pdfgate.com/envelope/{envelopeId}/send

Create the embed link

Right before showing the signing session, create an embed link with the Create Embed Link endpoint. The link expires 10 minutes after creation, so create a fresh one per session instead of storing it. The returnUrl is required. It is where the session redirects when it ends, and you can include your own query parameters for correlation, for example a session or flow id.

1curl \2  -H "Content-Type: application/json" \3  -H "Authorization: Bearer YOUR_API_KEY" \4  --request POST \5  --data '{6    "documentId": "{documentId}",7    "recipientId": "{recipientId}",8    "returnUrl": "https://app.example.com/signed?flow=abc123"9  }' \10  https://api.pdfgate.com/envelope/{envelopeId}/embed-link

Render the signing session

Render the returned urlinside your application. The signing page is designed to be embedded. It skips the OTP step, since your application has already authenticated the signer, and records the signer's e-sign consent with a checkbox at submission.

1<iframe2  src="EMBED_LINK_URL"3  style="width: 100%; height: 700px; border: none;"4  title="Sign document"5></iframe>

Handle the return redirect

When the session ends, the iframe navigates to your returnUrl with these query parameters appended (your own query parameters are preserved):

• event: signing_complete when the recipient signed, or voided, expired, not_found when the envelope was cancelled, expired, or deleted while the signer was mid-session.
• envelopeId, documentId, recipientId: identify the session that ended.

The page that loads is yours, so it can close the iframe, notify your frontend, or update your backend with full context.

Confirm results with webhooks

The redirect is a UI signal only, since anyone can navigate to your returnUrl manually. Use the envelope.recipient.signed and envelope.completed webhook events, or fetch the envelope, as the source of truth before treating a document as signed.