File Uploads

Learn how to securely upload files to sajn for use in document fields.

Overview

Uploading a file uses a presigned flow that sends the bytes straight to storage, so there is no API-server size limit:

Request a presigned URL — call POST /api/v1/files with the file’s metadata and checksum. You receive a fileId, a storage key, and a presigned uploadUrl.
Upload the bytes — PUT the raw file to the uploadUrl. Storage verifies the checksum on write.
Confirm the upload (recommended) — call POST /api/v1/files/{id}/confirm to verify the stored object and flip the record from PENDING to CONFIRMED immediately.
Use the storage key — reference the returned key in document fields.

Confirming is optional. If you skip step 3, the file is confirmed lazily the first time it is fetched via GET /api/v1/files/{id}. Calling confirm explicitly verifies the upload up front and is idempotent.

Removed: The legacy byte-through endpoint PUT /api/v1/putFile (hosted at https://upload.sajn.se) is no longer available. Use the presigned flow described below.

Benefits

No byte-through step: bytes go directly to cloud storage (up to 25 MB per file).
Integrity-checked: storage enforces the SHA-256 checksum you provide and rejects mismatched bytes.
Secure: files are scoped to your organization, private by default.

Step 1: Request a Presigned URL

Compute the file’s SHA-256 hash, base64-encoded, then call POST /api/v1/files:

Request

curl -X POST https://app.sajn.se/api/v1/files \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "contract.pdf",
    "mimeType": "application/pdf",
    "size": 102400,
    "checksum": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
    "visibility": "PRIVATE"
  }'

Request Fields

Field	Required	Description
`fileName`	Yes	Original filename including its extension (1–255 chars).
`mimeType`	Yes	MIME type of the file (see Supported formats).
`size`	Yes	File size in bytes (max `26214400` = 25 MB).
`checksum`	Yes	Base64-encoded SHA-256 checksum of the file. Storage enforces it on upload.
`visibility`	No	`PRIVATE` (default) or `PUBLIC`.

Response

{
  "fileId": "file_abc123",
  "key": "f/org_123/abc123def/contract.pdf",
  "uploadUrl": "https://storage.sajn.se/...&x-amz-signature=..."
}

fileId — the created file record ID. Its status is PENDING until the upload is confirmed on first access.
key — the storage key to reference in document fields.
uploadUrl — presigned PUT URL, valid for 1 hour.

Step 2: Upload the Bytes

PUT the raw file to the uploadUrl. You must send the Content-Type and the x-amz-checksum-sha256 headers — storage verifies the checksum and rejects the upload if it doesn’t match:

curl -X PUT "PRESIGNED_UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  -H "x-amz-checksum-sha256: 47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=" \
  --data-binary @contract.pdf

Do not send your sajn Authorization header to the presigned uploadUrl — authentication is already baked into the signed URL.

Step 3: Confirm the Upload (Recommended)

Right after the upload PUT returns 200, call POST /api/v1/files/{id}/confirm. The server reads the persisted object back from storage, verifies its size and checksum, then flips the file from PENDING to CONFIRMED:

curl -X POST https://app.sajn.se/api/v1/files/file_abc123/confirm \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "file_abc123",
  "status": "CONFIRMED",
  "size": 102400,
  "checksumVerified": true
}

size — the byte size of the persisted object, read back from storage.
checksumVerified — whether the storage backend reported a SHA-256 that matched the checksum you supplied at create time.

Confirming is optional but recommended and idempotent — confirming an already-confirmed file returns its recorded state. If you skip it, the file is confirmed automatically the first time it is fetched via GET /api/v1/files/{id}.

File Visibility

Control who can access your uploaded files via the visibility field in Step 1:

PRIVATE (default) — access requires a fresh signed URL (valid for 60 minutes), retrieved via GET /api/v1/files/{id}.
PUBLIC — accessible via a permanent CloudFront URL.

Using Uploaded Files in Documents

After a successful upload, use the storage key in document field metadata. You can either create a new PDF field or update an existing one:

PDF fields use value for the file storage key, while TEXT and HTML fields use content for their data. See the API Reference for full details on each field type.

Create New PDF Field

Use the Create Document Field endpoint to add the uploaded PDF:

curl -X POST https://app.sajn.se/api/v1/documents/doc_123/fields \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PDF",
    "position": 0,
    "fieldMeta": {
      "type": "PDF",
      "value": "f/org_123/abc123def/contract.pdf"
    }
  }'

Update Existing PDF Field

Use the Update Document Field endpoint to replace an existing PDF:

curl -X PATCH https://app.sajn.se/api/v1/documents/doc_123/fields/field_456 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fieldMeta": {
      "type": "PDF",
      "value": "f/org_123/abc123def/contract.pdf"
    }
  }'

Complete Upload Workflow

cURL Example

FILE="contract.pdf"
API_BASE="https://app.sajn.se"

# Compute size and base64-encoded SHA-256 checksum
SIZE=$(wc -c < "$FILE")
CHECKSUM=$(openssl dgst -sha256 -binary "$FILE" | base64)

# Step 1: Request a presigned URL
CREATE_RESPONSE=$(curl -s -X POST "$API_BASE/api/v1/files" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"fileName\": \"$FILE\",
    \"mimeType\": \"application/pdf\",
    \"size\": $SIZE,
    \"checksum\": \"$CHECKSUM\",
    \"visibility\": \"PRIVATE\"
  }")

FILE_ID=$(echo "$CREATE_RESPONSE" | jq -r '.fileId')
STORAGE_KEY=$(echo "$CREATE_RESPONSE" | jq -r '.key')
UPLOAD_URL=$(echo "$CREATE_RESPONSE" | jq -r '.uploadUrl')

