{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Embed document setup in your application","siteUrl":"https://developers.signable.app","description":"Integrate Signable’s eSignature API to send, sign, and manage documents with envelopes and webhooks.","image":"/assets/hero-placeholder-small.5b052639e5d5a3b6265375db1ac2835173dda2c0ed22f8c167f6284080cc84ce.db81178d.png","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"embed-document-setup-in-your-application","__idx":0},"children":["Embed document setup in your application"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a draft envelope, let a user place and position fields in an embedded document setup page, and then send the envelope from your application."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A Signable API key"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A server-side application that can keep the API key secure"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A user authenticated UI to embed the document setup page into"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["At least one document and details for at least one signing party"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-start","__idx":2},"children":["Before you start"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep all Signable API requests on your server. Your browser should request an embed session from your server and receive only the short-lived ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session_url"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"1-create-a-draft-envelope","__idx":3},"children":["1. Create a draft envelope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send a request to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/envelopes/sendenvelope"},"children":["POST /envelopes"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"curl","header":{"controls":{"copy":{}}},"source":"POST https://api.signable.co.uk/v1/envelopes\n","lang":"curl"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Where ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_draft"]}," property is set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You can use either document upload or templates to create a draft envelope."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Creating a draft does not notify its parties."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example send draft envelope body"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"envelope_title\": \"Test Draft Doc\",\n \"is_draft\": true,\n \"envelope_parties\": [\n {\n \"party_name\": \"Alex Mitchell\",\n \"party_email\": \"alexm@signable.com\",\n \"party_role\": \"signer1\"\n }\n ],\n \"envelope_documents\": [\n {\n \"document_url\": \"https://example-doc.pdf\",\n \"document_title\": \"Test Agreement\"\n }\n ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example successful response"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"http\": 202,\n \"message\": \"Your envelope with title Test Draft Doc will be processed and saved as a draft.\",\n \"envelope_title\": \"Test Draft Doc\",\n \"envelope_fingerprint\": \"584ea8b41b0d4c17a96b967433b211e6\",\n \"is_draft\": true,\n ...\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Store the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["envelope_fingerprint"]},"; you need it to create the embed session and send the envelope."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"2-create-an-embed-session","__idx":4},"children":["2. Create an embed session"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the draft is ready, send a request to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/embed-sessions/createembedsession"},"children":["POST /embed-sessions"]}," to create an embed session from your server:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"curl","header":{"controls":{"copy":{}}},"source":"POST https://api.signable.co.uk/v1/embed-sessions\n","lang":"curl"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example create embed sessions body"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The envelope must still be a draft."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"type\": \"envelope\",\n \"fingerprint\": \"584ea8b41b0d4c17a96b967433b211e6\",\n \"config\": {\n \"components\": [\n {\n \"type\": \"document_setup\",\n \"version\": \"1\"\n }\n ]\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example successful response"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful request returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}," with a short-lived session URL:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"http\": 201,\n \"uuid\": \"86fc0eac-ba4b-49fd-b6b2-98b64e51063c\",\n \"session_url\": \"http://embed.signable.app/auth?session_token=9fec3d8c5fd2185e1f3d9ce7a64db570cc9a2e28\",\n \"expires_at\": 1765208503\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The URL contains a sensitive session credential. Do not log, store, email, or reuse it. Return it only to the authenticated user who is preparing this envelope."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"3-display-the-document-setup-page","__idx":5},"children":["3. Display the document setup page"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session_url"]}," as the source of an iframe:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Load the URL within the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_at"]}," period. If it expires before the page loads, request a new embed session for the same draft and replace the iframe source."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Give the iframe enough space for document editing on the devices your application supports. Test the integration at each responsive breakpoint used by your application."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"4-continue-the-sending-journey","__idx":6},"children":["4. Continue the sending journey"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The embedded page saves field changes to the draft. Your application must provide the controls around it, including navigation, review, and confirmation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before sending, you may wish to show the envelope details that are managed outside the iframe, such as:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Envelope title"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Parties and signing order"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Party messages, passwords, and mobile numbers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["OTP, reminder, and expiry settings"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your own application data associated with the envelope"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is no browser event to tell your application that document setup is complete. Provide a clear ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Continue"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Review and send"]}," control outside the iframe, then let the send endpoint perform final validation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"5-send-the-draft-envelope","__idx":7},"children":["5. Send the draft envelope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After the user confirms the details, send a request to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/envelopes/senddraftenvelope"},"children":["POST /envelopes/{envelope_fingerprint}/send"]}," from your server:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST https://api.signable.co.uk/v1/envelopes/584ea8b41b0d4c17a96b967433b211e6/send\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Only an envelope with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["envelope_status"]}," set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["draft"]}," can be sent by this endpoint. On success, Signable changes the envelope status to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sent"]}," and sends the normal recipient notifications."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If validation fails, the API returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 Bad Request"]}," and leaves the envelope in draft. Keep the user's work available, explain what needs attention, and let them return to document setup or your surrounding form."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"party-management","__idx":8},"children":["Party management"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The embedded document setup page ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["does not support adding, updating, or removing parties"]},". Create all required parties before creating the embed session."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the end user needs to change the parties while on the document setup page, they must leave the current session. Provide a way for them to make the changes, create a new draft envelope, and restart the document setup flow with a new embed session."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":9},"children":["Error handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Handle these cases in your integration:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Scenario"},"children":["Scenario"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Expected response"},"children":["Expected response"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What to do"},"children":["What to do"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The embed URL session token expires (2min) before loading"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The embedded page cannot authenticate"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create a new embed session and update the iframe source."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The embed URL session itself expires (60min)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The embedded page displays error state"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pre-empt this with a session refresh close to expiry"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"security-checklist","__idx":10},"children":["Security checklist"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Make every Signable API request from your server."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Return session URLs only over HTTPS."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keep session URLs out of logs, analytics, browser history, and support screenshots."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a fresh session when a user reopens document setup."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-documentation","__idx":11},"children":["Related documentation"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/embedded-sending/embedded-sending"},"children":["Embedded sending"]}," – Understand the feature and division of responsibilities"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/webhooks"},"children":["Webhooks"]}," – Track the envelope after it is sent"]}]}]},"headings":[{"value":"Embed document setup in your application","id":"embed-document-setup-in-your-application","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Before you start","id":"before-you-start","depth":2},{"value":"1. Create a draft envelope","id":"1-create-a-draft-envelope","depth":2},{"value":"2. Create an embed session","id":"2-create-an-embed-session","depth":2},{"value":"3. Display the document setup page","id":"3-display-the-document-setup-page","depth":2},{"value":"4. Continue the sending journey","id":"4-continue-the-sending-journey","depth":2},{"value":"5. Send the draft envelope","id":"5-send-the-draft-envelope","depth":2},{"value":"Party management","id":"party-management","depth":2},{"value":"Error handling","id":"error-handling","depth":2},{"value":"Security checklist","id":"security-checklist","depth":2},{"value":"Related documentation","id":"related-documentation","depth":2}],"frontmatter":{"title":"Embed document setup in your application","description":"Create a draft envelope, display document setup in an iframe, and send the completed envelope","category":"Guide","keywords":["embedded sending","document setup","iframe","draft envelope","embed session","API"],"seo":{"title":"Embed document setup in your application"}},"lastModified":"2026-09-02T13:49:41.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/embedded-sending/embed-document-setup","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}