Documents

Documents are the core of sajn. They represent contracts, agreements, or any other documents that need to be signed.

Document Lifecycle

A document goes through several stages:

Document Statuses

Status	Description
`DRAFT`	Document is being prepared, not yet sent
`SENDING`	Document is being sent to signers
`PENDING`	Document sent, awaiting signatures
`COMPLETED`	All signers have signed
`EXPIRED`	Document expired before all signatures collected
`CANCELLED`	Document was cancelled
`IMPORTED`	Document imported from external archive

Document Types

sajn supports different document types:

SIGNABLE (Default)

Standard documents that require signatures from one or more signers.

{
  "name": "Employment Contract",
  "type": "SIGNABLE"
}

ACCEPTABLE

Documents that require acceptance rather than a signature, useful for terms of service or policies.

{
  "name": "Terms of Service",
  "type": "ACCEPTABLE"
}

ARCHIVE_IMPORTED

Documents imported from external systems for archival purposes.

Document Metadata

Documents can have rich metadata to control the signing process:

{
  "documentMeta": {
    "subject": "Please sign the employment contract",
    "message": "Welcome to the team! Please review and sign.",
    "signingOrder": "SEQUENTIAL",
    "forceReadFullDocument": true,
    "showCommentsToSigners": false,
    "preferredLanguage": "sv",
    "validFrom": "2024-01-01T00:00:00Z",
    "validTo": "2024-12-31T23:59:59Z",
    "value": "500000"
  }
}

Delivery method and signature type are configured per-signer. See Signers for details.

Key Metadata Fields

signingOrder

PARALLEL: All signers can sign simultaneously SEQUENTIAL: Signers must sign in order (1, 2, 3, etc.)

forceReadFullDocument

When true, signers must scroll through the entire document before signing.

preferredLanguage

Language for the signing interface: sv (Swedish), en (English), no (Norwegian), da (Danish), fi (Finnish), de (German), is (Icelandic), es (Spanish), fr (French), or it (Italian).

Document Fields

Documents can contain different types of fields:

TEXT: Rich text content sections
HTML: Raw HTML content with custom styling (API-only, sanitized server-side)
FORM: Form fields for signers to fill out
PDF: Embedded PDF files
PRODUCT_TABLE: Tables with products/services and pricing
TABLE: Simple tables with custom rows and columns

Learn more in the Document Fields API reference.

Tags and Organization

Organize documents using:

Tags: Categorize documents (e.g., “Contract”, “NDA”, “Employment”)
Custom Fields: Add structured metadata (e.g., project name, department)
External ID: Link to your own system’s identifiers

Expiration

Set an expiration date to automatically expire documents that aren’t completed in time:

{
  "expiresAt": "2024-12-31T23:59:59Z"
}

When a document expires, its status changes to EXPIRED and signers can no longer access it.

Retention and Deletion

Completed documents are stored indefinitely by default. Each workspace can enable a retention policy that moves completed documents to the trash after a set period, with per-document exemptions available. Any document can be deleted regardless of status via DELETE /api/v1/documents/{id}, which moves it to the trash; permanent deletion is a separate, irreversible operation via POST /api/v1/documents/{id}/purge. See the guide on storage and deletion for details.

Best Practices

Clear Naming

Use descriptive document names that clearly identify the content and purpose.

Appropriate Expiration

Set reasonable expiration dates - typically 7-30 days for most documents.

Sequential When Needed

Use sequential signing when the order matters (e.g., manager approval before employee signature).

External IDs

Use external IDs to link documents to records in your own systems.

Next Steps

Signers

Learn about adding signers to documents

Create Document Guide

Detailed guide on creating documents

​Documents

​Document Lifecycle

​Document Statuses

​Document Types

​SIGNABLE (Default)

​ACCEPTABLE

​ARCHIVE_IMPORTED

​Document Metadata

​Key Metadata Fields

​Document Fields

​Tags and Organization

​Expiration

​Retention and Deletion

​Best Practices

Clear Naming

Appropriate Expiration

Sequential When Needed

External IDs

​Next Steps

Signers

Create Document Guide

Documents

Document Lifecycle

Document Statuses

Document Types

SIGNABLE (Default)

ACCEPTABLE

ARCHIVE_IMPORTED

Document Metadata

Key Metadata Fields

Document Fields

Tags and Organization

Expiration

Retention and Deletion

Best Practices

Next Steps