Skip to main content
This is the page to read before writing the iframe; the machine-readable half is the API reference.

⚠️ Read this first: nothing in a browser is a completion signal

A postMessage from our iframe does not mean a document was signed, and there is no return_url on this API because a redirect does not mean it either. signed is a browser event. The signer can close the tab a millisecond before it fires, lose connectivity, have JavaScript blocked by an extension — and any script running on your own page can call postMessage with the same body, so it is not even evidence that it came from us unless you check event.origin. The webhook is authoritative. recipient.completed and envelope.completed are delivered from our servers to yours, signed and retried, and depend on nothing staying open. So: DocuSign appends ?event=signing_complete to their return URL and our own study records the consequence: “every first integration mistakes it for the truth”. This one is written down so that it is a decision rather than a discovery.

The shape of an integration

1. Register where you will embed — once, per brand

Settings → Brands → Embedding origins, one per line — or, from a key holding brands:write, one at a time with POST /api/v1/brands/{brandId}/embed-origins. See Brands. Origins must be bare: scheme, host, optional port. No trailing slash, no path, no wildcard, and https:// only.
⚠️ This is refused at registration rather than at render, and the reason is measured. Against Chromium, a frame-ancestors directive with a trailing slash still matches — so a browser tolerates it and teaches you the value is fine — while one carrying a path silently stops matching, and the only symptom is an iframe that never loads. Neither produces an error you could see. The moment you are still holding what you typed is the only useful moment to refuse it. Origins live on the brand, not on the API key. One key acts for every brand; each brand is one of your customers; each embeds on their own domain. ⚠️ They are a clickjacking defence for the signer, not an access boundary for you. Any key on the organisation that holds envelopes:write can mint a signing URL for any envelope of any brand.

2. Declare the recipient embedded, at creation

  • embedded: true is an explicit mode, not an inference from some other field being non-null, and it comes back on every recipient this API describes.
  • external_ref is your own identifier for that human. We store it, echo it, and use it for nothing.
  • ⚠️ An embedded recipient is never emailed. That is the point. No invitation, no reminder, no resend from the dashboard, no “email me a new link”, no notice that the document changed or was voided, and no completed copy: when their link expires, the page tells them to go back to yours, which can mint another. It is also why embedded: true is refused in two situations that would leave them unreachable: a role the template routes as cc (recipient_cannot_be_embedded), and a brand with no embedding origins registered (brand_has_no_embed_origins). That brand is the one the envelope goes out under — the brand_id you sent, or the organisation’s default when you sent none — so registering origins against the default while sending under another brand is refused.
  • The email address is still required, even though nothing is sent to it. It is on the certificate of completion and in the audit chain. Embedded signing says your application authenticated this person; it does not say they have no identity. Their entry on the certificate says so in those terms, and never that they were emailed: see what the certificate prints.
embedded cannot be changed afterwards. It decides how a human is reached, and an envelope that has gone out has already reached them.
  • Say who the form is about, if the template asks about people. For a template with conditional subjects, such as a co-tenant, subjects on the request decides what the signer meets inside your iframe: true or false settles the person with no question, and "ask" asks the signer who holds that person’s section a question at the start of signing, such as “Co-tenant: is there one on this form?”, which they answer before that section is shown or hidden. A conditional subject you do not name is left out, its fields hidden, and not asked about, whatever the template’s own choice says. So when your page should show no question, give every conditional subject true or false.
  • delegates_stay_embedded (optional, default false, only beside embedded: true) decides how somebody this signer delegates to is reached. Left out, that person is emailed. See When an embedded signer delegates.

3. Mint a URL when the signer arrives — not before

