Sending Documents for Signing

Learn how to send documents to signers and manage the signing workflow.

Prerequisites

Before sending a document:

Document must be in DRAFT status
At least one signer must be added with:
- deliveryMethod configured (EMAIL, SMS, or NONE)
- requiredSignature configured (DRAWING, BANKID, CLICK_TO_SIGN, or MANUAL)
Signers must have valid email addresses (for EMAIL delivery) or phone numbers (for SMS delivery)

Basic Send

Send a document to signers:

curl -X POST https://app.sajn.se/api/v1/documents/{documentId}/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

The send endpoint triggers delivery based on each signer’s individual deliveryMethod setting.

Adding a Custom Message

Include a personal message in the signing invitation:

curl -X POST https://app.sajn.se/api/v1/documents/{documentId}/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customMessage": "Hi, please review and sign the updated employment contract. Let me know if you have any questions!"
  }'

Line Breaks

Use \n in the JSON string to insert line breaks in the rendered message:

{
  "customMessage": "Hej\nrad 2"
}

Template Variables

Use {{variableName}} syntax to insert dynamic values. Each signer receives a personalized version of the message. Recipient (signer):

Variable	Description
`{{firstName}}` / `{{recipientFirstName}}`	Signer’s first name
`{{lastName}}` / `{{recipientLastName}}`	Signer’s last name
`{{fullName}}` / `{{recipientFullName}}`	Signer’s full name
`{{recipientEmail}}`	Signer’s email address
`{{recipientPhone}}`	Signer’s phone number

Sender (you):

Variable	Description
`{{senderFirstName}}`	Sender’s first name
`{{senderLastName}}`	Sender’s last name
`{{senderFullName}}`	Sender’s full name
`{{senderEmail}}`	Sender’s email address
`{{senderPhone}}`	Sender’s phone number

Document:

Variable	Description
`{{documentName}}`	Document name/title
`{{signUrl}}`	Direct signing URL for the recipient

Example combining variables and line breaks:

{
  "customMessage": "Hej {{firstName}},\n\nVänligen signera {{documentName}}.\n\nMvh,\n{{senderFullName}}"
}

Per-Signer Delivery and Signature Settings

Delivery method and signature type are configured per-signer when adding them to the document, not at send time. This allows different signers to receive invitations through different channels and use different signature types.

Example: Mixed Delivery Methods

{
  "signers": [
    {
      "name": "John Doe",
      "email": "[email protected]",
      "role": "SIGNER",
      "deliveryMethod": "EMAIL",
      "requiredSignature": "DRAWING"
    },
    {
      "name": "Jane Manager",
      "phone": "+46701234567",
      "role": "SIGNER",
      "deliveryMethod": "SMS",
      "requiredSignature": "BANKID",
      "twoStepVerification": "SMS_BEFORE_SIGNING"
    },
    {
      "name": "External Reviewer",
      "email": "[email protected]",
      "role": "REVIEWER",
      "deliveryMethod": "NONE"
    }
  ]
}

In this example:

John receives an email with a drawing signature
Jane receives an SMS with BankID + SMS verification before signing
The external reviewer doesn’t receive automatic delivery (use signing URL directly)

Delivery Methods

Method	Description
`EMAIL`	Signing invitation sent via email
`SMS`	Signing link sent via SMS (requires phone number)
`NONE`	No automatic delivery - retrieve signing URL manually

Signature Types

Type	Description
`DRAWING`	Free-hand signature drawing (SES)
`BANKID`	Swedish BankID electronic signature (AES) - requires SSN
`CLICK_TO_SIGN`	Simple click-to-sign (SES)
`MANUAL`	For in-person signing

Two-Step Verification

For additional security, enable SMS verification before signing:

{
  "deliveryMethod": "EMAIL",
  "requiredSignature": "DRAWING",
  "twoStepVerification": "SMS_BEFORE_SIGNING"
}

This sends an SMS code that the signer must enter before they can sign.

Retrieving Signing URLs

For signers with deliveryMethod: "NONE", or when you need to share the signing URL directly:

GET /api/v1/documents/{documentId}/signers/{signerId}

Response:

