Documents

A document is an agreement that one or more people sign. It combines three things:

Content: an ordered list of content blocks, such as text, an uploaded PDF, a form, or a product table.
Parties: the people who sign, review, or organize the document. For more information, see Parties.
Settings: the expiration date in expiresAt, and the signing order, invitation message, language, and other options in documentMeta.

When every party who must sign has signed, sajn seals the PDF with an eIDAS seal and appends a signing certificate.

Document lifecycle

A document’s status tells you where it is. The following diagram shows the transitions:

Statuses

Status	Meaning	What you can do
`DRAFT`	Being prepared. Nothing has been sent.	Change everything: content, parties, and settings.
`PENDING_APPROVAL`	Submitted for internal approval. The approvers must approve it before sajn sends it. `approvalRequestId` names the approval request.	Wait for the approvers, or cancel the approval request.
`PENDING`	Sent. Waiting for signatures.	Add, correct, or remove parties who haven’t signed, send reminders, change some settings, or withdraw it. Content is locked.
`COMPLETED`	Every required party signed, and the PDF is sealed.	Download the signed PDF and the signing journal. Nothing can change.
`REJECTED`	A party declined to sign.	Create a new document if the agreement is still needed.
`EXPIRED`	The expiration date passed before everyone signed.	Move the expiration date to reopen it for signing, or withdraw it.
`IMPORTED`	An agreement signed outside sajn, imported into the archive. It’s never sent for signing.	Edit its details, content, and parties.

Older documents can also have the status SENDING or CANCELLED. sajn doesn’t move documents into these statuses, but we recommend that your code accepts them when it reads older documents.

Transitions

The following table lists what moves a document from one status to another:

From	To	Trigger	Webhook event
None	`DRAFT`	Create a document	`document.created`
`DRAFT`	`PENDING`	Send the document.	`document.sent`
`DRAFT`	`PENDING_APPROVAL`	Request approval.	`approval_request.created`
`PENDING_APPROVAL`	`PENDING`	The last required approver approves, and the request has `autoSend` set to `true`.	`approval_request.approved`, `document.sent`
`PENDING_APPROVAL`	`DRAFT`	An approver rejects, or the requester cancels the request.	`approval_request.rejected` or `approval_request.cancelled`
`PENDING`	`COMPLETED`	The last party who must sign signs, and sajn seals the PDF.	`document.fully_signed`, then `document.completed`
`PENDING`	`REJECTED`	A party rejects the document.	`document.rejected`
`PENDING`	`EXPIRED`	The expiration date passes.	`document.expired`
`EXPIRED`	`PENDING`	Change the expiration date.	`document.expiration_extended`
`PENDING`	`DRAFT`	Withdraw the document. sajn removes existing signatures and notifies the parties.	`document.withdrawn`

Sealing runs in the background after the last signature, so a document can stay PENDING for a short time after everyone has signed. document.fully_signed fires when the last party signs, and document.completed fires when the sealed PDF exists. Wait for document.completed, or for status to be COMPLETED, before you download the signed PDF. For the events that fire per party, such as document.party.signed, see Webhook events.

Internal approval

When a document needs internal approval, POST /documents/{id}/send fails with 409 APPROVAL_REQUIRED. A document needs approval when it has approvers, such as the ones its template adds, when the workspace’s approval policy applies, or when your role lacks the SEND_WITHOUT_APPROVAL permission. To submit the draft for approval, call POST /approval-requests with its documentId:

{
  "documentId": "cm4k2x9p10001abcd1234efgh",
  "approverIds": ["cm4k2x9p00000abcd0000mnop"],
  "customMessage": "Please review the payment terms."
}

Leave out approverIds to submit the approvers already on the document, such as the ones its template adds. To find members who can approve, call GET /members?permission=APPROVE_DOCUMENT. The response is the approval request, with its status and each approver’s decision. Approvers act on it with POST /approval-requests/{id}/approve or /reject, and the requester can cancel it. A rejection returns the document to DRAFT, so you can edit it and request approval again. When an approved request has autoSend set to false, the document stays in PENDING_APPROVAL until the requester sends it.

Before you send

sajn refuses to send a document, with the code VALIDATION_FAILED, until it meets the following conditions:

