# 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.

## Prerequisites

- 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


## Before you start

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`.

## 1. Create a draft envelope

Send a request to [POST /envelopes](/openapi/envelopes/sendenvelope):

```curl
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**

```json
{
  "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**

```json
{
    "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.

## 2. Create an embed session

When the draft is ready, send a request to [POST /embed-sessions](/openapi/embed-sessions/createembedsession) to create an embed session from your server:

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

**Example create embed sessions body**

The envelope must still be a draft.

```json
{
  "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:

```json
{
  "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.

## 3. Display the document setup page

Set the returned `session_url` as the source of an iframe:

```html
<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.

## 4. Continue the sending journey

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.

## 5. Send the draft envelope

After the user confirms the details, send a request to [POST /envelopes/{envelope_fingerprint}/send](/openapi/envelopes/senddraftenvelope) from your server:

```http
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.

## Party management

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.

## Error handling

Handle these cases in your integration:

| Scenario | Expected response | What to do |
|  --- | --- | --- |
| The embed URL session token expires (2min) before loading | The embedded page cannot authenticate | Create a new embed session and update the iframe source. |
| The embed URL session itself expires (60min) | The embedded page displays error state | Pre-empt this with a session refresh close to expiry |


## Security checklist

- 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.


## Related documentation

- [Embedded sending](/guides/embedded-sending/embedded-sending) – Understand the feature and division of responsibilities
- [Webhooks](/webhooks) – Track the envelope after it is sent