SnowSign Hosted Embed Developer Guide
Contents
Overview
Hosted Embed provides SnowSign's contract creation UI inside an ERP, groupware, or back-office iframe. SnowSign handles PDF upload, AI document creation and rendering, field placement, participants, attachment requests, templates, and bulk sending.
Your integration has three responsibilities: create an Embed Session on your server, display its iframe_url in the browser, and handle result events. Keep the API key on your server, never in browser JavaScript, HTML, mobile apps, URLs, logs, or postMessage payloads.
Create an API key in Organization settings → API keys. Store it in a server environment variable or secret manager.
Create a session
POST https://api-snowsign.jtsnowball.com/public/v1/embed-sessions
X-API-Key: YOUR_API_KEY
Content-Type: application/json{
"purpose": "contract_create",
"allowed_origins": ["https://erp.example.com"],
"flows": ["template_bulk"],
"external_system": "customer-erp",
"external_id": "ERP-2026-00123",
"reference_id": "order-1004"
}| Field | Required | Meaning |
|---|---|---|
allowed_origins | Yes | Origins allowed to host the iframe |
flows | Yes | Permitted creation flows |
external_system | No | External system name |
external_id | No | External business or document ID |
reference_id | No | Reference for lookup and duplicate-session prevention |
Use origins, not page URLs: https://erp.example.com, https://admin.example.com:8443, or http://localhost:5173. Do not include wildcards, paths, queries, or fragments.
external_system together with external_id prevents duplicate sessions for the same request. Without that pair, reference_id serves this purpose. Use distinct user/contract/order identifiers when users share an API key. To allow a fresh session for each attempt, generate a new external_id and retain the business ID in reference_id.
{
"success": true,
"data": {
"session_id": "embed-session-uuid",
"iframe_url": "https://app.snowsign.jtsnowball.com/embed/contracts/new?...",
"code_expires_at": "2026-06-27T12:00:00Z"
}
}Pass only iframe_url to the browser. Do not parse its authentication parameters, share it, or store it long-term. Obtain a new session after expiration.
Node.js / Express example
Protect this endpoint using your application's authentication and authorization. Derive the allowed origin on the server; do not accept arbitrary origins from the browser.
import express from 'express';
const app = express();
app.use(express.json());
const baseUrl = 'https://api-snowsign.jtsnowball.com/public/v1';
app.post('/api/snowsign/embed-session', async (req, res, next) => {
try {
const response = await fetch(`${baseUrl}/embed-sessions`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': process.env.SNOWSIGN_API_KEY,
},
body: JSON.stringify({
purpose: 'contract_create',
allowed_origins: ['https://erp.example.com'],
flows: ['template_send'],
external_system: 'customer-erp',
external_id: req.body.externalId,
}),
});
const result = await response.json();
if (!response.ok || !result.success) {
return res.status(response.status).json({
message: result.error?.message || 'Unable to create an embed session.',
});
}
res.json({ iframe_url: result.data.iframe_url });
} catch (error) {
next(error);
}
});Display the iframe
<iframe
id="snowsign-embed"
title="SnowSign contract creation"
style="width: 100%; height: 720px; border: 0;"
allow="clipboard-write"
></iframe>async function openHostedEmbed(externalId) {
const response = await fetch('/api/snowsign/embed-session', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ externalId }),
});
if (!response.ok) throw new Error('Unable to open contract creation.');
const { iframe_url } = await response.json();
document.querySelector('#snowsign-embed').src = iframe_url;
}Allow at least 720px height. On mobile, use a full-screen modal or separate page. Provide retry outside the iframe if initialization fails.
The interface uses a single valid lang=ko or lang=en URL parameter first, then the saved language preference, then the browser's primary language (ko for Korean, otherwise en). This changes the UI, not stored contract content or participant delivery language.
Receive events
Register the listener before loading the iframe so that the initial ready event is not missed. Verify both the sender origin and the iframe window.
const iframe = document.querySelector('#snowsign-embed');
const appOrigin = 'https://app.snowsign.jtsnowball.com';
window.addEventListener('message', (event) => {
if (event.origin !== appOrigin || event.source !== iframe.contentWindow) return;
const message = event.data;
if (!message || message.source !== 'snowsign.embed') return;
switch (message.type) {
case 'snowsign.embed.ready':
console.log('SnowSign ready', message.payload);
break;
case 'snowsign.embed.contract_created':
case 'snowsign.embed.contract_sent':
case 'snowsign.embed.completed':
console.log('Creation completed', message.payload);
// Refresh the associated business record.
break;
case 'snowsign.embed.cancelled':
// Close the creation screen or return to the previous step.
break;
case 'snowsign.embed.error':
// Show payload.message; request a new session to retry initialization.
console.error('Embed failed', message.payload);
break;
}
});| Event | Meaning |
|---|---|
snowsign.embed.ready | Initialization completed |
snowsign.embed.contract_created | Contract draft created |
snowsign.embed.contract_sent | Contract sent |
snowsign.embed.bulk_sent | Bulk sending completed; also emits snowsign.embed.completed |
snowsign.embed.completed | Bulk operation completed |
snowsign.embed.cancelled | User canceled |
snowsign.embed.error | Initialization failure; payload contains message |
Example completion payload:
{
"source": "snowsign.embed",
"type": "snowsign.embed.contract_sent",
"payload": {
"contract_id": "contract-uuid",
"title": "Employment Agreement",
"status": "pending",
"sent_at": "2026-06-12T12:10:00Z"
}
}Errors during contract creation or sending are shown inside the iframe; they are not forwarded as snowsign.embed.error events. The initialization error payload contains message, without a separate error code.
Bulk completion may include processed counts and failures. Show failed rows in your UI; correct those rows and retry with a new session. Submitted attachments are not included in postMessage; retrieve them after all participants have signed and the contract is complete using GET /v1/contracts/{contract_id}/attachments.
Choose flows
| Flow | Capability |
|---|---|
pdf_draft / pdf_send | Upload a PDF and create a draft / send immediately |
template_draft / template_send | Create a template-based draft / send immediately |
template_bulk | Bulk-send template contracts |
ai_draft / ai_send | Create an AI document draft / send immediately |
all | All flows; pass only ["all"] |
Only templates available to all members appear. When approval is required, sending returns an error rather than submitting an approval request automatically.
PDF fields support checkbox groups for the same signer: select at least, exactly, or at most N options. Template flows inherit saved constraints.
PDF and AI flows allow participant attachment requests. Single-template creation starts with editable role defaults; bulk sending applies the template's requests to every row. Signers upload the files after the contract is sent.
Company seals cannot be added in the PDF or AI creation UI. Prepare a template containing the seal in SnowSign first.
Security and troubleshooting
| Situation | Action |
|---|---|
| Connection or session failure | Request a new session; verify API key validity and the exact parent origin |
| Duplicate session | Use the existing session for the same operation, or a new external_id for a new attempt |
| Origin error | Use only the origin, e.g. https://erp.example.com, not /contracts/1004 |
| No events | Verify the listener was registered before iframe loading and checks the correct origin/window |
| AI mode missing | Include ai_draft or ai_send |
| AI PDF created but contract creation fails | Check flows; wait for the asynchronous rendering job to complete |
| Send button missing | Include the corresponding pdf_send, template_send, or ai_send flow |
| Quota/subscription failure | Ask a SnowSign administrator to check usage, payment, and plan settings |
Billing, plan changes, and overage settings are not available inside the iframe. Use the SnowSign administration UI. Do not reuse an expired or failed session URL.