# Step 2: Upload the bytes to the presigned URL
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  -H "x-amz-checksum-sha256: $CHECKSUM" \
  --data-binary @"$FILE"

# Step 3: Confirm the upload (recommended)
curl -s -X POST "$API_BASE/api/v1/files/$FILE_ID/confirm" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Step 4: Add the uploaded file as a PDF field
curl -X POST "$API_BASE/api/v1/documents/doc_123/fields" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"type\": \"PDF\",
    \"position\": 0,
    \"fieldMeta\": { \"type\": \"PDF\", \"value\": \"$STORAGE_KEY\" }
  }"

Node.js Example

const crypto = require('crypto');
const fs = require('fs');
const path = require('path');

const API_BASE = 'https://app.sajn.se';

const uploadFile = async (filePath, apiKey, mimeType, visibility = 'PRIVATE') => {
  const bytes = fs.readFileSync(filePath);
  const checksum = crypto.createHash('sha256').update(bytes).digest('base64');

  // Step 1: Request a presigned URL
  const createRes = await fetch(`${API_BASE}/api/v1/files`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      fileName: path.basename(filePath),
      mimeType,
      size: bytes.length,
      checksum,
      visibility
    })
  });

  if (!createRes.ok) {
    throw new Error(`Could not create file: ${createRes.statusText}`);
  }

  const { fileId, key, uploadUrl } = await createRes.json();

  // Step 2: Upload the bytes (no Authorization header — the URL is signed)
  const uploadRes = await fetch(uploadUrl, {
    method: 'PUT',
    headers: {
      'Content-Type': mimeType,
      'x-amz-checksum-sha256': checksum
    },
    body: bytes
  });

  if (!uploadRes.ok) {
    throw new Error(`Upload failed: ${uploadRes.statusText}`);
  }

  // Step 3: Confirm the upload (recommended) — verifies the stored object
  // and flips the record from PENDING to CONFIRMED
  await fetch(`${API_BASE}/api/v1/files/${fileId}/confirm`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  return { fileId, key };
};

const addFileToDocument = async (documentId, storageKey, apiKey) => {
  const res = await fetch(`${API_BASE}/api/v1/documents/${documentId}/fields`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'PDF',
      position: 0,
      fieldMeta: { type: 'PDF', value: storageKey }
    })
  });

  return await res.json();
};

// Usage
(async () => {
  const { key } = await uploadFile('./contract.pdf', 'your-api-key', 'application/pdf');
  const field = await addFileToDocument('doc_123', key, 'your-api-key');
  console.log('Added to document:', field);
})();

File Requirements

Supported Formats

Category	MIME types
Documents	`application/pdf`, `application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/vnd.ms-excel`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `application/vnd.ms-powerpoint`, `application/vnd.openxmlformats-officedocument.presentationml.presentation`
Images	`image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/svg+xml`
Video	`video/mp4`, `video/quicktime`, `video/x-msvideo`, `video/webm`

Limits

Maximum size: 25 MB per file (26214400 bytes).
Checksum: a valid base64-encoded SHA-256 of the exact bytes you upload is required.

Error Handling

Common Errors

File Too Large

{
  "message": "File size exceeds limit"
}

Solution: Ensure the file is under the 25 MB limit and that size matches the actual byte count.

Checksum Mismatch

When the bytes you PUT don’t match the checksum you declared in Step 1, storage rejects the upload. Solution: Re-compute the base64-encoded SHA-256 over the exact bytes you upload, and send it both in the create request and in the x-amz-checksum-sha256 header.

Missing Authentication

{
  "message": "API token was not provided"
}

Solution: Include a valid Authorization: Bearer header on the POST /api/v1/files call (but not on the presigned uploadUrl).

Best Practices

Compute size and checksum together from the same byte buffer you upload.
Validate file type and size client-side before requesting a presigned URL.
Upload promptly — the presigned uploadUrl is only valid for 1 hour.
Store storage keys for later reference in document fields.

Guides

Creating Documents - Learn how to create and configure documents
Send for Signing - Send your document for signatures
Webhooks - Get notified when documents are signed

API Reference

Create a File (presigned upload) - Request a presigned upload URL
Confirm a File - Verify the upload and mark it CONFIRMED
Get File - Retrieve a file (confirms the upload on first fetch)
Create Document Field - Add fields to documents
Update Document Field - Modify existing fields

​File Uploads

​Overview

​Benefits

​Step 1: Request a Presigned URL

​Request

​Request Fields

​Response

​Step 2: Upload the Bytes

​Step 3: Confirm the Upload (Recommended)

​Response

​File Visibility

​Using Uploaded Files in Documents

​Create New PDF Field

​Update Existing PDF Field

​Complete Upload Workflow

​cURL Example

​Node.js Example

​File Requirements

​Supported Formats

​Limits

​Error Handling

​Common Errors

​File Too Large

​Checksum Mismatch

​Missing Authentication

​Best Practices

​Related Resources

​Guides

​API Reference

File Uploads

Overview

Benefits

Step 1: Request a Presigned URL

Request

Request Fields

Response

Step 2: Upload the Bytes

Step 3: Confirm the Upload (Recommended)

Response

File Visibility

Using Uploaded Files in Documents

Create New PDF Field

Update Existing PDF Field

Complete Upload Workflow

cURL Example

Node.js Example

File Requirements

Supported Formats

Limits

Error Handling

Common Errors

File Too Large

Checksum Mismatch

Missing Authentication

Best Practices

Related Resources

Guides

API Reference