Documents
What a document is made of, and every status it passes through from draft to sealed PDF
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 indocumentMeta.
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:
stateDiagram-v2
[*] --> DRAFT: create
DRAFT --> PENDING: send
DRAFT --> PENDING_APPROVAL: request approval
PENDING_APPROVAL --> PENDING: approvers approve
PENDING_APPROVAL --> DRAFT: approver rejects, or request cancelled
PENDING --> COMPLETED: last signer signs, PDF sealed
PENDING --> REJECTED: a party rejects
PENDING --> EXPIRED: expiration date passes
EXPIRED --> PENDING: expiration date moved
PENDING --> DRAFT: withdraw
COMPLETED --> [*]
REJECTED --> [*]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. Download the signed PDF when document.completed arrives, or when a document that you read for another reason has status set to COMPLETED. Don't poll the document to find out. For the pattern, see Wait for signatures.
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
SIGNERrole. - 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
EMAILdelivery or email verification, and a phone number forSMSdelivery 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, andvaluecan always change.- Reminders, message, and the redirect URL can change until the document is completed, rejected, or cancelled.
forceReadFullDocument,openVerification, andlanguagecan change until someone has signed.signingModecan'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 |
|---|---|
message | 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. Don't retry it in a loop: request SIGNED and JOURNAL when document.completed arrives. The files are available as follows:
| 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 withexternalId=, which matches the whole value.- Tags: labels such as
NDAorEmployment. 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
Was this page helpful?
Last updated on