Skip to main content

Embedded Signing

Embedded signing lets your product create a contract through the public API, fetch an embed URL for the signer, and render the SpotDraft signing flow inside an iframe or webview.

High-level flow​

  1. Collect business and signer data in your product.
  2. Create the contract through the public API.
  3. Request the embedded signing URL using the returned contract identifier.
  4. Render the URL in an iframe.
  5. Listen for postMessage events from the iframe to know whether signing succeeded, failed, or was declined.

Step 1: Create the contract​

Authenticate with a client-id and client-secret linked to the SpotDraft user who should receive notifications and appear as the business user for contracts created through this integration.

Map your form fields into the relevant contract creation request in the API reference. Handle 4xx validation errors the same way you would for any other REST integration.

Step 2: Generate the embed URL​

After contract creation, call the embedded signing endpoint documented in the API reference using the contract identifier and the counterparty details required by the endpoint.

Treat the returned URL like a capability:

  • serve it only to the intended signer session
  • keep it behind HTTPS
  • avoid logging it into client-visible analytics without redaction

Step 3: Render the iframe and handle completion​

Your host page should listen for postMessage events from the iframe and verify event.origin before trusting them.

EventMessage namePayload
Sign completedspotdraft.embedded.sign_successful{ contract_id }
Sign declinedspotdraft.embedded.sign_declined{ contract_id }
Sign or upstream API errorspotdraft.embedded.sign_error{ contract_id, error: { code, upstream_error } }
PDF generation errorspotdraft.embedded.sign_errorSame shape with a different code

Operational notes​

  • large agreements can take several seconds to prepare, so show a loader or skeleton until the iframe becomes interactive
  • keep the API calls and the embed URL in the same region for the tenant
  • mismatched regions usually surface as confusing 403 or 404 responses