Guide

Embedded signing

Let people sign inside your own website or app.

How it works

Send the document as usual (with the API or the app). Then, when the signer is on your site, ask for a signing session for them. You get a one-time URL; show it in a frame on your page, or send the browser to it.

You have already identified the signer in your own system, so they skip the email code. The evidence records that they were verified by your application (embedded:api). They still receive the normal email invitation, so they can finish from email if they leave your page.

bash

# 1. Allow your site to frame the signing page (once). Also possible in Settings, Developers.
curl -X PATCH "https://api.esorasign.com/v1/workspaces/$WORKSPACE_ID" \
  -H "Authorization: Bearer $ESORA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "embed_origins": ["https://portal.example.com"] }'

# 2. Each time the signer opens your page, make a fresh session for them (the document must be sent).
curl -X POST "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F/recipients/rcp_5ZR3qa7yEeeby3abP3E2Zs/signing-sessions" \
  -H "Authorization: Bearer $ESORA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "return_url": "https://portal.example.com/deals/D-10442/signed" }'

json

{
  "object": "signing_session",
  "recipient_id": "rcp_5ZR3qa7yEeeby3abP3E2Zs",
  "url": "https://sign.esorasign.com/embed/7Hk2…",
  "expires_at": "2026-11-02T14:12:00.000Z",
  "note": "Open within 5 minutes. The URL works once. Add your site to the workspace embed_origins to show it in a frame."
}

Show it on your page

The URL works once and must be opened within 5 minutes; make a new session each time the page loads. Only the sites in your workspace’s embed origins can show the signing page in a frame; any other site gets a blank frame. Origins are HTTPS (http://localhost is allowed for development).

html

<!-- signingUrl comes from your server (step 2). It works once, within 5 minutes. -->
<iframe id="esora" src="{{ signingUrl }}" style="width:100%;height:860px;border:0" allow="clipboard-write"></iframe>
<script>
  window.addEventListener('message', (e) => {
    if (e.origin !== 'https://sign.esorasign.com') return;
    if (e.data && e.data.type === 'esora.signing_complete') {
      // e.data.documentStatus is "sent" (others still to sign) or "finalizing"/"completed".
      // Wait for the document.completed webhook before treating the record as final.
    }
  });
</script>

When the person signs, the page posts a message of type esora.signing_complete to your page and then, if you set return_url, goes to it with ?event=signing_complete added. return_url must be HTTPS, or http://localhost while you develop.