Sending Documents for Signing

Guide to sending documents and managing the signing process

Sending Documents for Signing

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

Prerequisites

Before sending a document:

1. Document must be in DRAFT status
2. At least one signer must be added with:
   • deliveryMethod configured (EMAIL, SMS, or NONE)
   • requiredSignature configured (DRAWING, BANKID, CLICK_TO_SIGN, or MANUAL)
3. 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": "[e-mail]",
      "role": "SIGNER",
      "deliveryMethod": "EMAIL",
      "requiredSignature": "DRAWING"
    },
    {
      "name": "Jane Manager",
      "phone": "[phone]",
      "role": "SIGNER",
      "deliveryMethod": "SMS",
      "requiredSignature": "BANKID",
      "twoStepVerification": "SMS_BEFORE_SIGNING"
    },
    {
      "name": "External Reviewer",
      "email": "[e-mail]",
      "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": "[e-mail]",
  "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": "[e-mail]",
      "signingOrder": 1,
      "deliveryMethod": "EMAIL",
      "requiredSignature": "BANKID"
    },
    {
      "name": "Employee",
      "email": "[e-mail]",
      "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:

1. Document status changes to COMPLETED
2. Final sealed document is generated
3. All parties receive completion notification (if configured)
4. 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

1. Check spam/junk folders
2. Verify email address is correct
3. Update email address if needed
4. Resend the document

Wrong Signing Order

If you need to change signing order:

1. Cancel the current document
2. Create a new document with correct order
3. Send the new document

Document Stuck in SENDING

If document is stuck in SENDING status, contact support at [e-mail].

Next Steps

Webhooks

Get real-time signing notifications

Document Concepts

Learn more about document workflows