Embed document setup in your application

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.

• A Signable API key
• A server-side application that can keep the API key secure
• A user authenticated UI to embed the document setup page into
• At least one document and details for at least one signing party

Keep all Signable API requests on your server. Your browser should request an embed session from your server and receive only the short-lived session_url.

Send a request to POST /envelopes:

POST https://api.signable.co.uk/v1/envelopes

Where is_draft property is set to true.

Note:

• You can use either document upload or templates to create a draft envelope.
• Creating a draft does not notify its parties.

Example send draft envelope body

{
  "envelope_title": "Test Draft Doc",
  "is_draft": true,
  "envelope_parties": [
    {
      "party_name": "Alex Mitchell",
      "party_email": "alexm@signable.com",
      "party_role": "signer1"
    }
  ],
  "envelope_documents": [
    {
        "document_url": "https://example-doc.pdf",
        "document_title": "Test Agreement"
    }
  ]
}

Example successful response

{
    "http": 202,
    "message": "Your envelope with title Test Draft Doc will be processed and saved as a draft.",
    "envelope_title": "Test Draft Doc",
    "envelope_fingerprint": "584ea8b41b0d4c17a96b967433b211e6",
    "is_draft": true,
    ...
}

Store the envelope_fingerprint; you need it to create the embed session and send the envelope.

When the draft is ready, send a request to POST /embed-sessions to create an embed session from your server:

POST https://api.signable.co.uk/v1/embed-sessions

Example create embed sessions body

The envelope must still be a draft.

{
  "type": "envelope",
  "fingerprint": "584ea8b41b0d4c17a96b967433b211e6",
  "config": {
    "components": [
      {
        "type": "document_setup",
        "version": "1"
      }
    ]
  }
}

Example successful response

A successful request returns 201 Created with a short-lived session URL:

{
  "http": 201,
  "uuid": "86fc0eac-ba4b-49fd-b6b2-98b64e51063c",
  "session_url": "http://embed.signable.app/auth?session_token=9fec3d8c5fd2185e1f3d9ce7a64db570cc9a2e28",
  "expires_at": 1765208503
}

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.

Set the returned session_url as the source of an iframe:

<iframe
  src="https://embed.signable.app/auth?session_token=9fec3d8c5fd2185e1f3d9ce7a64db570cc9a2e28"
  title="Set up document fields"
  width="100%"
  height="760"
  frameborder="0"
></iframe>

Load the URL within the expires_at period. If it expires before the page loads, request a new embed session for the same draft and replace the iframe source.

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.

The embedded page saves field changes to the draft. Your application must provide the controls around it, including navigation, review, and confirmation.

Before sending, you may wish to show the envelope details that are managed outside the iframe, such as:

• Envelope title
• Parties and signing order
• Party messages, passwords, and mobile numbers
• OTP, reminder, and expiry settings
• Your own application data associated with the envelope

There is no browser event to tell your application that document setup is complete. Provide a clear Continue or Review and send control outside the iframe, then let the send endpoint perform final validation.

After the user confirms the details, send a request to POST /envelopes/{envelope_fingerprint}/send from your server:

POST https://api.signable.co.uk/v1/envelopes/584ea8b41b0d4c17a96b967433b211e6/send

Only an envelope with envelope_status set to draft can be sent by this endpoint. On success, Signable changes the envelope status to sent and sends the normal recipient notifications.

If validation fails, the API returns 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.

The embedded document setup page does not support adding, updating, or removing parties. Create all required parties before creating the embed session.

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.

Handle these cases in your integration:

• Make every Signable API request from your server.
• Return session URLs only over HTTPS.
• Keep session URLs out of logs, analytics, browser history, and support screenshots.
• Create a fresh session when a user reopens document setup.

• Embedded sending – Understand the feature and division of responsibilities
• Webhooks – Track the envelope after it is sent