Downloading Signed Documents

Once all signers have completed a document, you can download the signed PDF along with the audit trail. This guide covers manual downloads, automated retrieval, and archiving best practices.

Download Endpoint

The download endpoint returns a short-lived, pre-signed URL — not the file bytes directly. Request the URL, then fetch it to retrieve the PDF.

# 1. Request a download URL (defaults to the signed document)
curl -X GET "https://app.sajn.se/api/v1/documents/doc_123/download" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "downloadUrl": "https://files.sajn.se/documents/doc_123/signed.pdf?signature=..."
}

# 2. Fetch the file from the pre-signed URL
curl -L "https://files.sajn.se/documents/doc_123/signed.pdf?signature=..." \
  -o "signed-document.pdf"

The downloadUrl is valid for 1 hour. Request a fresh one if it expires.

Signed document showing embedded signatures from all parties

Choosing which file to download

Choose which file the pre-signed URL points to with the fileType value:

`fileType`	Returns	Availability
`SIGNED` (default)	The signed, sealed PDF with all signatures embedded	Document must be `COMPLETED`
`ORIGINAL`	The original, unsigned document	Any status
`JOURNAL`	The signing journal / audit trail	Document must be `COMPLETED`

There are two forms of the endpoint:

For new integrations, prefer the path form GET /api/v1/documents/{id}/download/{fileType} — the file type is explicit and required, which avoids ambiguity.

# Path form (recommended) — file type is part of the URL
curl -X GET "https://app.sajn.se/api/v1/documents/doc_123/download/ORIGINAL" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Query form — fileType is optional and defaults to SIGNED
curl -X GET "https://app.sajn.se/api/v1/documents/doc_123/download?fileType=JOURNAL" \
  -H "Authorization: Bearer YOUR_API_KEY"

Both forms return the same { "downloadUrl": "..." } JSON response. The endpoint returns 404 if the requested file doesn’t exist for the document (for example, requesting JOURNAL before the document is completed).

Response Headers on the pre-signed URL

When you fetch the downloadUrl, the file is served with:

Header	Description
`Content-Type`	`application/pdf`
`Content-Disposition`	`attachment; filename="document-name.pdf"`
`Content-Length`	File size in bytes

Audit Trail / Signing Journal

The signing journal is a separate PDF holding the full event log for the document: every party with their identity and signing method, and every recorded event — sent, opened, signed, reminded, sealed — with its timestamp and IP address. The signed PDF itself already ends with a signing certificate, a summary of the same evidence sealed into the document. Download the journal when you need the complete trail rather than the summary.

Downloading the Journal

The signing journal is a separate file — download it with fileType=JOURNAL:

# 1. Get a pre-signed URL for the journal
curl -X GET "https://app.sajn.se/api/v1/documents/doc_123/download?fileType=JOURNAL" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. Fetch it from the returned downloadUrl
curl -L "<downloadUrl from step 1>" -o "audit-journal.pdf"

Storing Signed Documents

Download to Local Storage

const fs = require('fs');
const axios = require('axios');

async function downloadDocument(documentId, outputPath, fileType = 'SIGNED') {
  // 1. Request a pre-signed download URL
  const { data } = await axios.get(
    `https://app.sajn.se/api/v1/documents/${documentId}/download`,
    {
      headers: { 'Authorization': `Bearer ${process.env.SAJN_API_KEY}` },
      params: { fileType }
    }
  );

  // 2. Stream the file from the pre-signed URL
  const file = await axios.get(data.downloadUrl, { responseType: 'stream' });
  const writer = fs.createWriteStream(outputPath);
  file.data.pipe(writer);

  return new Promise((resolve, reject) => {
    writer.on('finish', resolve);
    writer.on('error', reject);
  });
}

// Usage
await downloadDocument('doc_123', './contracts/signed-agreement.pdf');

Upload to Cloud Storage

Amazon S3

const AWS = require('aws-sdk');
const axios = require('axios');

const s3 = new AWS.S3();

