Quickstart
Send your first document for signing and download the signed PDF in about five minutes
In this quickstart, you create a document with one party, send it, sign it yourself, and download the sealed PDF. Every request uses API version 2026-10.
Before you begin
You need the following:
- A sajn workspace with API access. API access is included from the Team plan, and in every sandbox. We recommend a sandbox for this quickstart: nothing is billed, BankID is mocked, and the signed PDF is watermarked as a test.
- An email address you can read. sajn sends the signing invitation to it, and rejects addresses on domains that can't receive email.
curl, Node.js 18 or later, or Python 3 with therequestspackage.
Create an API key
In the sajn app, open the workspace you want to work in, and go to Inställningar > Utvecklare > API-nycklar. Click Skapa nyckel, enter a name, choose when the key expires, and copy the key. sajn shows the key only once.
A production key starts with sajn_svc_ or sajn_usr_, and every sandbox key contains _dev_. Store the key in an environment variable:
export SAJN_API_KEY="API_KEY"Replace API_KEY with the key you copied. For more information about keys, see Authentication.
Check the key
Call GET /me to confirm which user, workspace, and organization the key acts as. The Node.js and Python samples define a small sajn helper that the later steps reuse. The Node.js samples use top-level await, so save them in a file with the .mjs extension:
curl https://app.sajn.se/api/v1/me \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10"The response is similar to the following:
{
"id": "cm4k2x9p00000abcd0000mnop",
"email": "alex@example.com",
"name": "Alex Lindqvist",
"workspace": {
"id": "cm4k2x9p00003abcd0000qrst",
"slug": "k3x9p",
"name": "Sales"
},
"organization": {
"id": "cm4k2x9p00004abcd0000uvwx",
"name": "Example AB"
}
}A 401 response with the code UNAUTHORIZED means the key is missing, mistyped, expired, or revoked.
Create a document with a party
Create a document and add the party in the same request. An inline party takes either a contactId or a name and an email. The party in this example signs with click-to-sign and receives the invitation by email.
A document must have an expiration date before you can send it, so set expiresAt:
curl https://app.sajn.se/api/v1/documents \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{
"name": "Consulting agreement",
"expiresAt": "2030-01-01T00:00:00Z",
"parties": [
{
"name": "Kai Berg",
"email": "SIGNER_EMAIL",
"role": "SIGNER",
"delivery": ["EMAIL"],
"signatureMethod": "CLICK_TO_SIGN"
}
]
}'Replace SIGNER_EMAIL with your own email address.
The response is the new document, in DRAFT status, in the same shape as GET /documents/{id}. The following excerpt shows the fields you use next:
{
"id": "cm4k2x9p10001abcd1234efgh",
"name": "Consulting agreement",
"status": "DRAFT",
"expiresAt": "2030-01-01T00:00:00.000Z",
"parties": [
{
"id": "cm4k2x9p20002abcd5678ijkl",
"name": "Kai Berg",
"role": "SIGNER",
"signingStatus": "NOT_SIGNED",
"readStatus": "NOT_OPENED",
"delivery": ["EMAIL"],
"signatureMethod": "CLICK_TO_SIGN"
}
]
}If you use curl, save both IDs:
export DOCUMENT_ID="cm4k2x9p10001abcd1234efgh"
export PARTY_ID="cm4k2x9p20002abcd5678ijkl"Add content
A new document has no content. Add content blocks to it. The request takes a content array, also for one block. This example adds an HTML block; for other block types, such as an uploaded PDF, see Content and fields.
curl 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": "HTML",
"position": 0,
"fieldMeta": {
"type": "HTML",
"content": "<h1>Consulting agreement</h1><p>Kai Berg delivers 40 hours of consulting to Example AB.</p>"
}
}
]
}'The response lists the created blocks in data.
Send the document
Send the document. sajn emails the party an invitation, and the document moves from DRAFT to PENDING:
curl -X POST https://app.sajn.se/api/v1/documents/$DOCUMENT_ID/send \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{}'The response is the document, with status set to PENDING. If your workspace role can't send without approval, the request fails with 409 APPROVAL_REQUIRED; request approval first. For more information, see Send for signing.
Get the signing URL
The invitation email holds a signing link. To get the same link from the API, for example to show it in your own app, get the party:
curl https://app.sajn.se/api/v1/documents/$DOCUMENT_ID/parties/$PARTY_ID \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10"The response includes signingUrl:
{
"id": "cm4k2x9p20002abcd5678ijkl",
"name": "Kai Berg",
"signingStatus": "NOT_SIGNED",
"signingUrl": "https://app.sajn.se/sign/cm4k2x9p10001abcd1234efgh?token=SIGNING_TOKEN"
}Open the URL and sign. Each signing URL belongs to one party, so never publish it. sajn records an audit log entry every time you fetch it.
Wait for completion
After the last party signs, sajn seals the PDF and the document moves from PENDING to COMPLETED. Choose how you find out:
Create a webhook endpoint that subscribes to document.completed. sajn must reach the URL over the public internet, and rejects a URL that answers with an HTML page. For local development, see Test webhooks.
curl https://app.sajn.se/api/v1/webhooks \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{
"url": "WEBHOOK_URL",
"events": ["document.completed"],
"enabled": true,
"apiVersion": "2026-10"
}'Replace WEBHOOK_URL with your endpoint's HTTPS URL. Create the endpoint once, not once per document. It receives the events of every document in the workspace. Store the secret from the response, which starts with whsec_. sajn returns it only when you create the webhook or rotate its secret, and you use it to verify signatures.
When the document completes, your endpoint receives a POST request similar to the following:
{
"id": "cm4k2x9p30005abcd9012mnop",
"type": "document.completed",
"createdAt": "2026-10-01T09:41:12.000Z",
"apiVersion": "2026-10",
"workspaceId": "cm4k2x9p00003abcd0000qrst",
"environment": "SANDBOX",
"actor": null,
"data": {
"object": {
"id": "cm4k2x9p10001abcd1234efgh",
"name": "Consulting agreement",
"status": "COMPLETED",
"completedAt": "2026-10-01T09:41:10.000Z"
}
}
}data.object is the document, in the shape of GET /documents/{id}, so data.object.id is the document ID. For the full payload, see Webhook payloads.
Download the signed PDF
Get the SIGNED file to get a download URL, then download the PDF. The URL works for 15 minutes:
DOWNLOAD_URL=$(curl -s https://app.sajn.se/api/v1/documents/$DOCUMENT_ID/files/SIGNED \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" | jq -r .url)
curl -o consulting-agreement.pdf "$DOWNLOAD_URL"The response has the file's type, url, and expiresAt, and the curl sample uses jq to read url. Until the document is COMPLETED, the request returns 409 with the code INVALID_STATE.
The PDF ends with a signing certificate that records who signed, how, and when.
Next steps
Was this page helpful?
Last updated on