The document has at least one party with the SIGNER role.
The document has an expiration date in the future. If you don’t send expiresAt, sajn uses the workspace’s default expiration, when the workspace has one.
Every party has the contact details its delivery and verification need: an email address for EMAIL delivery or email verification, and a phone number for SMS delivery or SMS verification.

Change a document after sending

A DRAFT document accepts every change. After you send it, what you can change through PATCH /documents/{id} depends on the field:

name, externalId, responsibleUserId, and value can always change.
Reminders, subject, message, and the redirect URL can change until the document is completed, rejected, or cancelled.
forceReadFullDocument, openVerification, and language can change until someone has signed.
signingMode can’t change. Withdraw the document first.

To change the content or settings that are locked, withdraw the document, change it, and send it again.

Document settings

The documentMeta object holds the settings that control signing. The most common are the following:

Field	Description
`subject`, `message`	Subject line and message of the signing invitation.
`signingMode`	`PARALLEL` lets every party sign at once. `SEQUENTIAL` invites parties one at a time, in their `signingOrder`.
`language`	Language of the signing page and emails: `sv`, `en`, `no`, `da`, `fi`, `de`, `is`, `es`, `fr`, or `it`.
`forceReadFullDocument`	If `true`, a party must scroll through the whole document before signing.
`reminderIntervalDays`	Days between automatic reminders, as an integer. `0` turns them off, and `null` uses the default of 3 days.
`redirectUrl`	Where to send a party after signing.
`openVerification`	A verification that every party passes before the document opens, such as `SMS` or `SE_BANKID`. `null` means none.
`value`	The monetary value of the agreement.

For every field, see Create a document.

Document types

The type field sets what kind of document it is:

Type	Description
`SIGNABLE`	The default. Parties sign the document.
`ACCEPTABLE`	Parties accept the document instead of signing it, for example terms of service.
`ARCHIVE_IMPORTED`	An agreement imported from another system for archiving.

Files

A document has up to three files. GET /documents/{id}/files/{type} returns a download URL for one of them, and GET /documents/{id}/files lists every file that’s ready. A file that isn’t ready returns 409 INVALID_STATE:

File type	Contents	Available
`ORIGINAL`	The unsigned document	In every status
`SIGNED`	The sealed PDF, with the signing certificate at the end	When the status is `COMPLETED`
`JOURNAL`	The signing journal, the full event log as a PDF	When the status is `COMPLETED`

For more information, see Downloading signed documents.

Organize documents

The following fields help you find documents and link them to your own systems:

externalId: your own ID for the document, such as a deal or order number. Filter the document list by it with externalId=, which matches the whole value.
Tags: labels such as NDA or Employment. For more information, see Organizing with tags.
Custom fields: structured values such as a project name or cost center. For more information, see Custom fields.

Delete a document

DELETE /documents/{id} moves a document to the trash, in any status, and returns it with deletedAt set. You can restore it from the trash until the workspace’s trash period ends. A workspace can turn on a retention policy that moves completed documents to the trash after a set period, with exemptions per document. To delete a document immediately and permanently, move it to the trash first, and then call POST /documents/{id}/purge. Purging can’t be undone. The verify link in a sealed PDF keeps working after a purge. For more information, see storage and deletion.

Next steps

Parties

Roles, signing order, delivery, and verification.

Content and fields

The content of a document, and the fields parties fill in.

Create a document

Create documents from scratch or from a template.

Webhook events

Every event a document emits.

Get started

Core concepts

Guides

Webhooks

API fundamentals

Upgrading

sajn Login

API reference

Document lifecycle

Statuses

Transitions

Internal approval

Before you send

Change a document after sending

Document settings

Document types

Files

Organize documents

Delete a document

Next steps

Parties

Content and fields

Create a document

Webhook events

​Document lifecycle

​Statuses

​Transitions

​Internal approval

​Before you send

​Change a document after sending

​Document settings

​Document types

​Files

​Organize documents

​Delete a document

​Next steps

Parties

Content and fields

Create a document

Webhook events

Document lifecycle

Statuses

Transitions

Internal approval

Before you send

Change a document after sending

Document settings

Document types

Files

Organize documents

Delete a document

Next steps