Embedded Signing
Let an agent scaffold this for you
Install the TurboDocx Quickstart Skill and let Claude Code, Cursor, Copilot, Codex, or any agent that speaks the Agent Skills standard install the SDK, wire it into your app, and write a working TurboSign integration end-to-end.
$npx skills add TurboDocx/quickstart›/turbodocx-sdk turbosignEmbedded signing takes a signer straight from your own UI to a TurboSign signing page, without signing-link emails. Your backend asks TurboSign for a signing URL when the signer is ready, and your app opens it in an iframe, a new tab, or a redirect.
At a glance:
- Your signer never leaves your app. The signing page appears inside your product, and no signing-link email is needed.
- Your API key stays on your server. The browser only ever sees a per-signer URL.
- Each signer is verified your way. Use an email or SMS passcode, or your own identity verification vendor. The sender override skips verification while you test.
- The signer's real email is the signer of record, and the verification lands on the certificate of completion and in the audit trail.
- You get a completion event in the browser, and the
completedwebhook on your server.
How it works
Every embedded signing integration makes the same four moves:
- Your app asks your server for a signing session. Your server creates the document and asks TurboDocx for a signing URL for one signer.
- The signing URL comes back to your app, which shows it, usually in an iframe.
- The signing page verifies the signer and collects the signature.
- The signing page tells your app it finished with a
turbosign:completedmessage, and your server confirms the result.
Choose how signers verify
Give every embedded signer a verification method. Your app shows the signing page itself and TurboSign emails no link, so a check is what ties the person at the screen to the signer of record.
If you set no verification on a signer and your organization verifies only when requested, TurboSign still issues a reusable signing link, and anyone holding it can sign. If your organization verifies on every signature request, the signer gets your organization's default method instead. See A recipient with no verification is unprotected.
| Method | Who verifies the signer | Signing URL |
|---|---|---|
| Email or SMS passcode | TurboSign sends a code before the document opens | Reusable for the life of the document |
| External identity verification | Your identity provider; your backend asserts the result | Single-use, expires in about five minutes |
| Sender override | Nobody (testing only, marked not identity-verified) | Single-use, expires in about five minutes |
The Identity verification section compares them in full, including which ones also work for signers you email.
Choose your path
| You want to... | Signer verifies with | Front end | Guide |
|---|---|---|---|
| Write the least code in a React app | Email passcode | The React TurboSignForm component | React widget |
| Keep full control of the iframe, in any framework | Email passcode | Your own iframe and message listener | Your own iframe |
| Use Vue, Angular, Svelte or plain HTML | Email passcode | The turbosign-form web component | Web component |
| Have two or more people sign in order on one device | An email passcode each | Any | Kiosk signing (two signers, one device) |
| Verify signers by text message | SMS passcode | Any | Passcodes in embedded signing |
| Reuse a check your identity vendor already ran | Your identity provider | Any | External identity verification |
| Try the flow in development without verification | Nothing (marked not identity-verified) | Any | Sender override for testing |
They check the message origin and surface the completion event for you. Choose your own iframe only when you need full control of the frame.
Before you start
You need these in place before any guide works:
- An admin has turned on embedded signing. In Settings > Features and integrations > Signatures card > Configure E-Signature > Identity Verification, the Enable identity verification switch is on. Despite its name, it is the master switch for embedded signing and every verification mode.
- Your app's origin is allowed. On the Identity & embedding tab, your origin (for example
https://app.yourcompany.com) is under Allowed embedding domains. - You have an API key with the right role: an Administrator or Contributor key.
- Your PDF has text anchors where fields go, for example
{signature1}and{date1}. - The TurboDocx SDK is installed on your server. See the TurboSign SDK for your language.
Set up your organization walks an admin through steps 1 and 2 with screenshots.
Embedding is denied by default. Until an admin adds your app's origin under Allowed embedding domains, the iframe stays blank. That is the clickjacking protection working, not a bug.
Requesting a signing URL needs an Administrator or Contributor key. A User-role key can create the document, but the signing URL request fails with HTTP 403.
You can allow http://localhost origins to test on your machine. Remove every http:// origin before you go live; production origins must be https://.
The flow, end to end
- Your backend prepares the document with an embedded recipient and
sendEmail: false, then stores the returneddocumentIdon the customer record. - Your app shows a "Sign now" button. Clicking it calls your backend, not a stored link.
- Your backend confirms the signed-in user matches the customer record, calls
createSigningUrl, and returns the URL. - The signing page verifies the signer (a passcode, the asserted external verification, or nothing for override) and shows the document.
- The signer signs. The page posts
turbosign:completed, and TurboSign returns the signer to yourreturnUrlif you set one. - The
completedwebhook updates your record. Download the signed PDF; the certificate shows the identity-verification line.
The API reference has every request and response field.
Common errors
| HTTP | code | What to do |
|---|---|---|
| (blank iframe) | none | Add your exact origin under Allowed embedding domains. |
| 403 | none (a plain 403 Forbidden) | The API key belongs to a User. Use an Administrator or Contributor key. |
| 403 | EmbeddedSigningNotEnabled | Ask an admin to turn on Enable identity verification. |
| 403 | OtpOverrideNotAllowed | Your organization locked the passcode method. Omit the channel, or ask an admin to let senders change it. |
| 409 | RecipientNotInTurn | An earlier signer has not finished. Mint this signer's URL when it is their turn. |
| 410 | SigningUrlNotRedeemable | A single-use URL was used or expired. Request a new one. |
Every error code is in the API reference.
Good practice
- Never store a signing URL. Request one when the signer clicks. Passcode signers get a reusable link that lasts as long as the document; external identity verification and override signers get a single-use link that expires after about five minutes.
- Verify the signer in your own app first. Confirm the logged-in user is the recipient before you request a URL.
- Use
externalIdto reference a signer by your own record (an Airtable row, a CRM contact) instead of storing TurboDocx's recipient id. - Set allowed embedding domains before you iframe the signing page.
- Confirm completion on your server. Treat the browser event as a hint, and rely on the document status or the
completedwebhook.
Next
Set up your organization, then pick a guide from Choose your path.