async function downloadAndUploadToS3(documentId, bucket, key) {
  // Get a pre-signed download URL from sajn, then fetch the file
  const { data } = await axios.get(
    `https://app.sajn.se/api/v1/documents/${documentId}/download`,
    { headers: { 'Authorization': `Bearer ${process.env.SAJN_API_KEY}` } }
  );
  const file = await axios.get(data.downloadUrl, { responseType: 'arraybuffer' });

  // Upload to S3
  await s3.putObject({
    Bucket: bucket,
    Key: key,
    Body: file.data,
    ContentType: 'application/pdf'
  }).promise();

  console.log(`Document uploaded to s3://${bucket}/${key}`);
}

Google Cloud Storage

const { Storage } = require('@google-cloud/storage');
const axios = require('axios');

const storage = new Storage();

async function downloadAndUploadToGCS(documentId, bucket, fileName) {
  // Get a pre-signed download URL from sajn, then fetch the file
  const { data } = await axios.get(
    `https://app.sajn.se/api/v1/documents/${documentId}/download`,
    { headers: { 'Authorization': `Bearer ${process.env.SAJN_API_KEY}` } }
  );
  const download = await axios.get(data.downloadUrl, { responseType: 'arraybuffer' });

  const file = storage.bucket(bucket).file(fileName);
  await file.save(download.data, {
    contentType: 'application/pdf'
  });

  console.log(`Document uploaded to gs://${bucket}/${fileName}`);
}

Automating Downloads with Webhooks

The most common pattern is to automatically download documents when they’re completed using webhooks.

Webhook Handler

const express = require('express');
const axios = require('axios');
const crypto = require('crypto');

const app = express();
app.use(express.json());

// sajn sends the secret you configured as a plain header — compare it, don't hash it
const secretMatches = (received) => {
  const expected = process.env.WEBHOOK_SECRET;
  const a = Buffer.from(received ?? '');
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
};

app.post('/webhooks/sajn', async (req, res) => {
  if (!secretMatches(req.headers['x-sajn-secret'])) {
    return res.status(401).send('Invalid secret');
  }

  const { event, payload } = req.body;

  // Handle document completion — payload is the document object
  if (event === 'DOCUMENT_COMPLETED') {
    try {
      await downloadAndArchive(payload.id, payload.externalId);
      console.log(`Archived document ${payload.id}`);
    } catch (error) {
      console.error(`Failed to archive document: ${error.message}`);
    }
  }

  res.status(200).send('OK');
});

// Fetch one file type and return its bytes
async function fetchFile(documentId, fileType) {
  const { data } = await axios.get(
    `https://app.sajn.se/api/v1/documents/${documentId}/download`,
    {
      headers: { 'Authorization': `Bearer ${process.env.SAJN_API_KEY}` },
      params: { fileType }
    }
  );
  const file = await axios.get(data.downloadUrl, { responseType: 'arraybuffer' });
  return file.data;
}

async function downloadAndArchive(documentId, externalId) {
  // Archive both the signed document and its signing journal
  const [pdf, journal] = await Promise.all([
    fetchFile(documentId, 'SIGNED'),
    fetchFile(documentId, 'JOURNAL')
  ]);

  // Store in your system (database, file system, cloud storage)
  await saveToArchive({
    documentId,
    externalId,
    pdf,
    journal,
    archivedAt: new Date()
  });
}

app.listen(3000);

Python Webhook Handler

from flask import Flask, request, abort
import hmac
import requests
import os

app = Flask(__name__)

@app.route('/webhooks/sajn', methods=['POST'])
def webhook():
    # sajn sends the secret you configured as a plain header — compare it, don't hash it
    secret = request.headers.get('X-Sajn-Secret', '')
    if not hmac.compare_digest(secret, os.environ['WEBHOOK_SECRET']):
        abort(401)

    body = request.json
    event = body['event']
    payload = body['payload']

    if event == 'DOCUMENT_COMPLETED':
        download_and_archive(payload['id'], payload.get('externalId'))

    return 'OK', 200

