Editor sessions
Let your users prepare a draft envelope or a template in the eSignStack editor, inside your app or on a hosted page, without an eSignStack account.
Your server creates an editor session and gets back a single-use URL. You load it in an iframe (embedded) or send the browser to it (hosted). The person can only do what the session allows.
Create a session
POST /api/v1/editor_sessions
Authorization: Bearer rk_live_…
Content-Type: application/json
Idempotency-Key: order-456-edit-1
{
"target": "env_01J…",
"mode": "embedded",
"parent_origin": "https://app.example.com",
"capabilities": { "edit_documents": true, "edit_recipients": true, "edit_fields": true, "send": false },
"actor": { "name": "Jane Doe", "email": "jane@example.com", "external_id": "user_123" }
}| Field | Notes |
|---|---|
target |
A draft envelope (env_…) or a template (tpl_…). A test key opens the sandbox's envelopes and templates, and a live key the live ones. A sent envelope returns 409; use corrections instead. A new one must be prepared first (preparation_status: "ready"); until then it returns 409 envelope_preparing or template_preparing. |
new_template |
Instead of target: start a new template. See Start a new template. |
mode |
embedded or hosted |
parent_origin |
Required for embedded. Must be an origin in Settings → Embedding. |
return_url |
Required for hosted. Must be an HTTPS URL on an allowed return origin. |
capabilities |
At least one of edit_documents, edit_recipients, edit_fields and send. |
actor |
Who your app says is editing: the same actor as on envelope create and send (name required, email, external_id). Recorded with every change in the history. |
Capabilities can't go beyond the key. Editing an envelope needs envelopes:write, editing a template needs templates:write, and send needs envelopes:send. Templates can't be sent. The server checks the capability and the key's ability on every change, so removing an ability from the key stops those changes in open sessions.
The response includes id (ses_…), url and expires_at. Open the URL within 10 minutes. After that the session lasts 60 minutes without activity and 8 hours at most. It also ends if the key that created it expires or is revoked.
Saving
The editor saves as the person works, as it does for your own team. Done saves anything still waiting and ends the session with saved. If something can't be saved yet, such as a field with nobody to fill it, the editor says so and stays open. Cancel ends the session with cancelled. Changes already saved are kept.
A link that can no longer be used shows a short note instead of the editor: the session ended or expired, or the entry link was already opened. The note asks the person to open the editor again from your app.
Edit a template
Templates have three steps: Documents (add files, reorder, rotate and remove pages, and choose whether a fillable PDF keeps its fields), Roles (names such as "Next of kin"; no email needed) and Fields. A Sender pre-fill field is filled in before sending, by whoever creates an envelope from the template, for example through POST /templates/{id}/envelopes with values. Templates have no Send step, and their share link and kiosk settings aren't shown.
Start a new template
Send new_template instead of target:
{
"new_template": { "name": "Cremation Authorization", "metadata": { "form": "cremation-v2" } },
"mode": "hosted",
"return_url": "https://app.example.com/after-edit",
"capabilities": { "edit_documents": true, "edit_recipients": true, "edit_fields": true }
}The person starts on an empty Documents step. Their first file creates the template with your name and metadata. The session then edits that template. Until then, target is null in the response, and no template exists.
edit_documentsis required, so the person can add the first file.- The key needs
templates:write, and the workspace plan must include templates. - As with
POST /templates, the template belongs to the workspace. In a workspace with no members it has no creator. - If the person leaves before adding a file, nothing is created and the hand-back has no
target.
Embedded sessions
Put the URL in an iframe. The page can only be framed by parent_origin. The editor posts messages to that origin, with the name in a type key:
type |
When |
|---|---|
esignstack:editor.ready |
The editor loaded |
esignstack:editor.saved |
The person saved and finished |
esignstack:editor.sent |
The person sent the envelope |
esignstack:editor.cancelled |
The person left without saving |
esignstack:resize |
The content height changed (height) |
Each message also has session. editor.saved and editor.cancelled also have target: the envelope or template ID, or null when a session that starts a template ended before its first file.
Hosted sessions
When the person finishes, the browser goes to:
https://app.example.com/after-edit?session=ses_…&status=saved&target=env_…status is saved, sent or cancelled. target is left out when a session that starts a template ended before its first file.
Confirm what happened
Messages and redirects only update your interface. Check the result before acting on it: GET /api/v1/envelopes/{id} or the envelope.sent webhook for envelopes, and GET /api/v1/templates/{id}?expand[]=roles&expand[]=fields or the template.created and template.updated webhooks for templates.