SnowSign Public API Guide
Contents
Authentication and conventions
| Property | Value |
|---|---|
| Base URL | https://api-snowsign.jtsnowball.com/public |
| Protocol | HTTPS |
| Response | JSON, UTF-8 |
| Authentication | X-API-Key: YOUR_API_KEY |
Create a key in Organization settings → API keys → New API key. Keys are active immediately and shown only once. Store them securely on your server; never expose them in browser code or SDKs.
API keys represent the organization, not the issuer's personal permissions. API-created contracts, templates, and signing links belong to the all-work scope. Template listing and usage include only templates available to all members. If approval is required, sending returns an error rather than automatically requesting approval. Company seals cannot be added directly through the Public API; prepare a template containing them in SnowSign.
Success responses include "success": true. Responses that return resource data also include data; reminder responses include message and omit data. Paginated lists also return meta.pagination with page, per_page, total_items, and total_pages. Unless noted, pagination defaults to page 1 and 20 items, with a maximum of 100 per page.
Method names, paths, field names, status codes, and event identifiers are language-independent. Use error codes for application logic, not diagnostic message wording. Ordinary resource APIs do not accept a UI-language parameter. Stored names, titles, variable keys, and user-entered text retain their original language. Participant locale controls email and signing UI language (ko, en, or ja), not document translation.
Hosted Embed
POST /v1/embed-sessions creates a short-lived iframe session for PDF, template, bulk, or AI creation. Your server authenticates with the API key and passes only the returned iframe_url to the browser.
{
"purpose": "contract_create",
"allowed_origins": ["https://erp.example.com"],
"flows": ["template_bulk"],
"external_system": "customer-erp",
"external_id": "ERP-2026-00123"
}The response contains session_id, iframe_url, and code_expires_at. external_system + external_id, or otherwise reference_id, prevents duplicate sessions for the same operation. Use distinct identifiers for separate users/orders/attempts.
Supported flows: pdf_draft, pdf_send, template_draft, template_send, template_bulk, ai_draft, ai_send, or ["all"] on its own. Results arrive through snowsign.embed.* messages. See the Hosted Embed developer guide for origin validation, event handling, and complete examples.
Contracts
Endpoints
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /v1/contracts | List contracts |
| GET | /v1/contracts/{contract_id} | Contract details |
| GET | /v1/contracts/{contract_id}/status | Status summary |
| POST | /v1/templates/{template_id}/create-contract | Create from a template |
| POST | /v1/contracts | Create from an uploaded PDF |
| POST | /v1/contracts/{contract_id}/send | Send or schedule |
| POST | /v1/contracts/{contract_id}/cancel | Cancel |
| POST | /v1/contracts/{contract_id}/remind | Send reminders |
| GET | /v1/contracts/{contract_id}/download | Completed PDF download URL |
| GET | /v1/contracts/{contract_id}/attachments | Submitted attachment metadata and URLs |
| GET | /v1/contracts/{contract_id}/audit-certificate | Audit certificate PDF URL |
| POST | /v1/contracts/bulk-download | Multiple completed PDF URLs |
| POST | /v1/contracts/bulk-audit-certificates | Multiple audit certificate URLs |
List, detail, and status
The list accepts page, per_page, and optional status: draft, scheduled, pending, in_progress, completed, cancelled, or expired. Link-signing contracts are retrieved through the link's contracts endpoint instead of this list. Contracts archived in the web app still appear as usual; contracts moved to the trash leave the list, and their detail returns 404.
| Response field | Included in | Meaning |
|---|---|---|
contract_id, status | Contract resources | Identity and state |
title | Create, list, detail, link-signing contracts | The contract name participants see. Does not change after sending |
internal_title | List, detail, link-signing contracts | The organization's own name set after sending. Participants never see it; null if not renamed |
revision | List, detail, status | { number, state }. number is the version participants see (the first send is 1). state is requested (a participant asked for changes) or null. Signing is paused while it is requested or a revision awaits approval (approval_status=pending). Read-only; revisions are handled in the web app |
responsible_permission_group | List, detail | { uuid, name, path } |
approval_status | Create, list, detail, status | Latest approval state or null |
dispatch_mode | Create, send, list, detail, status | platform or external |
scheduled_send_at | Create, send, list, detail, status | Scheduled time or null |
schedule_failure_code | Create, send, list, detail, status | Scheduling failure or null |
email_issue, email_issue_count | List, detail, status | Unresolved email delivery issues |
link_signing | Detail, status | { id, name } for link-generated contracts |
participants[].attachment_requirements | Detail | Requests and submission state; file metadata after completion |
participants[].delivery_channels | Detail | Platform delivery channels, or null for external delivery |
participants[].email_delivery | Detail | Delivery status, attempts, timestamps, failure reason, unresolved issue |
participants[].alimtalk_delivery | Detail | Latest { outcome, purpose, attempted_at, failure_reason }, or null. outcome is accepted, failed, unknown, or skipped (a reminder not sent because signing was paused) |
Scheduling failure codes: approval_required, subscription_required, payment_past_due, quota_exceeded, authorization_failed, resource_invalid, system_error.
Email delivery failure reasons exclude raw SMTP responses and recipient addresses. email_delivery contains status, attempted_at, event_at, failure_reason, attempt_count, and unresolved_issue; the latter contains the unresolved status, event time, and reason when present. Public API failure text retains its existing behavior, including the provider result in alimtalk_delivery.failure_reason.
Detail also includes description, signing_order, participants with signing/security state, variables, integrity_hash, created_at, sent_at, completed_at, cancelled_at, cancelled_reason, and expires_at. The status response includes participants_status: { total, signed, pending }.
Participant fields
| Field | Required | Meaning |
|---|---|---|
role | Conditional | Role shorthand when not explicitly supplying key and role_name |
key | Conditional | Stable participant identifier; connects to PDF participant_key |
role_name | Conditional | Role name; usually role is sufficient |
name | Yes | Participant name |
email | Conditional | Required for email delivery, or external delivery without a phone |
phone | Conditional | Korean 010 mobile number for Alimtalk/identity verification, or external delivery without email |
delivery_channels | No | One or both of email, alimtalk; omit for external delivery |
security | No | { "method": "password", "value": "..." } or { "method": "identity_verification" }; omission uses link contact verification |
locale | No | ko, en, or ja for email and signing UI |
attachment_requirements | No | Up to five requested files |
Each attachment request accepts one PDF, JPG/JPEG, or PNG file from the signer:
{ "title": "Identification", "description": "Mask sensitive identification numbers.", "is_required": true }Requests belong to PDF contract participants[] or template signers[]. Template-created contracts inherit role defaults. For a single template contract, omission keeps the defaults, a new array replaces them, and [] removes the requests. Bulk and link signing apply template requests uniformly.
Create from a template
POST /v1/templates/{template_id}/create-contract
| Field | Type | Required | Meaning |
|---|---|---|---|
title | string | Yes | Contract title |
description | string | No | Description |
participants | array | Yes | Participants using the fields above |
dispatch_mode | string | No | Default platform; external returns links without sending messages |
variables | object | No | Text strings, numbers (JSON numbers or strings), ISO date/month strings, checkbox booleans, or address objects |
signing_order | string | No | Omit to use template defaults |
send_immediately | boolean | No | Default false for platform; omit or set true for external |
scheduled_send_at | string | No | ISO 8601 timestamp with timezone |
message | string | No | Message delivered to participants |
Participant roles must match the template's saved role names exactly. If channels are omitted, SnowSign uses the role's defaults that can be delivered to the supplied contacts. Omitted locale and attachment requests inherit the role settings. Password-protected roles require security.value.
Repeated variable names share one supplied value. Text values are strings; number values are JSON numbers or strings such as "1,234.5"; formula variables are calculated by SnowSign and rejected with 400 if supplied; checkbox values are booleans; address values are { "address_line1", "address_line2", "postal_code" } objects or a base-address string; dates use YYYY-MM-DD for date_precision=day or YYYY-MM for month. Do not translate saved variable keys or role names when switching your UI language.
{
"title": "Alex Kim Employment Agreement",
"send_immediately": true,
"participants": [
{ "name": "Alex Kim", "email": "alex@example.com", "role": "Employee", "locale": "en" }
],
"variables": { "Start date": "2026-10-01", "Consent": true, "Salary": "KRW 3,500,000" }
}These example role and variable names assume a matching template. A successful creation returns HTTP 201 with contract_id, title, status, approval/scheduling state, and sent_at when sent.
External delivery
Set dispatch_mode: "external" and provide at least one of email or phone. The contract is activated immediately on creation: omit send_immediately or set it to true. Draft creation and scheduled sending are not supported in this mode. SnowSign does not send participant messages. Each supplied contact yields a corresponding signing_urls.email or signing_urls.phone; both appear when both contacts are provided.
{
"participant_id": "participant-uuid",
"email": "alex@example.com",
"phone": "01012345678",
"security_method": "email",
"signing_urls": {
"email": "https://.../sign/token?verify=email",
"phone": "https://.../sign/token?verify=phone"
},
"expires_at": "2026-10-05T01:30:00"
}Send, schedule, cancel, remind
- Send:
POST /v1/contracts/{contract_id}/send, optionalmessage. Sending consumes monthly contract usage. - Schedule: Include
scheduled_send_atwith a future timestamp before the deadline. Explicit null cancels a schedule; omission sends immediately. External delivery does not support scheduled sending. - Cancel:
POST /v1/contracts/{contract_id}/cancel, optionalreason. Completed or canceled contracts return 400CONTRACT_STATUS_ERROR. - Remind:
POST /v1/contracts/{contract_id}/remind, optionalmessageandparticipant_uuidsto restrict recipients. Uses saved email/Alimtalk channels for participants awaiting signatures. Returns 409CONTRACT_SIGNING_PAUSEDwhile signing is paused (seerevision).
Downloads and attachments
Contract PDF, audit certificate, and attachment downloads require a completed contract. Download responses contain download_url, filename, and expires_at; temporary URLs last one hour. Template source downloads do not require contract completion.
The attachments response is an array of { participant_id, participant_name, requirements }. Each requirement contains uuid, title, description, is_required, has_file, and file. A submitted file contains upload_id, filename, content_type, size_bytes, uploaded_at, download_url, and expires_at. Missing submissions have has_file: false and file: null; no requests produce an empty array.
Both bulk-download endpoints accept { "contract_ids": ["uuid-1", "uuid-2"] }, up to 50 IDs. Results are per contract: { contract_id, download_url, filename, error }. A failed item has null URL/filename and an error; successful items remain usable.
PDF uploads and fields
Upload flow
- Your server calls
POST /v1/uploads. - Upload the PDF using the returned
upload_urlandfieldsunchanged. - Optionally call
POST /v1/uploads/{upload_id}/diagnosticsto show PDF warnings. - Create a contract or template using
document_upload_idand field coordinates. Creation always validates the uploaded PDF again.
Upload request:
{
"purpose": "contract_document",
"filename": "contract.pdf",
"content_type": "application/pdf",
"size_bytes": 1234567
}purpose is contract_document or template_document. Maximum file size is 50MB (52,428,800 bytes). The response includes upload_id, upload_url, fields, max_size_bytes, allowed_content_types, and expires_at. Sessions expire after 10 minutes.
Diagnostics returns upload_id and pdf: { upload_policy, page_count, render_profile, warnings, errors }. Example values are upload_policy: "allow" and render_profile: "fontFace".
Create a PDF contract
POST /v1/contracts requires title, document_upload_id, participants, and signature_fields. Optional fields include dispatch_mode, signing_order, send_immediately, scheduled_send_at, message, variables, and external integration metadata.
Do not combine send_immediately: true and a scheduled_send_at timestamp. For dispatch_mode: "platform" (the default), omitting both produces a draft. External delivery activates the contract immediately; omit send_immediately or set it to true. Scheduled sending is not supported for external delivery.
Coordinates use PDF.js getViewport({ scale: 1 }) pixels, measured from the top-left corner. Page numbers start at 1.
| Field | Meaning |
|---|---|
participant or participant_key | Role name or stable participant key; omit for variables |
type | signature, stamp, name, phone, text, date, checkbox, address, variable |
page_number | Required, 1-based page |
position_x, position_y, width, height | Required pixel geometry |
position_unit | Only pixel supported |
is_required | Defaults true; signature/stamp/name always true; variable false; phone/text/date/checkbox/address may be false |
font_size | Integer 1–72 for phone/text/date/address/variable text rendering |
text_align | left, center, right for name/phone/text/date/address and text/number/date/address variables; not stored for signatures/checkboxes |
placeholder_text | Text-entry hint; not stored for dates |
label | Up to 100 characters. The address name for address fields (see address_display_part); an internal identifier for other fields |
variable_name | Required for type: "variable" |
variable_value_type | text (default), number, checkbox, date, or address |
default_value | Default for text variables. For number variables, a default or a formula starting with = (={Supply}*0.1, {name} references with + - * / and parentheses) |
date_precision | day or month |
date_format_pattern | Display pattern, e.g. YYYY-MM-DD or YYYY/MM; stored patterns are not changed by UI language. Not used by number variables |
number_format | Number variable display format: decimals (0-6, default 0), thousands_separator (default true), rounding (half, up, down), korean_amount (only when decimals is 0), unit (up to 8 characters), unit_position (before, after). All optional |
address_display_part | Address part shown by an address field or variable: full (default, address and details), address_line1, address_line2, or postal_code. Address variables with the same name, and a participant's address fields with the same label (none means the participant's default address), share one value |
fill_background | White background behind date/variable content |
selection_group_key | Checkbox group key, at most 64 characters |
selection_group_mode | at_least, exactly, or at_most |
selection_group_count | Integer from 1 to group size |
A signer checkbox group must contain at least two ordinary checkboxes for the same participant. Supply the same mode/count on every member. Group constraints replace individual required flags (is_required=false). Ungrouped fields omit all three group fields or set all to null. PDF templates support the same fields and template contracts inherit them.
{
"title": "Service Agreement",
"document_upload_id": "upl_abc123",
"signing_order": "parallel",
"send_immediately": true,
"message": "Please review and sign.",
"participants": [
{ "role": "Contractor", "name": "Alex Kim", "email": "alex@example.com", "delivery_channels": ["email"], "locale": "en" }
],
"signature_fields": [
{ "participant": "Contractor", "type": "signature", "page_number": 2, "position_x": 410, "position_y": 710, "width": 120, "height": 50, "position_unit": "pixel", "is_required": true },
{ "type": "variable", "variable_name": "contract_amount", "variable_value_type": "text", "page_number": 1, "position_x": 180, "position_y": 240, "width": 120, "height": 18, "fill_background": true, "text_align": "right" }
],
"variables": { "contract_amount": "KRW 3,000,000" },
"integration": { "external_system": "customer-erp", "external_id": "ERP-2026-0001" }
}Templates
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /v1/templates | Create from an uploaded PDF |
| GET | /v1/templates | List, with optional page / per_page |
| GET | /v1/templates/{template_id} | Details, signer fields, variables |
| GET | /v1/templates/{template_id}/download | Original PDF URL, valid for one hour |
Create
Required fields: name, document_upload_id, signers, signature_fields. Optional fields: signing_order (parallel or sequential), deadline_days, and integration metadata. Templates are created in the all-work scope and available to all members.
Signer roles may be strings or objects such as { "role": "Employee", "locale": "en" }; locale defaults to ko. For repeated role names, specify distinct key values and role_name. Field geometry, required rules, alignment, date/variable metadata, and checkbox constraints follow the PDF contract rules above; use the role reference for template signer fields.
Templates also support separate sender checkbox-variable groups. Use type: "variable" with variable_value_type: "checkbox" and at least two distinct variable_name values; repeated placements of the same name count once. Do not mix variables and signer checkboxes in one group. These groups are evaluated using the supplied variable values, separately from the signer's completion requirements.
{
"name": "Standard Service Agreement",
"document_upload_id": "upl_template_abc",
"signing_order": "parallel",
"deadline_days": 14,
"signers": [{ "role": "Contractor", "locale": "en" }],
"signature_fields": [
{ "role": "Contractor", "type": "signature", "page_number": 2, "position_x": 410, "position_y": 710, "width": 120, "height": 50, "position_unit": "pixel", "is_required": true },
{ "role": "Contractor", "type": "date", "page_number": 1, "position_x": 180, "position_y": 240, "width": 120, "height": 24, "date_precision": "day", "date_format_pattern": "YYYY-MM-DD", "text_align": "center" }
],
"integration": { "external_system": "customer-erp", "external_id": "ERP-TEMPLATE-001" }
}HTTP 201 returns { "template_id": "uuid-string", "name": "Standard Service Agreement" } inside data.
Read
List/detail contain template_id, name, description, category, signing_order, deadline_days, can_create_link_signing, and signers. Details also contain signature_fields and variables.
| Field | Meaning |
|---|---|
signers[].role_name, signing_order | Saved role and order |
signers[].security_method | email, password, or easy_cert; absent means email |
signers[].delivery_channels, locale | Default delivery channels and email/signing language |
signers[].attachment_requirements | Default requested files |
signature_fields | Non-variable fields, including signer input fields and company seals (organization_seal) |
signature_fields[].is_required | Always true for signature/stamp/name; saved value otherwise |
variables | Deduplicated by variable name; includes name, label, default value, and type |
variables[].is_required | Always false |
variables[].value_type | text, number, checkbox, date, or address; dates include display metadata and numbers include number_format; formula variables are not listed |
text_align on fields/variables | left, center, right, or null when not applicable |
can_create_link_signing | True when the template has a PDF and exactly one signer role |
Download errors include TEMPLATE_NOT_FOUND and TEMPLATE_FILE_NOT_FOUND.
Link signing
Create
POST /v1/link-signings
| Field | Required | Meaning |
|---|---|---|
template_uuid | Yes | template_id from a template response |
name | Yes | Management name |
max_submissions | Yes | Submission limit, at least 1 |
description | No | Instructions for signers |
expires_at | No | UTC ISO 8601 timestamp |
require_identity_verification | No | Require mobile identity verification; default false |
variables | No | Template values shared by all contracts from this link |
{
"template_uuid": "template-uuid",
"name": "2026 Onboarding Consent",
"description": "Please review and sign.",
"max_submissions": 100,
"expires_at": "2026-12-31T14:59:59Z",
"require_identity_verification": false,
"variables": { "Company": "SnowSign" }
}The 201 response contains link_signing_id, name, description, status, template: { template_id, name }, responsible_permission_group: { uuid, name }, link_url, max_submissions, submission_count, expires_at, require_identity_verification, locale, created_at, and updated_at.
Read and manage
| Method | Endpoint | Behavior |
|---|---|---|
| GET | /v1/link-signings | Paginated list |
| GET | /v1/link-signings/{id} | Details including saved variables |
| PATCH | /v1/link-signings/{id} | Change only supplied settings |
| POST | /v1/link-signings/{id}/pause | active → paused |
| POST | /v1/link-signings/{id}/resume | paused → active |
| POST | /v1/link-signings/{id}/close | Close an active or paused link |
List query: page, per_page, status (active, paused, closed, expired), search (link/template name), and sort: created_at:desc (default), created_at:asc, expires_at:asc, submission_count:desc, name:asc.
PATCH supports optional name, description, max_submissions (not less than current submissions), expires_at, and require_identity_verification. It cannot change variables, template_uuid, or status. Pause/resume/close have no request body.
Completed contracts
GET /v1/link-signings/{link_signing_id}/contracts has no request body and returns only completed contracts generated by that link. Optional queries: page, per_page, search (title, internal title, or signer name/email/contact), and sort: completed_at:desc (default), created_at:desc, signer_name:asc.
Items include contract_id, title, internal_title, status: "completed", signer_name, signer_email, completed_at, and link_signing: { id, name }. Use contract_id with the contract detail, status, PDF, and audit-certificate endpoints. These contracts do not appear in the general contract list.
Errors and limits
{
"success": false,
"error": { "code": "ERROR_CODE", "message": "Diagnostic message" },
"meta": { "timestamp": "2025-01-06T10:00:00Z" }
}| HTTP | Meaning |
|---|---|
| 200 / 201 | Success / created |
| 400 | Invalid request |
| 401 | Authentication failure |
| 403 | Authorization or usage restriction |
| 404 | Resource not found |
| 409 | Conflicts with the current state, such as paused signing |
| 429 | Request/session limit exceeded |
| 500 | Server error |
| Code | Meaning |
|---|---|
API_KEY_REQUIRED / INVALID_API_KEY | Missing or invalid key |
VALIDATION_ERROR | Invalid request parameters |
QUOTA_EXCEEDED | Monthly usage limit reached |
UPLOAD_SESSION_NOT_FOUND | Upload session missing |
PDF_UPLOAD_REJECTED | Unsupported PDF |
CONTRACT_NOT_FOUND / TEMPLATE_NOT_FOUND / LINK_SIGNING_NOT_FOUND | Resource missing |
INVALID_LINK_SIGNING_STATUS | Unsupported list-status filter |
INVALID_PUBLIC_LINK_SIGNING_REQUEST | Invalid link-signing fields or values |
INVALID_CONTRACT_STATUS | Action unavailable in the current state |
CONTRACT_SIGNING_PAUSED | Signing is paused because a revision was requested or a revised version is awaiting approval |
INVALID_DISPATCH_MODE | Action unavailable for this delivery mode |
EXTERNAL_DISPATCH_SCHEDULE_NOT_ALLOWED | Scheduling requested for external delivery |
APPROVAL_REQUIRED | Approval must be completed in the internal application |
Each API key can have up to three active upload sessions with a combined declared size of 150MB. Upload sessions last 10 minutes; excess usage returns HTTP 429.
Examples
cURL
curl "https://api-snowsign.jtsnowball.com/public/v1/contracts" \
-H "X-API-Key: YOUR_API_KEY"
curl -X POST "https://api-snowsign.jtsnowball.com/public/v1/uploads" \
-H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"purpose":"contract_document","filename":"contract.pdf","content_type":"application/pdf","size_bytes":1234567}'
curl -X POST "https://api-snowsign.jtsnowball.com/public/v1/contracts/CONTRACT_ID/send" \
-H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"message":"Please review and sign."}'Python
import os
import requests
base_url = 'https://api-snowsign.jtsnowball.com/public/v1'
headers = {'X-API-Key': os.environ['SNOWSIGN_API_KEY']}
response = requests.get(f'{base_url}/contracts', headers=headers, timeout=30)
response.raise_for_status()
contracts = response.json()['data']
contract_id = 'CONTRACT_ID'
response = requests.post(f'{base_url}/contracts/{contract_id}/send',
headers=headers, json={'message': 'Please review and sign.'}, timeout=30)
response.raise_for_status()JavaScript / Node.js
const baseUrl = 'https://api-snowsign.jtsnowball.com/public/v1';
const headers = { 'X-API-Key': process.env.SNOWSIGN_API_KEY, 'Content-Type': 'application/json' };
const response = await fetch(`${baseUrl}/contracts`, { headers });
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const { data: contracts } = await response.json();
const contractId = 'CONTRACT_ID';
const sent = await fetch(`${baseUrl}/contracts/${contractId}/send`, {
method: 'POST', headers, body: JSON.stringify({ message: 'Please review and sign.' }),
});
if (!sent.ok) throw new Error(`Sending failed: ${sent.status}`);Reference values
| Contract status | Meaning |
|---|---|
draft | Not sent |
scheduled | Waiting for scheduled sending |
pending | Sent, awaiting signatures |
in_progress | Some participants have signed |
completed | All participants have signed |
cancelled / expired | Canceled / expired |
Participant statuses: pending (awaiting signature), viewed, signed, declined. A decline leaves the contract awaiting signatures; the participant returns to pending when the sender sends a revision.
Field types: signature, name, phone, text, date, checkbox, address, stamp, variable. Variables are filled by the API, not by signers.
Document version: 1.9 (2026-09-04).