It lasts 10 minutes, or less if the envelope’s own deadline is sooner. Single use. The first GET spends it. ⚠️ url is a bearer credential for a legal act. Anyone holding it can open the document as that signer. Put it in an iframe src and nowhere else — not a log, not an analytics event, not a database column, not a support ticket. There is no endpoint that reads it back: only a digest is stored. ⚠️ expires_at is the life of the URL, not of the signing session. A signer who opens it just before it expires gets 1 hour from that moment to read and sign (again, less if the envelope’s deadline is sooner). Reload the iframe on this timer only if nobody ever opened it. ⚠️ Say where you will frame it. Send { "embed_origin": "https://app.example.com" } — your page’s window.location.origin — and a mint for an origin the brand has not registered is refused with embed_origin_not_registered, naming the origin and the brand, before anything is minted. Without it, an unregistered page gets a URL that works and a frame the browser refuses: a blank box for the signer, and no response anywhere to say why. Leaving it out changes nothing. The body may be at most 4096 bytes; a larger one is refused with invalid_request. Every refusal this call can answer, each with its own code so you can branch on it. The table is generated from the API reference, so it is the whole list: There is no Idempotency-Key on this call: the response is the credential, so “I do not know which state I am in” is unreachable, and a duplicate emails nobody and bills nothing. ⚠️ Redeeming a second URL does revoke the session a first one began.

4. Frame it

The page is served with
naming the origins registered against the brand this envelope was sent under, and with no X-Frame-Options. Those are the origins registered when the URL was minted: an origin you register afterwards does not apply to a URL already minted, so mint a new one. An origin you remove stops applying when the URL is opened — the session it starts is framed only for the origins still registered — while a session already open keeps the origins it opened with. An expired URL we minted — past the lifetime of the URL itself or of the session it began — is still framed for those same origins for 1 hour after it expires, so that the page inside can tell you it expired (step 5); it shows nothing of the document and nobody can sign through it. After that, and for any URL we cannot verify — unreadable or altered — the response carries X-Frame-Options: DENY instead, so the browser refuses to frame it and nothing inside it runs. The ordinary emailed signing page keeps X-Frame-Options: DENY unconditionally.

5. Listen

The origin says a message came from us, not from which of our frames: with two signers embedded on one page, both iframes share that origin, so event.source is what ties a message to this iframe and the ids are what tie it to the signer you minted for. Every action carries envelope_id and recipient_id — see the table below — so the id check never has to be skipped. When you re-mint for a replacement after delegated, update expected to the new recipient id. Every message this product will ever post is { action, ...payload } — one envelope, defined before there was a second surface to disagree with it. BoldSign has three shapes across three surfaces (params.data as a bare string, params.data.action, params.data.status) because nobody wrote one down first. ⚠️ delegated is not signed. The session is over for this recipient; the envelope is not finished. recipient.delegated follows on your webhook and names the new recipient: see the next section for what to do with it. signing_url_invalid reasons: ⚠️ Branch on can_remint. A host that re-mints on every refusal builds an infinite loop against this API the first time a signer finishes in another tab. Messages are posted to each registered origin and never to *, so a page we did not sanction learns nothing — including the envelope and recipient ids. expired means the credential in the src is past its lifetime. That is the URL’s 10 minutes — whether or not anybody opened it, so it does not tell you the signer never arrived — or the 1 hour of the session it began, and either can end sooner when the envelope’s deadline comes first. It arrives with can_remint: true: mint a new URL and replace the src. A session that runs out while the page stays open posts nothing at that moment — the signer’s next action is refused inside the frame — and posts expired the next time the frame loads. ⚠️ Some URLs post nothing at all. One we cannot read — truncated or altered on its way into the src — names no origin to post to and is refused a frame (X-Frame-Options: DENY, above), so no script of ours runs. So is one loaded more than 1 hour after it expired, because the origins it carries cannot be revoked and must not frame our pages indefinitely. For those, treat a ready that has not arrived after a reasonable timeout as “mint a new URL, once” — and if the second URL also produces no ready, stop and show something else rather than looping: the fault is in how the URL reaches the src, and minting again will not fix it.

When an embedded signer delegates