def download_and_archive(document_id, external_id):
    # 1. Request a pre-signed download URL (defaults to the signed document)
    res = requests.get(
        f'https://app.sajn.se/api/v1/documents/{document_id}/download',
        headers={'Authorization': f'Bearer {os.environ["SAJN_API_KEY"]}'},
        params={'fileType': 'SIGNED'}
    )
    download_url = res.json()['downloadUrl']

    # 2. Fetch the file from the pre-signed URL
    pdf = requests.get(download_url).content

    # Save to your archive
    filename = f'contracts/{external_id or document_id}.pdf'
    with open(filename, 'wb') as f:
        f.write(pdf)

    print(f'Archived document to {filename}')

Archiving Best Practices

Download immediately on completion

Set up a webhook handler to download documents as soon as they’re completed. This ensures you always have a copy, even if the document is later deleted from sajn.

Download the signing journal

Always download the signing journal (fileType=JOURNAL) alongside the signed PDF for legal purposes. The journal provides proof of signing events.

Use external IDs for organization

Set externalId on documents to match your system’s identifiers. This makes it easy to organize and retrieve archived documents.

Store metadata alongside PDFs

Save document metadata (signers, dates, custom fields) alongside the PDF for easier searching and reporting.

Implement redundant storage

Store signed documents in multiple locations (e.g., primary storage + backup) for disaster recovery.

Consider retention policies

Define how long to keep signed documents based on legal requirements. Some contracts may need to be retained for 7+ years.

Secure your archive

Signed documents often contain sensitive information. Ensure your archive has appropriate access controls and encryption.

Error Handling

Document Not Ready

If the requested file isn’t available yet (for example, the signed PDF or journal before completion), the endpoint returns 404 with a JSON body:

{
  "message": "Document is not yet fully signed. Current status: SENT",
  "code": "DOCUMENT_NOT_COMPLETED"
}

Document Not Found

{
  "message": "Document with ID doc_123 was not found",
  "code": "DOCUMENT_NOT_FOUND"
}

Handling Errors

async function safeDownload(documentId, fileType = 'SIGNED') {
  try {
    // Request the pre-signed URL (404 if the file isn't available yet)
    const response = await axios.get(
      `https://app.sajn.se/api/v1/documents/${documentId}/download`,
      {
        headers: { 'Authorization': `Bearer ${process.env.SAJN_API_KEY}` },
        params: { fileType },
        validateStatus: (status) => status < 500
      }
    );

    if (response.status === 404) {
      console.error(`File not available (${response.data?.code ?? 'NOT_FOUND'})`);
      return null;
    }

    // Fetch the actual file from the pre-signed URL
    const file = await axios.get(response.data.downloadUrl, { responseType: 'arraybuffer' });
    return file.data;
  } catch (error) {
    console.error(`Download failed: ${error.message}`);
    throw error;
  }
}

Next Steps

Webhooks

Set up automated document processing

Reminders & Expiration

Manage unsigned documents

API Reference

Download endpoint documentation

Creating Documents

Learn document creation basics

​Downloading Signed Documents

​Download Endpoint

​Choosing which file to download

​Response Headers on the pre-signed URL

​Audit Trail / Signing Journal

​Downloading the Journal

​Storing Signed Documents

​Download to Local Storage

​Upload to Cloud Storage

​Amazon S3

​Google Cloud Storage

​Automating Downloads with Webhooks

​Webhook Handler

​Python Webhook Handler

​Archiving Best Practices

​Error Handling

​Document Not Ready

​Document Not Found

​Handling Errors

​Next Steps

Webhooks

Reminders & Expiration

API Reference

Creating Documents

Downloading Signed Documents

Download Endpoint

Choosing which file to download

Response Headers on the pre-signed URL

Audit Trail / Signing Journal

Downloading the Journal

Storing Signed Documents

Download to Local Storage

Upload to Cloud Storage

Amazon S3

Google Cloud Storage

Automating Downloads with Webhooks

Webhook Handler

Python Webhook Handler

Archiving Best Practices

Error Handling

Document Not Ready

Document Not Found

Handling Errors

Next Steps