⚠️ Read this first: nothing in a browser is a completion signal
ApostMessage 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 holdingbrands: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.
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: trueis an explicit mode, not an inference from some other field being non-null, and it comes back on every recipient this API describes.external_refis 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: trueis refused in two situations that would leave them unreachable: a role the template routes ascc(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 — thebrand_idyou 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
conditionalsubjects, such as a co-tenant,subjectson the request decides what the signer meets inside your iframe:trueorfalsesettles 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 subjecttrueorfalse. -
delegates_stay_embedded(optional, defaultfalse, only besideembedded: 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
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
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
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, andrecipient.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://localhostas 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.