Upload files
Upload a PDF file straight to storage with a presigned URL, and attach it to a document as a PDF field
In this guide, you upload a PDF file to sajn and attach it to a draft document. The bytes go straight to storage through a presigned URL, so the API server never handles them.
Before you begin
- Store your API key in the
SAJN_API_KEYenvironment variable. To create a key, go to workspace settings in the sajn app, then Utvecklare (Developer) > API-nycklar (API keys). - Have a
DRAFTdocument. For more information, see Create a document. - Have a file of at most 25 MB (26,214,400 bytes) in a supported format. sajn accepts PDF, Word, Excel, and PowerPoint documents; JPEG, PNG, GIF, WebP, and SVG images; and MP4, QuickTime, AVI, and WebM video. For the exact MIME types, see Create a file.
How the upload works
- You create a file record with the file's name, MIME type, size, and SHA-256 checksum. The response is the file, with its
id, a storagekey, and anuploadUrl. - You send the bytes to
uploadUrlin aPUTrequest. Storage rejects bytes that don't match the checksum. - You confirm the upload, so sajn verifies the stored bytes.
- You reference the storage
keyin a document field.
Upload a file and attach it
Compute the checksum
The checksum is the SHA-256 hash of the exact bytes you upload, encoded as base64:
FILE="contract.pdf"
SIZE=$(wc -c < "$FILE" | tr -d ' ')
CHECKSUM=$(openssl dgst -sha256 -binary "$FILE" | base64)Create the file record
Send a POST request to /api/v1/files:
curl -X POST https://app.sajn.se/api/v1/files \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d "{
\"fileName\": \"$FILE\",
\"mimeType\": \"application/pdf\",
\"size\": $SIZE,
\"checksum\": \"$CHECKSUM\"
}"The response is the file, in the same shape as Get file by ID, plus key and uploadUrl. The following example leaves out url and uploadedBy:
{
"id": "cm4k2xf3u0007abcd2468cdef",
"filename": "contract.pdf",
"mimeType": "application/pdf",
"size": 102400,
"visibility": "PRIVATE",
"createdAt": "2026-10-01T09:00:00.000Z",
"updatedAt": "2026-10-01T09:00:00.000Z",
"key": "f/cm4k2xz0a0000abcd0000orgx/cm4k2xf3u0007abcd2468cdef/contract.pdf",
"uploadUrl": "https://storage.sajn.se/f/cm4k2xz0a0000abcd0000orgx/cm4k2xf3u0007abcd2468cdef/contract.pdf?X-Amz-Signature=3f9a"
}uploadUrl is valid for 15 minutes. visibility is optional: PRIVATE, the default, serves the file only through short-lived signed URLs, and PUBLIC serves it from a permanent URL.
Upload the bytes
Send the file to uploadUrl with the same Content-Type and the checksum in the x-amz-checksum-sha256 header. Don't send your Authorization header; the URL is already signed:
curl -X PUT "UPLOAD_URL" \
-H "Content-Type: application/pdf" \
-H "x-amz-checksum-sha256: $CHECKSUM" \
--data-binary @"$FILE"Replace UPLOAD_URL with the uploadUrl from the previous step. A successful upload returns an empty 200 response.
Confirm the upload
Confirm the file, so sajn verifies the stored size and checksum before you use it:
curl -X POST https://app.sajn.se/api/v1/files/FILE_ID/confirm \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10"Replace FILE_ID with the file id. sajn checks the stored size and, when storage records it, the checksum. The response is the file, in the same shape as Get file by ID.
Confirming is idempotent. If you skip it, sajn confirms the file the first time you call Get file by ID.
Attach the file to the document
Create a PDF content block whose fieldMeta.value is the storage key:
curl -X POST https://app.sajn.se/api/v1/documents/DOCUMENT_ID/content \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{
"content": [
{
"type": "PDF",
"position": 0,
"fieldMeta": { "type": "PDF", "value": "STORAGE_KEY" }
}
]
}'Replace the following:
DOCUMENT_ID: the ID of the draft document.STORAGE_KEY: thekeyfrom the file record.
The response has the created block in data, in the same shape as Get a document content block. To replace the PDF of an existing block, send a PATCH request to /api/v1/documents/DOCUMENT_ID/content/CONTENT_ID with the full fieldMeta.
To place signature boxes and input fields on the PDF's pages, see Place fields on a PDF.
Complete example
The following programs run the whole flow for contract.pdf. Set SAJN_API_KEY and DOCUMENT_ID in the environment first:
#!/usr/bin/env bash
set -euo pipefail
API="https://app.sajn.se/api/v1"
FILE="contract.pdf"
SIZE=$(wc -c < "$FILE" | tr -d ' ')
CHECKSUM=$(openssl dgst -sha256 -binary "$FILE" | base64)
HEADERS=(-H "Authorization: Bearer $SAJN_API_KEY" -H "Sajn-Version: 2026-10" -H "Content-Type: application/json")
CREATED=$(curl -sf -X POST "$API/files" "${HEADERS[@]}" -d "{
\"fileName\": \"$FILE\", \"mimeType\": \"application/pdf\",
\"size\": $SIZE, \"checksum\": \"$CHECKSUM\"
}")
FILE_ID=$(echo "$CREATED" | jq -r .id)
KEY=$(echo "$CREATED" | jq -r .key)
curl -sf -X PUT "$(echo "$CREATED" | jq -r .uploadUrl)" \
-H "Content-Type: application/pdf" \
-H "x-amz-checksum-sha256: $CHECKSUM" \
--data-binary @"$FILE"
curl -sf -X POST "$API/files/$FILE_ID/confirm" "${HEADERS[@]}"
curl -sf -X POST "$API/documents/$DOCUMENT_ID/content" "${HEADERS[@]}" -d "{
\"content\": [{
\"type\": \"PDF\", \"position\": 0,
\"fieldMeta\": { \"type\": \"PDF\", \"value\": \"$KEY\" }
}]
}" | jq '.data[0].id'Handle errors
400 VALIDATION_FAILEDonPOST /api/v1/files: themimeTypeisn't supported, orsizeis more than 26,214,400 bytes. Theissuesarray names the field.403from theuploadUrl: the URL expired, or theContent-Typedoesn't matchmimeType. Create a new file record.400from theuploadUrl: the bytes don't match the checksum. Compute the size and the checksum from the same bytes you upload.401 UNAUTHORIZEDon a sajn endpoint: theAuthorizationheader is missing or the key is invalid. TheuploadUrldoesn't take the header.
For the error shape and every code, see Errors.
Next steps
Was this page helpful?
Last updated on