curl --request POST \
--url https://app.vumasign.com/api/v1/envelopes/{envelopeId}/recipients/{recipientId}/signing-url \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"embed_origin": "https://hr.nttdata.example"
}
'import requests
url = "https://app.vumasign.com/api/v1/envelopes/{envelopeId}/recipients/{recipientId}/signing-url"
payload = { "embed_origin": "https://hr.nttdata.example" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({embed_origin: 'https://hr.nttdata.example'})
};
fetch('https://app.vumasign.com/api/v1/envelopes/{envelopeId}/recipients/{recipientId}/signing-url', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.vumasign.com/api/v1/envelopes/{envelopeId}/recipients/{recipientId}/signing-url"
payload := strings.NewReader("{\n \"embed_origin\": \"https://hr.nttdata.example\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"url": "https://app.vumasign.com/e/specimen-payload.specimen-signature",
"expires_at": "2026-09-02T10:15:00.000Z"
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}Mint a short-lived, single-use URL for an embedded signer.
THE ONE ENDPOINT IN THIS API THAT RETURNS A BEARER CREDENTIAL FOR A LEGAL ACT. Anyone holding the url can open the document as that signer. Do not log it, cache it, store it or put it in a support ticket — put it in an iframe src and nowhere else.
⚠️ 10 MINUTES, AND SINGLE USE. The first GET spends it. A second GET within the 10 minutes renders a page that posts signing_url_invalid to your host page and signs nothing. A URL — opened or not — or the session it began, loaded after its lifetime is up (which the envelope’s deadline can shorten), renders the same kind of page and posts signing_url_invalid with reason: "expired" and can_remint: true, for 1 hour after that expiry; later than that it is refused a frame and posts nothing. Mint it when the signer arrives, not when the envelope is created — Dropbox Sign’s own advice, and the reason a recipient id is durable while a URL is not.
⚠️ THE URL AND THE SESSION HAVE DIFFERENT LIVES. expires_at is when the URL stops being redeemable; a signer who redeems it just before then gets 1 hour from that moment to read and sign (or less, if the envelope’s deadline is sooner). Reload the iframe on this timer only if nobody ever opened it.
FOUR THINGS MUST BE TRUE, and each has its own code: the envelope is open for signing, the recipient was created with "embedded": true, they have not already acted, and it is their turn (a later step is held back until the one before it finishes — recipient_not_yet_turn is a 409 and the identical call succeeds once it has).
⚠️ A vsk_test_ key may mint only on a sandbox envelope — one a test key created — and is refused test_key_cannot_mint on any other.
Framing
The page is served with Content-Security-Policy: frame-ancestors naming the origins registered against the brand this envelope was sent under, and with no X-Frame-Options. Register those origins in Settings first; they must be bare — https://example.com, no trailing slash, no path, no wildcard — and an unregistered parent cannot frame the page at all. An expired URL or session we minted is framed for the same origins for 1 hour after it expires, so its refusal can reach you; it grants nothing, and after that it is refused. A URL we cannot verify — unreadable or altered — gets X-Frame-Options: DENY instead, and the ordinary emailed signing page keeps X-Frame-Options: DENY unconditionally.
Talking to your page
The iframe posts { action, ...payload } to each registered origin, never to *. Actions: ready, signed, declined, delegated, signing_url_invalid. signing_url_invalid carries can_remint — branch on that, not on reason, or a signer who finishes in another tab turns your retry into an infinite loop.
⚠️ delegated MEANS THEY HANDED IT TO SOMEBODY ELSE: this recipient is retired and a replacement holds their position, so take the iframe down — but the envelope is not finished. recipient.delegated follows on your webhook. By default the replacement is NOT embedded: we email them a signing link when their turn comes, and minting for them is refused. Only when the recipient was created with delegates_stay_embedded: true is the replacement embedded: then mint a URL for delegate_recipient_id when you want them to sign in your page.
⚠️ NEITHER A postMessage NOR A RETURN URL IS A COMPLETION SIGNAL, AND THERE IS NO return_url ON THIS ENDPOINT FOR EXACTLY THAT REASON. signed is a browser event: the signer can close the tab, lose connectivity, or have any script on your own page forge it. The webhook is authoritative. Use these messages to move your interface — close the modal, navigate onwards — and use recipient.completed and envelope.completed to decide that a document was signed, to release goods, or to bill anybody. This is the mistake every first integration makes, and it is the one that is expensive.
NO Idempotency-Key, unlike POST /api/v1/envelopes. A retry mints a second URL, which emails nobody and bills nothing — and the response IS the credential, so “I do not know which state I am in” is not reachable. ⚠️ Redeeming a second URL does revoke the session a first one began.
Saying where you will frame it
Send embed_origin — the origin of the page the iframe goes on — and the mint is refused embed_origin_not_registered when that origin is not registered against the envelope’s brand, before anything is minted or recorded. Without it, an unregistered parent gets a URL that works and a frame the browser refuses: a blank box for the signer, and no response anywhere to say why. Omitting it changes nothing.
curl --request POST \
--url https://app.vumasign.com/api/v1/envelopes/{envelopeId}/recipients/{recipientId}/signing-url \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"embed_origin": "https://hr.nttdata.example"
}
'import requests
url = "https://app.vumasign.com/api/v1/envelopes/{envelopeId}/recipients/{recipientId}/signing-url"
payload = { "embed_origin": "https://hr.nttdata.example" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({embed_origin: 'https://hr.nttdata.example'})
};
fetch('https://app.vumasign.com/api/v1/envelopes/{envelopeId}/recipients/{recipientId}/signing-url', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.vumasign.com/api/v1/envelopes/{envelopeId}/recipients/{recipientId}/signing-url"
payload := strings.NewReader("{\n \"embed_origin\": \"https://hr.nttdata.example\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"url": "https://app.vumasign.com/e/specimen-payload.specimen-signature",
"expires_at": "2026-09-02T10:15:00.000Z"
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}Authorizations
Authorization: Bearer vsk_live_…. Chosen over a bespoke X-API-KEY header because every client, proxy and log-redaction rule already knows this one. What a key may DO is its scopes — see x-scopes at the root of this document and x-required-scope on each operation. The scope list is not written here because OpenAPI reserves a requirement’s scope array for oauth2 and openIdConnect and requires it to be empty for an http scheme.
Path Parameters
Body
Optional: the origin you will frame the URL on. At most 4096 bytes; a larger body is refused with invalid_request.
The optional body.
The origin of the page you will put this URL’s iframe on — window.location.origin. When it is not registered against the envelope’s brand the mint is refused embed_origin_not_registered and nothing is minted, rather than handing you a URL the browser will refuse to frame. Omit it and nothing is checked. It changes nothing about which origins may frame the URL.
"https://app.customer.example"
Response
The URL and when it stops being redeemable. Not readable again from anywhere: only a digest is stored.
The minted URL.
Single use. The first GET spends it; a second, within the 10 minutes, renders a page that posts { action: "signing_url_invalid", reason: "used", can_remint: true } to your host page, and the remedy is to call this endpoint again. There is no endpoint that reads this value back — a credential readable twice is one stored somewhere readable, and we store only a digest.
ISO 8601, UTC. 10 minutes from minting, or the envelope’s own deadline if that is sooner. ⚠️ THIS IS THE LIFE OF THE URL, NOT OF THE SIGNING SESSION: a signer who opens it just before it expires gets a full session of 1 hour (or less, if the envelope’s deadline is sooner) from that moment. A host that reloads the iframe on this timer rather than only when the URL was never opened will interrupt somebody mid-signature.