{
  "id": "signer_123",
  "name": "John Doe",
  "email": "[email protected]",
  "token": "abc123...",
  "signingUrl": "https://app.sajn.se/sign/doc_123?token=abc123..."
}

Each time you retrieve a signing URL, an audit log entry is created. Only fetch signing URLs when you need to share them with signers.

Signing Workflows

Parallel Signing

All signers can sign simultaneously (default):

{
  "documentMeta": {
    "signingOrder": "PARALLEL"
  }
}

All signers receive invitations immediately when the document is sent.

Sequential Signing

Signers must sign in order:

{
  "documentMeta": {
    "signingOrder": "SEQUENTIAL"
  },
  "signers": [
    {
      "name": "Manager",
      "email": "[email protected]",
      "signingOrder": 1,
      "deliveryMethod": "EMAIL",
      "requiredSignature": "BANKID"
    },
    {
      "name": "Employee",
      "email": "[email protected]",
      "signingOrder": 2,
      "deliveryMethod": "EMAIL",
      "requiredSignature": "DRAWING"
    }
  ]
}

Only the first signer receives the invitation. Others receive theirs after the previous signer completes.

Tracking Status

After sending, monitor document and signer status:

GET /api/v1/documents/{documentId}

Response shows individual signer progress:

{
  "id": "doc_123",
  "status": "PENDING",
  "signers": [
    {
      "name": "John Doe",
      "readStatus": "OPENED",
      "signingStatus": "NOT_SIGNED",
      "signedAt": null
    },
    {
      "name": "Jane Manager",
      "readStatus": "READ",
      "signingStatus": "SIGNED",
      "signedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Resending Invitations

If a signer didn’t receive or lost their invitation, update and resend:

# Update signer email if needed
PATCH /api/v1/documents/{docId}/signers/{signerId}

# Resend the document
POST /api/v1/documents/{docId}/send

Document Completion

When all signers have signed:

Document status changes to COMPLETED
Final sealed document is generated
All parties receive completion notification (if configured)
Webhooks fire DOCUMENT_COMPLETED event

Download the completed document:

GET /api/v1/documents/{documentId}/download

Best Practices

Test before sending

Use deliveryMethod: "NONE" on signers to get signing URLs for testing before sending to real signers.

Clear instructions

Always include a custom message explaining what the document is and why it needs signing.

Sequential for approvals

Use sequential signing when manager approval is needed before employee signatures.

Set expiration

Set reasonable expiration dates (7-30 days) to maintain urgency.

Monitor progress

Use webhooks or polling to track signing progress and send reminders if needed.

Troubleshooting

Signer Didn’t Receive Email

Check spam/junk folders
Verify email address is correct
Update email address if needed
Resend the document

Wrong Signing Order

If you need to change signing order:

Cancel the current document
Create a new document with correct order
Send the new document

Document Stuck in SENDING

If document is stuck in SENDING status, contact support at [email protected].

Next Steps

Webhooks

Get real-time signing notifications

Document Concepts

Learn more about document workflows

​Sending Documents for Signing

​Prerequisites

​Basic Send

​Adding a Custom Message

​Line Breaks

​Template Variables

​Per-Signer Delivery and Signature Settings

​Example: Mixed Delivery Methods

​Delivery Methods

​Signature Types

​Two-Step Verification

​Retrieving Signing URLs

​Signing Workflows

​Parallel Signing

​Sequential Signing

​Tracking Status

​Resending Invitations

​Document Completion

​Best Practices

​Troubleshooting

​Signer Didn’t Receive Email

​Wrong Signing Order

​Document Stuck in SENDING

​Next Steps

Webhooks

Document Concepts

Sending Documents for Signing

Prerequisites

Basic Send

Adding a Custom Message

Line Breaks

Template Variables

Per-Signer Delivery and Signature Settings

Example: Mixed Delivery Methods

Delivery Methods

Signature Types

Two-Step Verification

Retrieving Signing URLs

Signing Workflows

Parallel Signing

Sequential Signing

Tracking Status

Resending Invitations

Document Completion

Best Practices

Troubleshooting

Signer Didn’t Receive Email

Wrong Signing Order

Document Stuck in SENDING

Next Steps