A signer can hand the document to somebody else from the signing page: a name, an address and a reason. That works inside your iframe too. The signer is retired, a new recipient takes their role, and recipient.delegated fires with the delegator’s id as recipient_id, the new recipient’s as delegate_recipient_id, and delegate_embedded. The body carries ids only: read the new recipient’s name and address from GET /api/v1/envelopes/{envelopeId}. By default the delegate is emailed. Your page has a seat for the person you authenticated, not for somebody they name, so the new recipient is an ordinary one: embedded: false, invited by email with a signing link when their turn comes, reminded, and sent the completed copy like anybody else. delegate_embedded is false, and there is nothing for you to do but close the iframe. On a test envelope the address has to be one that may receive test documents, exactly as at send; the signer is told so if it is not. Because the delegate is invited in the envelope sender’s name, a delegation is refused while the member recorded as having sent the envelope is no longer in your organisation, exactly as for an emailed signer. ⚠️ This changed on 2026-10-18, for envelopes already sent too. Before then the delegate of an embedded signer stayed embedded and was never emailed. A recipient created before the change cannot be given delegates_stay_embedded, so its delegate is emailed. With delegates_stay_embedded: true, the delegate stays embedded. Nobody emails them, delegate_embedded is true, and they sign only once you seat them: mint their URL with POST /api/v1/envelopes/{envelopeId}/recipients/{recipientId}/signing-url, passing delegate_recipient_id, exactly as for any embedded recipient. The new recipient carries the setting on, so a delegate of the delegate stays embedded too. Use it only if your application can authenticate somebody it has never seen; if it cannot, leave it off and let them be emailed. Either way the new recipient starts with external_ref set to null, and no endpoint sets one: your key named the person who delegated. Keep your own mapping from delegate_recipient_id to whoever you seat, and match them by id. An emailed delegate is asked to prove what an emailed recipient of that role is asked: where the template role asks for an emailed code, they get one, even though the embedded signer before them (whom your application authenticated) did not. A delegate who stays embedded keeps the slot’s verification_method. The certificate of completion records the handover and its reason, and the delegate’s entry says how they were reached: an emailed link, unless they stayed embedded.

Asking an embedded signer for a code

An embedded recipient is asked for nothing by default: your application has already signed them in. You can still ask for one more check, per recipient, by creating them with "verification_method": "mobile_code" and their mobile. When the iframe opens, they see the code screen first, are sent a code on their phone (on WhatsApp, or by SMS when WhatsApp cannot reach them), and enter it before the document appears. An email code is refused for an embedded recipient, because Vumasign never emails one. A mobile-code slot’s delegate who stays embedded is sent a code too, at the number the delegating signer gives for them. See signer verification for the limits, the pause and what the certificate says.

An identity check

You can also create an embedded recipient with "verification_method": "identity_check" and their mobile. After the mobile code, the iframe shows a QR code and Send the link to my phone, and waits. The signer photographs their ID or passport and takes a selfie on their phone, in its own browser, never inside your iframe; when they finish, the iframe carries on to the document by itself. This happens even when the iframe is already on a phone: they open the link sent to the number they just confirmed, then come back to your application. So your iframe needs no camera permission and no popups: do not add allow="camera" for this. What it does need is a signer who has their phone with them, and time to finish the whole check, the phone part included, inside the embedded session. That session lasts at most 1 hour from the moment the URL is redeemed (or less, near the envelope’s deadline), and the phone part cannot outlast it. If it runs out, mint a new URL: the signer enters a new mobile code, but an identity check they already passed is not asked for again, and a signer is charged for an identity check at most once per envelope, however many URLs you mint for them. See what it costs. Nothing about the identity check is sent by postMessage; the result is on the envelope read and on the recipient.identity_verified and recipient.identity_check_failed webhooks. See signer verification for the price, plans and what the certificate says.

What we deliberately did not build

  • return_url. It is a browser redirect and would be mistaken for the truth. The postMessage envelope does the job a return URL was being asked to do — moving your interface — without navigating anywhere.
  • A “read my minted URLs” endpoint. A credential readable twice is one stored somewhere readable. What is readable after the fact is the audit chain, which records that a URL was minted, by which key, for whom and until when — and never the URL.
  • http://localhost as a registrable origin. A permanently open plaintext origin in production is a hole nobody remembers to close. Terminate TLS locally, or use a tunnel.
  • Embedded sending and embedded template authoring. One embedded surface, one message envelope, and the envelope is defined so the second one cannot disagree with it.