SnowSignSnowSign
Back
Quick integration

SnowSign Public API Guide

Contents

Authentication and conventions

PropertyValue
Base URLhttps://api-snowsign.jtsnowball.com/public
ProtocolHTTPS
ResponseJSON, UTF-8
AuthenticationX-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.

json
{
  "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

MethodEndpointPurpose
GET/v1/contractsList contracts
GET/v1/contracts/{contract_id}Contract details
GET/v1/contracts/{contract_id}/statusStatus summary
POST/v1/templates/{template_id}/create-contractCreate from a template
POST/v1/contractsCreate from an uploaded PDF
POST/v1/contracts/{contract_id}/sendSend or schedule
POST/v1/contracts/{contract_id}/cancelCancel
POST/v1/contracts/{contract_id}/remindSend reminders
GET/v1/contracts/{contract_id}/downloadCompleted PDF download URL
GET/v1/contracts/{contract_id}/attachmentsSubmitted attachment metadata and URLs
GET/v1/contracts/{contract_id}/audit-certificateAudit certificate PDF URL
POST/v1/contracts/bulk-downloadMultiple completed PDF URLs
POST/v1/contracts/bulk-audit-certificatesMultiple 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 fieldIncluded inMeaning
contract_id, statusContract resourcesIdentity and state
titleCreate, list, detail, link-signing contractsThe contract name participants see. Does not change after sending
internal_titleList, detail, link-signing contractsThe organization's own name set after sending. Participants never see it; null if not renamed
revisionList, 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_groupList, detail{ uuid, name, path }
approval_statusCreate, list, detail, statusLatest approval state or null
dispatch_modeCreate, send, list, detail, statusplatform or external
scheduled_send_atCreate, send, list, detail, statusScheduled time or null
schedule_failure_codeCreate, send, list, detail, statusScheduling failure or null
email_issue, email_issue_countList, detail, statusUnresolved email delivery issues
link_signingDetail, status{ id, name } for link-generated contracts
participants[].attachment_requirementsDetailRequests and submission state; file metadata after completion
participants[].delivery_channelsDetailPlatform delivery channels, or null for external delivery
participants[].email_deliveryDetailDelivery status, attempts, timestamps, failure reason, unresolved issue
participants[].alimtalk_deliveryDetailLatest { 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

FieldRequiredMeaning
roleConditionalRole shorthand when not explicitly supplying key and role_name
keyConditionalStable participant identifier; connects to PDF participant_key
role_nameConditionalRole name; usually role is sufficient
nameYesParticipant name
emailConditionalRequired for email delivery, or external delivery without a phone
phoneConditionalKorean 010 mobile number for Alimtalk/identity verification, or external delivery without email
delivery_channelsNoOne or both of email, alimtalk; omit for external delivery
securityNo{ "method": "password", "value": "..." } or { "method": "identity_verification" }; omission uses link contact verification
localeNoko, en, or ja for email and signing UI
attachment_requirementsNoUp to five requested files

Each attachment request accepts one PDF, JPG/JPEG, or PNG file from the signer:

json
{ "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

FieldTypeRequiredMeaning
titlestringYesContract title
descriptionstringNoDescription
participantsarrayYesParticipants using the fields above
dispatch_modestringNoDefault platform; external returns links without sending messages
variablesobjectNoText strings, numbers (JSON numbers or strings), ISO date/month strings, checkbox booleans, or address objects
signing_orderstringNoOmit to use template defaults
send_immediatelybooleanNoDefault false for platform; omit or set true for external
scheduled_send_atstringNoISO 8601 timestamp with timezone
messagestringNoMessage 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.

json
{
  "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.

json
{
  "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, optional message. Sending consumes monthly contract usage.
  • Schedule: Include scheduled_send_at with 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, optional reason. Completed or canceled contracts return 400 CONTRACT_STATUS_ERROR.
  • Remind: POST /v1/contracts/{contract_id}/remind, optional message and participant_uuids to restrict recipients. Uses saved email/Alimtalk channels for participants awaiting signatures. Returns 409 CONTRACT_SIGNING_PAUSED while signing is paused (see revision).

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

  1. Your server calls POST /v1/uploads.
  2. Upload the PDF using the returned upload_url and fields unchanged.
  3. Optionally call POST /v1/uploads/{upload_id}/diagnostics to show PDF warnings.
  4. Create a contract or template using document_upload_id and field coordinates. Creation always validates the uploaded PDF again.

Upload request:

json
{
  "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.

FieldMeaning
participant or participant_keyRole name or stable participant key; omit for variables
typesignature, stamp, name, phone, text, date, checkbox, address, variable
page_numberRequired, 1-based page
position_x, position_y, width, heightRequired pixel geometry
position_unitOnly pixel supported
is_requiredDefaults true; signature/stamp/name always true; variable false; phone/text/date/checkbox/address may be false
font_sizeInteger 1–72 for phone/text/date/address/variable text rendering
text_alignleft, center, right for name/phone/text/date/address and text/number/date/address variables; not stored for signatures/checkboxes
placeholder_textText-entry hint; not stored for dates
labelUp to 100 characters. The address name for address fields (see address_display_part); an internal identifier for other fields
variable_nameRequired for type: "variable"
variable_value_typetext (default), number, checkbox, date, or address
default_valueDefault for text variables. For number variables, a default or a formula starting with = (={Supply}*0.1, {name} references with + - * / and parentheses)
date_precisionday or month
date_format_patternDisplay pattern, e.g. YYYY-MM-DD or YYYY/MM; stored patterns are not changed by UI language. Not used by number variables
number_formatNumber 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_partAddress 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_backgroundWhite background behind date/variable content
selection_group_keyCheckbox group key, at most 64 characters
selection_group_modeat_least, exactly, or at_most
selection_group_countInteger 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.

json
{
  "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

MethodEndpointPurpose
POST/v1/templatesCreate from an uploaded PDF
GET/v1/templatesList, with optional page / per_page
GET/v1/templates/{template_id}Details, signer fields, variables
GET/v1/templates/{template_id}/downloadOriginal 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.

json
{
  "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.

FieldMeaning
signers[].role_name, signing_orderSaved role and order
signers[].security_methodemail, password, or easy_cert; absent means email
signers[].delivery_channels, localeDefault delivery channels and email/signing language
signers[].attachment_requirementsDefault requested files
signature_fieldsNon-variable fields, including signer input fields and company seals (organization_seal)
signature_fields[].is_requiredAlways true for signature/stamp/name; saved value otherwise
variablesDeduplicated by variable name; includes name, label, default value, and type
variables[].is_requiredAlways false
variables[].value_typetext, number, checkbox, date, or address; dates include display metadata and numbers include number_format; formula variables are not listed
text_align on fields/variablesleft, center, right, or null when not applicable
can_create_link_signingTrue when the template has a PDF and exactly one signer role

Download errors include TEMPLATE_NOT_FOUND and TEMPLATE_FILE_NOT_FOUND.

Create

POST /v1/link-signings

FieldRequiredMeaning
template_uuidYestemplate_id from a template response
nameYesManagement name
max_submissionsYesSubmission limit, at least 1
descriptionNoInstructions for signers
expires_atNoUTC ISO 8601 timestamp
require_identity_verificationNoRequire mobile identity verification; default false
variablesNoTemplate values shared by all contracts from this link
json
{
  "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

MethodEndpointBehavior
GET/v1/link-signingsPaginated list
GET/v1/link-signings/{id}Details including saved variables
PATCH/v1/link-signings/{id}Change only supplied settings
POST/v1/link-signings/{id}/pauseactive → paused
POST/v1/link-signings/{id}/resumepaused → active
POST/v1/link-signings/{id}/closeClose 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

json
{
  "success": false,
  "error": { "code": "ERROR_CODE", "message": "Diagnostic message" },
  "meta": { "timestamp": "2025-01-06T10:00:00Z" }
}
HTTPMeaning
200 / 201Success / created
400Invalid request
401Authentication failure
403Authorization or usage restriction
404Resource not found
409Conflicts with the current state, such as paused signing
429Request/session limit exceeded
500Server error
CodeMeaning
API_KEY_REQUIRED / INVALID_API_KEYMissing or invalid key
VALIDATION_ERRORInvalid request parameters
QUOTA_EXCEEDEDMonthly usage limit reached
UPLOAD_SESSION_NOT_FOUNDUpload session missing
PDF_UPLOAD_REJECTEDUnsupported PDF
CONTRACT_NOT_FOUND / TEMPLATE_NOT_FOUND / LINK_SIGNING_NOT_FOUNDResource missing
INVALID_LINK_SIGNING_STATUSUnsupported list-status filter
INVALID_PUBLIC_LINK_SIGNING_REQUESTInvalid link-signing fields or values
INVALID_CONTRACT_STATUSAction unavailable in the current state
CONTRACT_SIGNING_PAUSEDSigning is paused because a revision was requested or a revised version is awaiting approval
INVALID_DISPATCH_MODEAction unavailable for this delivery mode
EXTERNAL_DISPATCH_SCHEDULE_NOT_ALLOWEDScheduling requested for external delivery
APPROVAL_REQUIREDApproval 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

bash
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

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

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 statusMeaning
draftNot sent
scheduledWaiting for scheduled sending
pendingSent, awaiting signatures
in_progressSome participants have signed
completedAll participants have signed
cancelled / expiredCanceled / 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).