Upgrading to 2026-10
Move your integration from API version 2026-09 to 2026-10, with before-and-after examples for the changes that affect most integrations
API version 2026-10 is a clean break from 2026-09. Every list pages the same way, every error has the same shape, every write returns the object it changed, and a webhook delivers the same object the REST API returns. Version 2026-09 keeps working until its sunset date, October 1, 2027. From that date, requests on 2026-09 fail with 400 API_VERSION_SUNSET.
You move one piece at a time, and anything you haven't moved yet stays on 2026-09:
- Find what affects you.
- Send the new version on your requests.
- Move your webhook endpoints.
- Confirm nothing relies on the default.
- Switch the organization default.
For how versions work, see API versioning. For every change in one list, see the changelog.
Upgrade with an AI assistant
To have a coding assistant such as Claude Code, Cursor, or Codex make the changes, give it the following prompt in your repository. The prompt lists every change an integration can hit, and points the assistant at the Markdown version of this guide for the examples:
Show the upgrade prompt
Migrate this codebase's sajn integration from API version 2026-09 to 2026-10.
The guide with before-and-after examples is at
https://www.sajn.se/docs/upgrading/2026-10.md, and the complete changelog is at
https://www.sajn.se/docs/upgrading/changelog.md. Fetch them if you can. The API
reference at https://www.sajn.se/docs is the authority on every request and
response shape.
Find every place this codebase calls the sajn API (https://app.sajn.se/api/v1)
or receives sajn webhooks, and apply every rule below that applies. Keep
behavior the same. Don't guess: if a rule doesn't say how to handle
something, check the reference, and list what you couldn't resolve.
1. VERSION AND GENERAL RULES
- Send "Sajn-Version: 2026-10" on every request, from one shared place such
as the HTTP client. Keep it pinned in code.
- Without the header, an API key request uses the organization default,
and an OAuth access token request uses the OAuth app's own version,
never the organization default.
- Every response property is always present, null when empty. Update types:
optional response fields become "T | null".
- In a PATCH request, an omitted field is unchanged and null clears it.
- Every create returns 200 (POST /forms returned 201).
2. LISTS AND PAGINATION (every list endpoint)
- Request: "limit" (1-100, default 25) and "cursor". "page" and "perPage"
are removed and return 400. Add "include=total" only if you need "total";
"totalPages" is gone.
- Response: { data, hasMore, nextCursor } (+ total with include=total).
Rename the old array keys (documents, contacts, companies, templates,
members, webhooks, sajnIds, chats, events, parties, ...) to "data".
"hasNextPage" is now "hasMore". Loop: pass nextCursor as cursor, keep the
other parameters, stop when hasMore is false.
- Now paginated (they returned everything): GET /folders,
/document-categories, /workspaces, /companies, /documents/{id}/activity,
/documents/{id}/comments. Read every page if you relied on one response.
- Lists bounded by a parent return every item in one response, as
{ data, hasMore: false, nextCursor: null }, and take no limit or cursor:
a document's parties, content, signatures, files, links, reminders and
delegations, GET /documents/{id}/field-values, a template's parties and
content, /roles, /permissions, /helpers/*.
- Default order is createdAt descending everywhere, including
GET /documents (was updatedAt) and GET /forms and /forms/{id}/submissions
(were updatedAt ascending). Pass orderBy and orderDirection to keep an
order you depend on.
- Query values are plain strings, never JSON-encoded: externalId=order-1042,
archived=false. Booleans are true/false; dates are ISO 8601 (no offset =
UTC). Multi-value filters take a comma-separated list or a repeated
parameter. An unknown query parameter returns 400, so remove any the
endpoint doesn't document.
- Filter renames: GET /templates search -> query, createdBy -> createdById;
GET /events since/until -> createdAfter/createdBefore and event -> type;
GET /identity-checks (was /sajn-id) dateFrom/dateTo ->
createdAfter/createdBefore, with no default seven-day window;
GET /blocks scope -> visibility (a sajn-curated block is SHARED) and
locale -> language.
createdBefore and updatedBefore include their boundary.
- Reference filters end in "Id" and take several values (tagId, templateId,
companyId, roleId). "ALL" is no longer a filter value: omit the filter.
Top-level documents and templates: folderId=root (not an empty folderId).
- The GET /documents externalId filter matches the whole value,
case-sensitively; use "query" for a partial match.
3. ERRORS
- Body: { code, message, userMessage, requestId, resource?, issues?,
requiredScopes?, grantedScopes? }. Branch on "code" only, never on the
HTTP status or "message". "message" is English for developers;
"userMessage" is always present and safe to show end users (usually
Swedish), so show it where you showed "message" before. Log "requestId"
(was "errorId"; equals the Sajn-Request-Id response header).
- issues[]: { path, code, message }; code is INVALID_TYPE, INVALID_FORMAT,
INVALID_VALUE, TOO_SMALL, TOO_BIG or UNRECOGNIZED_KEY. VALIDATION_FAILED
always has at least one issue. NOT_FOUND has "resource" (such as
"document"). A path with no endpoint returns ROUTE_NOT_FOUND.
- Code renames: INVALID_REQUEST, INVALID_BODY, VALIDATION_ERROR ->
VALIDATION_FAILED; FORBIDDEN -> PERMISSION_DENIED, INSUFFICIENT_SCOPE,
PLAN_REQUIRED or ACCOUNT_INACTIVE; TOO_MANY_REQUESTS -> RATE_LIMITED;
DUPLICATE_EXTERNAL_ID -> ALREADY_EXISTS;
EXPIRED_CODE -> EXPIRED; RESPONSIBLE_PERSON_REQUIRED, WORKSPACE_REQUIRED ->
ACCOUNT_SETUP_REQUIRED; reused Idempotency-Key -> IDEMPOTENCY_KEY_REUSED
(400) or IDEMPOTENCY_KEY_IN_USE (409).
- Status changes: 401 UNAUTHORIZED now means only a missing, invalid,
expired or revoked token; a valid token without permission gets
403 PERMISSION_DENIED (was 401). State conflicts are 409 INVALID_STATE
(were 400), including editing a non-draft document, editing a locked
template or its content or parties (were 401/403), extending the
expiration of a document that isn't PENDING or EXPIRED, and fetching a
document file that isn't produced yet (was 404). Monthly send limit:
403 LIMIT_EXCEEDED (was 400). Deactivated user: 403 ACCOUNT_INACTIVE (was
401). Duplicate unique value: 409 ALREADY_EXISTS. A failing external
service: 503 UPSTREAM_UNAVAILABLE, retry with backoff (was 500).
4. DOCUMENTS AND PARTIES
- POST /documents returns the full document, the same shape as
GET /documents/{id}: read "id" (not documentId) and parties[].id (not
parties[].signerId). PATCH /documents/{id}, POST .../send, .../withdraw,
.../extend-expiration, POST /documents/{id}/tags and
DELETE /documents/{id}/tags/{tagId} (were { success: true }) also return
the document; DELETE /documents/{id} returns it with deletedAt set.
"content" is null unless ?expand=content (see 6. CONTENT AND FIELDS).
- A document adds deletedAt, templateId, folderId, responsibleUserId and,
on the full document, approvalRequestId. List items in GET /documents
include parties (id, name, email, role, signingStatus, signedAt) and tags.
- Send "parties", never "signers"; role ACCEPTOR is rejected (use SIGNER).
The /documents/{id}/signers endpoints are removed (use .../parties).
- documentMeta.signingOrder (PARALLEL/SEQUENTIAL) -> documentMeta.signingMode;
templateMeta.signingOrder -> templateMeta.signingMode. "signingOrder" now
only means a party's numeric position. Sending the old key returns 400.
- Parties nest the company, on documents and templates alike:
company: { name, orgNumber, role } replaces companyName,
companyOrgNumber and companyRole (responses add company.id, replacing
companyId). company is null for a private individual. This applies to
POST /documents, PATCH /documents/{id}/parties/{partyId},
POST /templates/{id}/parties, PATCH /templates/{id}/parties/{partyId}
and PUT /forms/{id}/template/parties. A request with a flat key returns
400. In a PATCH, null clears phone, externalId, nationalId or a company
key, and company: null clears the company.
- A document party has createdAt, when it was added to the document.
- Party settings, on document parties, template parties, form template
parties and webhooks: deliveryMethod -> delivery, a list of channels:
"EMAIL" -> ["EMAIL"], "SMS" -> ["SMS"], "IN_APP" -> ["IN_APP"],
"NONE" -> []; ["EMAIL", "SMS"] invites by both, and each channel needs
its contact detail. requiredSignature -> signatureMethod (same
values). twoStepVerification -> signVerification (gates signing);
documentMeta.accessVerification and templateMeta.accessVerification ->
openVerification (gates opening). Both verifications drop the
"_BEFORE_SIGNING" suffix (SMS_BEFORE_SIGNING -> SMS, PIN_BEFORE_SIGNING
-> PIN, SE_BANKID_BEFORE_SIGNING -> SE_BANKID, ...) and use null instead
of "NONE". GET /helpers/two-step-verifications returns the plain codes
and no NONE entry. The old keys return 400.
- A document party can have its own openVerification, which overrides
documentMeta.openVerification for that party; null uses the document's.
PIN is rejected there (a PIN only gates signing).
- Party input on POST /documents is one shape: contactId is optional;
name, email, phone, nationalId, externalId, company and country beside
it override the contact's for this document. Without contactId, a party
needs name and an email or phone.
- POST /documents can create and send in one call: parties[].ref (such as
"buyer"), content[] in the shape of POST /documents/{id}/content
(position optional) that names parties by ref in partyId or in
<sajn-field party="buyer">, and send: true. Content is checked before
anything is created: an unknown ref or a duplicate key returns 400. If
the send fails, the document stays a DRAFT and the error message names
its ID.
- GET /documents/{id}/readiness returns { ready, issues: [{ code,
severity: BLOCKER|WARNING, message, userMessage }] }. A send that fails
those checks returns 409 DOCUMENT_NOT_READY with the blockers as an
array of those issues in "readiness" (was a 400 with one joined
message). Codes include
MISSING_EMAIL, MISSING_PHONE, MISSING_ACCESS_VERIFICATION_PHONE,
MISSING_ACCESS_VERIFICATION_EMAIL and DUPLICATE_KEY; new codes can be
added.
- documentMeta.preferredLanguage and templateMeta.preferredLanguage ->
language. Sending preferredLanguage returns 400.
- documentMeta.reminderIntervalDays and templateMeta.reminderIntervalDays
are integers, not strings: 0 turns reminders off, and null uses the
default of 3 days.
- Country codes are ISO 3166-1 alpha-2 everywhere: "SE", not "SWE" (party
country on documents, templates and forms, and GET /helpers/countries).
Map stored alpha-3 values.
- PATCH /documents/{id}/parties/{partyId} on a sent document changes name,
email and phone of a party who hasn't signed; anything else returns
409 INVALID_STATE.
- GET /documents/{id}/parties/{partyId} no longer returns "token"; use
signingUrl.
- Files: GET /documents/{id}/download and
GET /documents/{id}/download/{fileType} are removed. Use
GET /documents/{id}/files/{type} (type ORIGINAL, SIGNED or JOURNAL),
which returns { type, url, expiresAt } (was { downloadUrl }), or
GET /documents/{id}/files for { data: [...] } of every ready file.
- GET /templates/{id}/documents is removed: GET /documents?templateId={id}.
- Reminders: POST /documents/{id}/parties/{partyId}/remind is removed. Use
POST /documents/{id}/reminders with { partyIds: [...], channel? } and read
each party's outcome from results[] (status SENT, SKIPPED or FAILED); a
failure no longer fails the request.
- DELETE /documents/{id}/parties/{partyId}, DELETE /files/{id} and
DELETE /documents/{id}/links/{linkId} return { id, deleted: true }.
POST /documents/{id}/links returns the link like a list item, with
fromDocumentId and toDocumentId.
- POST /files returns the file object (use "id", not "fileId") with
uploadUrl and key. POST /files/{id}/confirm returns the file (no
checksumVerified).
- Sending for approval: see 7. APPROVALS.
5. NAMES AND ENUM VALUES
- ssn -> nationalId (parties, template parties, contacts, identity checks);
ssnDisplayMode -> nationalIdDisplayMode; identity.match.method SSN ->
NATIONAL_ID.
- BANKID -> SE_BANKID (signatureMethod); BANKID_BEFORE_SIGNING ->
SE_BANKID (signVerification, openVerification). Migrate stored values
too.
- customFields[].customInputId -> customFields[].customFieldId on document
create and update; document categories return customFieldIds.
- signerId/signerName/signerEmail -> partyId/partyName/partyEmail
(signatures, reminders); originalSigner(Id)/delegateSigner(Id) ->
originalParty(Id)/delegateParty(Id) (delegations); respondentSignerId ->
respondentPartyId; PUT /forms/{id}/respondent takes { partyId }.
- Closed enums are uppercase: member status ACTIVE/INACTIVE; login session
status PENDING/COMPLETED/FAILED/EXPIRED; form question kind and width,
slot type, publishIssues severity; document link origin;
documentStyle.theme bodyFont, headingFont, density, textSize; block
visibility; on POST /documents, integrationLink.integration HUBSPOT and
integrationLink.type DEAL. Document and identity check statuses spell
CANCELLED.
- Custom field "options" is a string array (["Small","Large"]), not a
JSON-encoded string, in requests and responses.
6. CONTENT AND FIELDS
- The blocks a document or template is built from are "content"; "fields"
means only what a party fills in. Endpoints move:
/documents/{id}/fields -> /documents/{id}/content,
/documents/{id}/fields/{fieldId} -> /documents/{id}/content/{contentId},
.../fields/{fieldId}/placed-fields -> .../content/{contentId}/placed-fields,
and the same for /templates/{id}. PUT /forms/{id}/template/fields ->
PUT /forms/{id}/template/content with { "content": [ ... ] }.
- POST /documents/{id}/content and POST /templates/{id}/content take
{ "content": [ ... ] } (was { "fields": [ ... ] }; in 2026-09 also a
single block), and return the created blocks in "data"; read the
document or template ID from each block. Issue paths start with
"content.".
- Documents, templates, blocks and form templates return their blocks in
"content" (was "fields"); "content" is null unless ?expand=content (was
expand=fields). POST /templates takes "initialContent" (was
"initialFields").
- PATCH .../content/{contentId} takes a block ID only; the "key:" path
prefix is removed. PATCH /documents/{id}/fields (bulk FORM-subfield update
by key) is removed. To find the block that holds a key:
GET .../content?key=KEY. PATCH and the placed-fields endpoints return the
block. DELETE returns { id, deleted: true }. The ignored "key" property on
block create and update bodies is removed.
- Boxes on a PDF (fieldMeta.placedFields, placed-fields "upsert") and
AcroForm fields (fieldMeta.formFields): "page" is counted from 1 (was
0), and "rect" is fractions of the page from 0 to 1, measured from the
top-left corner (was PDF points from the bottom-left corner). To keep
sending points, add 1 to page and set "unit": "POINTS" and
"origin": "BOTTOM_LEFT" on each box. Responses are always fractions
from the top-left, with pageWidth and pageHeight in points; to get
points back: x = rect.x * pageWidth,
y = (1 - rect.y - rect.height) * pageHeight.
- Inline party fields in TEXT and HTML content, in requests and
responses: <sajn-field key="..." party="PARTY_ID" type="TEXT|DATE|SELECT"
label="..." description="..." required="true|false" options="A, B"
value="..."></sajn-field> replaces the editor's
<span class="signer-variable" data-*>. type defaults to TEXT and required
to true; options is comma-separated.
- Fill values only with PATCH /documents/{id}/field-values
{ values: [{ key, value }] }. The response is { results, remaining,
data }: the values are in "data" (was "values"), and there is no
top-level "success": check results[].success; results[].error is null or
{ code: NOT_FOUND|INVALID_STATE|VALIDATION_FAILED, message, userMessage }
(was a Swedish string). GET /documents/{id}/field-values returns "data"
(was "values"), with kind FORM|PDF_ACROFORM|PDF_PLACED|INLINE (INLINE
is a <sajn-field>), filledBy SENDER|SIGNER and partyId (was signerId).
On a DRAFT, a value for a SIGNER field prefills it, and the party can
change it.
- A field key is unique within a document or template. A write that adds
a duplicate returns 400; a document that already has one can't be sent
(409 DOCUMENT_NOT_READY, code DUPLICATE_KEY). One AcroForm field split
across PDF blocks, and one <sajn-field> placed again for the same party,
count as one field.
- Inside fieldMeta (requests and responses, including placed-fields
"upsert", POST /templates initialContent, and blocks): signerId -> partyId,
selectionSignerId -> selectionPartyId, visibilityRule.customInputId ->
visibilityRule.customFieldId; every enum is uppercase: placed box kind
INPUT|STATIC, inputType (SIGNATURE, ...), fillSource (SIGNER, ...),
style.align, FORM subfield type and its fieldMeta type (DATEPICKER, ...),
attachment allowedTypes, AcroForm formFields[].type, TABLE column type,
DURATION durationType and unit, sectionStyle background and padding. An
old name or a lowercase value returns 400.
- Product tables: moms -> vat, pricing.pricesIncludeMoms -> pricesIncludeVat,
defaultMomsRate -> defaultVatRate, showMomsBreakdown -> showVatBreakdown
(also on columns), the VAT column key is "vat", summaryLabels.moms ->
summaryLabels.vat. In productTables on GET /documents/{id} and webhooks:
row moms/lineMoms -> vat/lineVat, totals momsAmount -> vatAmount,
selectionSignerId -> selectionPartyId. Prices stay decimal amounts.
- An uploaded attachment in a FORM subfield's fieldMeta.value is
{ filename, mimeType, size }.
7. APPROVALS
- POST /documents/{id}/send no longer takes approverId and never returns
202. When the caller needs an approval, it returns 409 APPROVAL_REQUIRED.
Request one with POST /approval-requests
{ documentId, approverIds?, customMessage? } (omit approverIds to use the
approvers already on the document); the document is sent when approved.
- GET /approval-requests?documentId=&approverId=&status=,
GET /approval-requests/{id}, POST /approval-requests/{id}/approve
{ comment? }, /reject { comment }, /cancel. Each returns the request:
{ id, documentId, status, autoSend, customMessage, requestedBy,
approvers: [{ user: { id, email, name }, stage, orGroup, status, comment,
resolvedAt }], createdAt, updatedAt }.
- Removed: GET and DELETE /documents/{id}/approval,
POST /documents/{id}/approval/approve and /reject, GET /approvers (use
GET /members?permission=APPROVE_DOCUMENT, which also lists you).
8. MEMBERS, ROLES AND INVITES
- A member is { id, email, name, role: { id, name }, status, lastActiveAt,
joinedAt }; "id" is the user ID (was userId). POST, GET and PATCH
/members return it. No invited, roleId, roleName, workspaceId,
organizationId or addedAt.
- POST /members { email, roleId } only adds an existing organization member
(404 otherwise; no sendInvite). To invite someone new:
POST /member-invites { email, roleId }, which returns the invitation
{ id, email, role, status, invitedBy, createdAt, expiresAt }.
POST /member-invites/{id}/resend returns the invitation.
DELETE /members/{userId} and DELETE /member-invites/{id} return
{ id, deleted: true }.
- /workspace-roles -> /roles; /workspace-permissions -> /permissions;
DELETE /roles/{id} returns { id, deleted: true }.
- GET /me returns "id" (was userId).
- A user reference is { id, email, name } (invitedBy, requestedBy,
identity check createdBy, approvers[].user). Templates, folders and
blocks return createdBy (was createdById); a form returns sender (was
senderUserId); a file's uploadedBy has name (was firstName and
lastName); a reminder's triggeredBy adds id and is null for a reminder
sajn sent automatically.
9. CONTACTS AND COMPANIES
- GET /contacts/search is removed: GET /contacts?email=&phone=&externalId=
(every filter you pass must match; the search matched any one).
- GET /companies/search is removed: GET /companies?orgNumber=&name=.
- GET /companies/lookup?orgNr= -> GET /company-registry/{orgNumber}; read
basic.orgNumber (was basic.orgNr).
- GET /companies/{id} returns the company unwrapped (no { company }) and
without "contacts": GET /contacts?companyId={id}. A company has createdAt
and updatedAt.
- A contact has address fields (addressLine1, addressLine2, postalCode,
city, state, country), settable on create and update, and "company" as
the full company object. postalCode replaces zipCode everywhere,
including GET /organization. In PATCH /contacts/{id}, null clears email,
phone, nationalId, externalId and companyRole.
- DELETE /contacts/{id} and DELETE /custom-fields/{id} return
{ id, deleted: true } (were the deleted object).
10. FORMS, IDENTITY CHECKS, MESSAGES AND LOGIN
- Form "title" -> "name" (responses and PATCH /forms/{id}).
/forms/{id}/document, /document/fields, /document/parties ->
/forms/{id}/template, /template/content, /template/parties.
PATCH /forms/{id}/template returns the template (was { success }).
POST /forms/{id}/unpublish and /rotate-token return the form (were
{ success } and { url }). DELETE /forms/{id} returns
{ id, deleted: true }. publishIssues[] have an English "message" and a
Swedish "userMessage".
- /sajn-id -> /identity-checks. Create takes "language" (ISO 639-1 such as
"sv") instead of "locale", and "nationalId" instead of "ssn". A check has
language, createdBy { id, email, name }, and status CANCELLED (was
CANCELED). The create response no longer returns "token":
verificationUrl carries it. In a list, audits, data and verificationUrl
are null; get one check by ID for audits and data. An empty-string email
or phone returns 400; leave the field out.
- Document chat: /documents/{id}/chat -> /documents/{id}/messages
(GET is a paginated list in "data"). A message's text is "body" (was
"content"), in responses and in POST { body, internal }.
- Messages and comments name their author as
author: { type, id, name, email } (a comment had a separate
authorType). A comment's author is always present; id, name and email
are null for the AI assistant or an author who no longer exists.
- POST /login/sessions returns the full session (same fields as GET, plus
loginUrl and expiresAt). In "claims", a claim your client isn't approved
for is null instead of missing. A session's "method" and the login.*
webhook "method" are SE_BANKID (was BANKID_SE); the "amr" claim keeps
BANKID_SE.
11. MONEY AND LIMITS
- Money is { amount, currency }, amount in minor units (öre for SEK).
GET /limits: balance -> { amount, currency } in the organization's
currency; quota.aiBudgetOre -> quota.aiBudget, remaining.aiBudgetOre ->
remaining.aiBudget, usage.aiSpentOre -> usage.aiSpent,
usage.aiSpentOreSigner -> usage.aiSpentSigner, each { amount, currency:
"SEK" } (an unlimited budget stays null). bankIdSignatures ->
signatures.SE_BANKID. Removed: aiTokens, aiTokensSigner,
quota.additionalBankidCost, quota.smsCost, additionalCosts.
12. WEBHOOKS (only for endpoints you move to 2026-10)
- Managing: webhookUrl -> url, eventTriggers -> events (dotted types).
POST /webhooks { url, events, enabled, apiVersion: "2026-10", secret? }.
A webhook adds status (ENABLED|DISABLED|PAUSED), pausedAt and
pauseReason; resume a paused one with POST /webhooks/{id}/reactivate.
"secret" is returned only by POST /webhooks and
POST /webhooks/{id}/rotate-secret (both secrets sign for 24 hours after a
rotation); PATCH no longer takes "secret". A secret you pass must be
"whsec_" + base64. DELETE /webhooks/{id} returns { id, deleted: true }
(was { success: true }).
- Event types are lowercase and dotted. Mapping: DOCUMENT_X -> document.x
(DOCUMENT_SIGNED -> document.fully_signed; DOCUMENT_ARCHIVE_UPLOADED is
no longer sent, document.created with data.source covers it);
DOCUMENT_PARTY_X -> document.party.x; DOCUMENT_REMINDER_AUTOMATIC and
DOCUMENT_REMINDER_MANUAL -> document.party.reminded with data.trigger
AUTOMATIC|MANUAL; DOCUMENT_MODIFIED -> document.updated; ID_X ->
identity_check.x (ID_CANCELED -> identity_check.cancelled);
SECURITY_X -> security.x, except that the workspace membership events
drop "workspace_": SECURITY_WORKSPACE_MEMBER_REMOVED ->
security.member_removed, SECURITY_WORKSPACE_MEMBER_ROLE_CHANGED ->
security.member_role_changed, SECURITY_WORKSPACE_ROLE_UPDATED ->
security.role_updated (SECURITY_WORKSPACE_RETENTION_UPDATED ->
security.workspace_retention_updated); CONTACT_X,
TEMPLATE_X, FORM_SUBMITTED, WORKSPACE_CREATED, MEMBER_ADDED, LOGIN_X ->
contact.x, template.x, form.submitted, workspace.created, member.added,
login.x. Removed: DOCUMENT_OPENED, DOCUMENT_RECREATED, WORKFLOW_* (use
document.party.opened and document.updated).
- document.completed fires only after sajn seals the signed PDF, also for
a document completed early from the dashboard. Use document.fully_signed
for "every party signed".
- Delivery body: { id, type, createdAt, apiVersion, workspaceId,
environment: PRODUCTION|SANDBOX, actor: { type: USER|API_KEY|OAUTH_APP|
SYSTEM, id } | null, data: { object, ...extras } }. It was { event,
payload, createdAt, webhookEndpoint, apiVersion }. "id" is the event ID
and "createdAt" the event time; both stay the same across retries, so
deduplicate on "id". GET /events and GET /events/{id} return the same
object. An event that no 2026-10 endpoint subscribed to when it happened
has no snapshot: GET /events builds its data.object from the resource's
current state, and leaves the event out (GET /events/{id}: 404) if the
resource no longer exists.
- data.object is the resource as the REST API returns it: a document event
carries GET /documents/{id} without content (was payload, or
payload.document on party events; "title" is now "name"); a party event
adds data.party (as GET /documents/{id}/parties lists it, with nested
company and alpha-2 country); a contact event carries GET /contacts/{id};
template events GET /templates/{id}; member.added GET /members/{userId}
with data.via (uppercase); identity_check.* the check
(identity_check.failed adds data.failureReason). Extras:
document.party.auth_failed adds method (SE_BANKID, ...) and hintCode;
document.party.delegated adds delegation { id, delegate, reason,
delegatedAt }; template.updated and document.expiration_extended have
previousAttributes (replacing changedFields and previousExpiresAt);
document.party.signed and document.completed add fieldValues, the
entries GET /documents/{id}/field-values lists.
Security events: who acted is in "actor"; users are { id, email, name } in
data.object.user and data.object.member; no occurredAt. Payloads never
contain national identity numbers.
- Signatures: Standard Webhooks. The headers webhook-id (the event id),
webhook-timestamp (unix seconds) and webhook-signature replace
X-Sajn-Signature, X-Sajn-Delivery and X-Sajn-Environment; X-Sajn-Secret
is gone. webhook-signature is a space-separated list of "v1,<base64>";
each is HMAC-SHA256 over "<webhook-id>.<webhook-timestamp>.<raw body>"
with key = base64-decode(secret without "whsec_"). Accept if any entry
matches (constant-time compare), and reject old timestamps (for example,
older than 5 minutes). Verify against the raw body, before parsing. A
Standard Webhooks library (npm or PyPI "standardwebhooks") does this.
- Deliveries: GET /webhooks/{id}/deliveries lists deliveries (one event to
one endpoint), each with eventId, type, status SUCCESS|FAILED|PENDING and
attempts[] (with durationMs and headers). Filters: type (was event),
eventId, and status, which filters on the delivery's status instead of
an attempt's.
POST /webhooks/{id}/deliveries/{deliveryId}/retry returns the new
delivery. POST /events/{id}/replay is removed: retry the delivery.
WHEN YOU'RE DONE
- Update types, fixtures, mocks, tests and comments to the new shapes.
- List every change you made, and everything you couldn't migrate with
certainty, such as stored data with old values (BANKID, SWE, signerId,
*_BEFORE_SIGNING, NONE, DOCUMENT_* event names, PDF box coordinates) or
code that assumed one response held a whole list, which a person must
review.
- Also list every loop that polls a document or a list to wait for a status
change. Don't change it: a person replaces it with webhooks, as
https://www.sajn.se/docs/guides/documents/wait-for-signatures.md describes.Review the changes, then run your tests against a sandbox organization with Sajn-Version: 2026-10 before you switch production traffic.
Before you begin
- An API key with access to the workspace you integrate with.
- A test environment, such as a sandbox organization, where you can run your integration against
2026-10.
Find what affects you
Go through What to change in your code, and list each endpoint, field, query parameter, and webhook event your integration uses that a change affects. The changelog has the complete list.
The following changes affect almost every integration:
- Lists return
dataand page by cursor.pageandperPagereturn400. - Errors have one shape, with
codefrom a closed list anduserMessagefor your users. - Writes return the full object.
POST /api/v1/documentsreturns the document with its ID inid. - Parties nest their company, and countries are alpha-2 codes, such as
SE. - Party settings are renamed:
delivery,signatureMethod,signVerification, andopenVerification. - Content blocks move to
/content, and boxes on a PDF are measured in fractions of the page from the top-left corner. - Webhooks deliver an event with a dotted
typeand the REST object indata.object, signed according to Standard Webhooks.
Send the new version on your requests
-
In your test environment, send
Sajn-Version: 2026-10on every request:curl https://app.sajn.se/api/v1/documents \ -H "Authorization: Bearer API_KEY" \ -H "Sajn-Version: 2026-10"Replace
API_KEYwith your API key. -
Update your code for each change that affects it, and run your tests against
2026-10. -
Deploy the change to production.
The header takes precedence over the organization default, so your organization default stays on 2026-09 and other integrations on the same organization aren't affected.
If your integration is an OAuth app, a request without the header uses the app's own version, never the organization default. For more information, see OAuth app version.
We recommend keeping the Sajn-Version header in your code permanently. Your integration then never depends on the organization default.
Move your webhook endpoints
A webhook endpoint keeps its own version, so moving your requests doesn't change your webhook deliveries. A 2026-10 delivery has a new body and new signature headers, so your receiver needs new code for it.
To move an endpoint without dropping events, run a second endpoint next to it:
-
Create a second endpoint for the same URL or a new one, with
"apiVersion": "2026-10"and the same events:curl -X POST https://app.sajn.se/api/v1/webhooks \ -H "Authorization: Bearer API_KEY" \ -H "Sajn-Version: 2026-10" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/sajn-2026-10", "events": ["document.fully_signed", "document.completed"], "enabled": true, "apiVersion": "2026-10" }'Store the
secretfrom the response. Only this response andPOST /api/v1/webhooks/:id/rotate-secretreturn it. -
Verify that your receiver handles the
2026-10deliveries. Each delivery carries its version in theSajn-Versionheader and theapiVersionfield, so a receiver on one URL can tell the two endpoints' deliveries apart. -
Delete the old endpoint with
DELETE /api/v1/webhooks/{id}.
While both endpoints exist, every event is delivered twice, once per version. A 2026-09 delivery has no event id, so make your handler safe to run twice for one event. For example, check the document's current status before you act on it.
If your receiver already accepts both the 2026-09 and the 2026-10 deliveries, you can upgrade the endpoint in place instead. Send {"apiVersion": "2026-10"} in a PATCH /api/v1/webhooks/{id} request. Every delivery after the change uses 2026-10, including retries of earlier events. The endpoint keeps its secret, which Standard Webhooks libraries accept. To get a whsec_ secret, call POST /api/v1/webhooks/{id}/rotate-secret.
Confirm nothing relies on the default
- In the dashboard, go to Inställningar > Utvecklare.
- In the API-version section, check the Anrop de senaste 72 timmarna table. The Vald via column shows whether requests chose their version with the header (Header) or relied on the default (Organisationens standard).
A request from an OAuth app without the header also shows as Organisationens standard, with the app's version. Switching the organization default doesn't change the version that an OAuth app uses.
The table covers only the last 72 hours. If you have jobs that run less often, check the table again after they've run.
If 2026-09 requests from Organisationens standard remain, find the integration that sends them before you continue. Either update it for 2026-10, or make it send Sajn-Version: 2026-09 until you do.
Switch the organization default
In the API-version section, select 2026-10 in the version list, and then click Byt version. Requests without the Sajn-Version header use 2026-10 from then on.
Switching the default doesn't change the version of existing webhook endpoints. A webhook endpoint created through the API without apiVersion gets the version of that request, so Sajn-Version: 2026-10 gives a 2026-10 endpoint.
What to change in your code
Each section shows a 2026-09 request or response, then the same one on 2026-10. Examples are shortened to the fields that matter.
Two rules apply to every endpoint:
- Every response property is always present, and
nullwhen it has no value. In2026-09, many were left out. - In a
PATCHrequest, a field you leave out is unchanged, andnullclears it.
Lists and pagination
Every list returns { data, hasMore, nextCursor } and pages by cursor. page and perPage are removed and return 400 VALIDATION_FAILED.
In 2026-09, each list had its own array key and page numbers:
GET /api/v1/documents?page=2&perPage=50{
"documents": [],
"total": 87,
"totalPages": 2,
"hasNextPage": false,
"nextCursor": null
}In 2026-10, pass limit (1 to 100, default 25) and the previous nextCursor as cursor:
GET /api/v1/documents?limit=50&cursor=NEXT_CURSOR{
"data": [],
"hasMore": false,
"nextCursor": null
}To read every page, keep the other parameters unchanged and stop when hasMore is false:
const listAll = async (path: string, apiKey: string) => {
const items = [];
let cursor: string | null = null;
do {
const url = new URL(`https://app.sajn.se/api/v1/${path}`);
url.searchParams.set('limit', '100');
if (cursor) url.searchParams.set('cursor', cursor);
const res = await fetch(url, {
headers: { Authorization: `Bearer ${apiKey}`, 'Sajn-Version': '2026-10' },
});
const page = await res.json();
items.push(...page.data);
cursor = page.hasMore ? page.nextCursor : null;
} while (cursor);
return items;
};Also change the following:
total: returned only when you passinclude=total.totalPagesis removed.- Lists that returned everything:
GET /api/v1/folders,/document-categories,/workspaces,/companies,/documents/:id/activity, and/documents/:id/commentsare paginated. If you read one response, read every page. - Lists bounded by a parent: a document's parties, content, signatures, files, links, reminders, and delegations,
GET /api/v1/documents/:id/field-values, a template's parties and content,/roles,/permissions, and the/helperslists return every item in one response, as{ data, hasMore: false, nextCursor: null }. They take nolimitorcursor. - Default order: lists sort by
createdAt, newest first.GET /api/v1/documentssorted byupdatedAt, andGET /api/v1/formsand/forms/:id/submissionsbyupdatedAtascending. To keep an order you depend on, passorderByandorderDirection.
Query strings
Send query values as plain strings. In 2026-09, the API JSON-decoded each value, so some clients quoted strings:
GET /api/v1/documents?externalId=%22order-1042%22&archived=falseIn 2026-10, send the value as is. A quoted value matches the quotes literally:
GET /api/v1/documents?externalId=order-1042&archived=falseThe following rules apply to every query parameter:
- Booleans take
trueorfalse. - Dates take an ISO 8601 date, such as
2026-10-01, or a date-time, such as2026-10-01T08:00:00Z. A date-time without an offset is UTC. - Filters that take several values, such as
statusandtagId, take a comma-separated list (status=PENDING,COMPLETED) or a repeated parameter. - An unknown query parameter returns
400 VALIDATION_FAILED, so a misspelled filter fails instead of returning every result. - A filter that references another resource ends in
Idand takes several values:tagId,templateId,companyId,roleId, andcreatedById. ALLis no longer a filter value. To include every value, leave the filter out.- To list top-level documents or templates, pass
folderId=root. - Mutable resources take
createdAfter,createdBefore,updatedAfter, andupdatedBefore. Each includes its boundary.
The following query parameters are renamed:
| Endpoint | 2026-09 | 2026-10 |
|---|---|---|
GET /api/v1/templates | search, createdBy | query, createdById |
GET /api/v1/events | since, until, event | createdAfter, createdBefore, type |
GET /api/v1/identity-checks (was /sajn-id) | dateFrom, dateTo | createdAfter, createdBefore |
GET /api/v1/blocks | scope, locale | visibility, language |
GET /api/v1/identity-checks returns every check when you leave out createdAfter; in 2026-09, it returned only the last seven days. The externalId filter on GET /api/v1/documents matches the whole value, case-sensitively. For a partial match, use query.
Errors
Every error response has the same shape, with code from a closed list. For every code, see Errors.
In 2026-09, a validation error looks like the following:
{
"message": "Invalid email address",
"code": "INVALID_REQUEST",
"issues": [{ "path": "parties.0.email", "message": "Invalid email address" }]
}In 2026-10, the same error looks like the following:
{
"code": "VALIDATION_FAILED",
"message": "Invalid email address",
"userMessage": "Förfrågan innehåller ogiltiga värden.",
"requestId": "req_V1StGXR8Z5jdHi6BmyT2",
"issues": [
{ "path": "parties.0.email", "code": "INVALID_FORMAT", "message": "Invalid email address" }
]
}To update your error handling, do the following:
-
Branch on
code, never on the status ormessage. -
Show your users
userMessage. It's always present, and usually Swedish.messageis English text for developers. -
Log
requestIdinstead oferrorId. It matches theSajn-Request-Idresponse header. -
On
404 NOT_FOUND, readresourcefor the type of the missing resource, such asdocument. A path that matches no endpoint returnsROUTE_NOT_FOUND. -
Map the old codes to the new ones:
2026-09code2026-10codeINVALID_REQUEST,INVALID_BODY,VALIDATION_ERRORVALIDATION_FAILEDFORBIDDENPERMISSION_DENIED,INSUFFICIENT_SCOPE,PLAN_REQUIRED, orACCOUNT_INACTIVETOO_MANY_REQUESTSRATE_LIMITEDDUPLICATE_EXTERNAL_IDALREADY_EXISTSEXPIRED_CODEEXPIREDRESPONSIBLE_PERSON_REQUIRED,WORKSPACE_REQUIREDACCOUNT_SETUP_REQUIREDA reused Idempotency-KeyIDEMPOTENCY_KEY_REUSED(400) orIDEMPOTENCY_KEY_IN_USE(409) -
Expect the following status changes:
Situation 2026-092026-10A valid token that isn't allowed to do something 401403 PERMISSION_DENIEDEditing a document that isn't a draft 400409 INVALID_STATEEditing a locked template, its content, or its parties 401or403409 INVALID_STATEExtending the expiration of a document that isn't PENDINGorEXPIRED400409 INVALID_STATEFetching a document file that isn't produced yet 404409 INVALID_STATESending a document past the monthly limit 400403 LIMIT_EXCEEDEDA token whose user is deactivated 401403 ACCOUNT_INACTIVEA failing external service 500503 UPSTREAM_UNAVAILABLE
401 UNAUTHORIZED means only that the token is missing, invalid, expired, or revoked. A duplicate unique value returns 409 ALREADY_EXISTS. Retry 503 UPSTREAM_UNAVAILABLE with exponential backoff.
Documents and parties
Full objects from writes
Every write returns the object it changed. POST /api/v1/documents returns the document in the same shape as GET /api/v1/documents/:id. Read the document ID from id, and each party ID from parties[].id.
In 2026-09, the response is a summary:
{
"documentId": "cm4k2x9p10001abcd1234efgh",
"externalId": "order-1042",
"parties": [{ "signerId": "cm4k2x9p10002abcd1234efgh", "name": "Alex Berg" }]
}In 2026-10, the response is the document:
{
"id": "cm4k2x9p10001abcd1234efgh",
"name": "Employment contract",
"status": "DRAFT",
"externalId": "order-1042",
"templateId": null,
"folderId": null,
"responsibleUserId": "cm4k2x9p10009abcd1234efgh",
"deletedAt": null,
"documentMeta": { "subject": null, "signingMode": "PARALLEL" },
"parties": [
{
"id": "cm4k2x9p10002abcd1234efgh",
"name": "Alex Berg",
"email": "alex@example.com",
"role": "SIGNER",
"company": null,
"country": "SE",
"signingStatus": "NOT_SIGNED",
"createdAt": "2026-10-01T09:00:00.000Z"
}
],
"tags": [],
"content": null,
"approvalRequestId": null
}content is null unless you pass expand=content. The following endpoints also return the document: PATCH /api/v1/documents/:id, POST /api/v1/documents/:id/send, /withdraw, and /extend-expiration, POST /api/v1/documents/:id/tags, and DELETE /api/v1/documents/:id/tags/:tagId. DELETE /api/v1/documents/:id returns the document with deletedAt set.
Deleting a party, a file, a document link, a contact, a custom field, a member, an invitation, or a role returns { "id": "...", "deleted": true }.
Each document in GET /api/v1/documents includes tags and parties, with each party's id, name, email, role, signingStatus, and signedAt. You can tell who has signed without reading each document.
Parties and companies
A party nests its company in company, on documents and templates alike, and countries use ISO 3166-1 alpha-2 codes everywhere. The PARALLEL or SEQUENTIAL setting is documentMeta.signingMode, so signingOrder only means a party's position.
In 2026-09, a POST /api/v1/documents request looks like the following:
{
"name": "Supplier agreement",
"documentMeta": { "signingOrder": "SEQUENTIAL" },
"parties": [
{
"name": "Alex Berg",
"email": "alex@example.com",
"role": "SIGNER",
"signingOrder": 1,
"companyName": "Example AB",
"companyOrgNumber": "5566778899",
"companyRole": "CEO",
"country": "SWE",
"requiredSignature": "BANKID"
}
]
}In 2026-10:
{
"name": "Supplier agreement",
"documentMeta": { "signingMode": "SEQUENTIAL" },
"parties": [
{
"name": "Alex Berg",
"email": "alex@example.com",
"role": "SIGNER",
"signingOrder": 1,
"company": { "name": "Example AB", "orgNumber": "5566778899", "role": "CEO" },
"country": "SE",
"signatureMethod": "SE_BANKID"
}
]
}A party in a response has company with id, name, orgNumber, and role, or null for a private individual. company.id replaces companyId. A request that sends companyName, companyOrgNumber, companyRole, or documentMeta.signingOrder fails with 400 VALIDATION_FAILED. In a PATCH request to a party, "company": null clears the company.
The same company object applies to template parties, on POST /api/v1/templates/:id/parties, PATCH /api/v1/templates/:id/parties/:partyId, and PUT /api/v1/forms/:id/template/parties, and in their responses.
A document party has createdAt, the time when the party was added to the document. A template party keeps createdAt and updatedAt.
On a sent document, PATCH /api/v1/documents/:id/parties/:partyId changes the name, email, and phone of a party who hasn't signed. Any other property fails with 409 INVALID_STATE.
Party settings
A party's delivery, signature method, and verification have new names, and the verifications take plain method names. In 2026-09, a party and its document look like the following:
{
"documentMeta": { "accessVerification": "SMS_BEFORE_SIGNING" },
"parties": [
{
"name": "Alex Berg",
"email": "alex@example.com",
"role": "SIGNER",
"deliveryMethod": "NONE",
"requiredSignature": "CLICK_TO_SIGN",
"twoStepVerification": "SE_BANKID_BEFORE_SIGNING"
}
]
}In 2026-10:
{
"documentMeta": { "openVerification": "SMS" },
"parties": [
{
"name": "Alex Berg",
"email": "alex@example.com",
"role": "SIGNER",
"delivery": [],
"signatureMethod": "CLICK_TO_SIGN",
"signVerification": "SE_BANKID"
}
]
}The following settings change:
2026-09 | 2026-10 |
|---|---|
deliveryMethod: EMAIL, SMS, IN_APP, or NONE | delivery: ["EMAIL"], ["SMS"], ["IN_APP"], or []. ["EMAIL", "SMS"] invites by both, and each channel needs its contact detail. |
requiredSignature | signatureMethod, with the same values |
twoStepVerification, such as SMS_BEFORE_SIGNING, or NONE | signVerification, such as SMS, or null. It gates signing. |
documentMeta.accessVerification, templateMeta.accessVerification | documentMeta.openVerification, templateMeta.openVerification, with the same values as signVerification. It gates opening the document. |
GET /api/v1/helpers/two-step-verifications codes such as SMS_BEFORE_SIGNING, with a NONE entry | Codes such as SMS, without NONE |
The new names apply to document parties, template parties, form template parties, and webhook payloads. A request with an old key fails with 400 VALIDATION_FAILED. Migrate stored values too, such as a NONE delivery or a verification with the _BEFORE_SIGNING suffix.
A document party can also have its own openVerification. It overrides documentMeta.openVerification for that party, and null uses the document's. It can't be PIN, because a PIN only gates signing.
A party in POST /api/v1/documents has one shape. contactId is optional, and name, email, phone, nationalId, externalId, company, and country beside it override the contact's details for this document. Without a contactId, a party needs a name, and an email or a phone.
Files
GET /api/v1/documents/:id/download/:fileType is removed. In 2026-09:
GET /api/v1/documents/cm4k2x9p10001abcd1234efgh/download/SIGNED{ "downloadUrl": "https://..." }In 2026-10, get one file by type (ORIGINAL, SIGNED, or JOURNAL):
GET /api/v1/documents/cm4k2x9p10001abcd1234efgh/files/SIGNED{ "type": "SIGNED", "url": "https://...", "expiresAt": "2026-10-01T13:00:00.000Z" }To list every file that's ready, call GET /api/v1/documents/:id/files, which returns { data: [...] }. A file that isn't produced yet returns 409 INVALID_STATE instead of 404.
POST /api/v1/files returns the file object, the same as GET /api/v1/files/:id, plus uploadUrl and key. Read the ID from id instead of fileId. POST /api/v1/files/:id/confirm returns the file.
Send and approval
POST /api/v1/documents/:id/send no longer submits a document for approval. When the caller needs an approval first, it returns 409 APPROVAL_REQUIRED, never 202. To request an approval, see Approvals.
When the document isn't ready, such as a party invited by SMS without a phone number, the send returns 409 DOCUMENT_NOT_READY instead of 400 with one joined message. The error's readiness lists every blocker:
{
"code": "DOCUMENT_NOT_READY",
"message": "A party invited by SMS has no phone number.",
"userMessage": "Alex Andersson saknar telefonnummer för SMS-leverans.",
"requestId": "req_V1StGXR8Z5jdHi6BmyT2",
"readiness": [
{
"code": "MISSING_PHONE",
"severity": "BLOCKER",
"message": "A party invited by SMS has no phone number.",
"userMessage": "Alex Andersson saknar telefonnummer för SMS-leverans."
}
]
}To run the same checks without sending, call GET /api/v1/documents/:id/readiness, which returns { ready, issues } with warnings too. Branch on each issue's code and severity, BLOCKER or WARNING; sajn can add codes.
POST /api/v1/documents can also create and send a document in one request. It takes content, the blocks to create, and send: true. A party can have a ref, such as buyer, that the blocks use in place of its ID, in partyId or in a <sajn-field> tag's party. For an example, see Create and send in one request.
Other document changes
2026-09 | 2026-10 |
|---|---|
/api/v1/documents/:id/signers endpoints | /api/v1/documents/:id/parties endpoints |
signers in requests and responses | parties |
Role ACCEPTOR | SIGNER |
POST /api/v1/documents/:id/parties/:partyId/remind | POST /api/v1/documents/:id/reminders with { "partyIds": [...] }, which reports each party's outcome in results |
GET /api/v1/templates/:id/documents | GET /api/v1/documents?templateId= |
token on GET /api/v1/documents/:id/parties/:partyId | signingUrl, which carries it |
ssn, ssnDisplayMode | nationalId, nationalIdDisplayMode |
BANKID, BANKID_BEFORE_SIGNING | SE_BANKID, both as a signature method and as a verification method |
customFields[].customInputId | customFields[].customFieldId |
signerId, signerName, signerEmail on signatures and reminders | partyId, partyName, partyEmail |
originalSigner(Id), delegateSigner(Id) on delegations | originalParty(Id), delegateParty(Id) |
SSN in identity.match.method | NATIONAL_ID |
Custom field options as a JSON-encoded string | A string array, such as ["Small", "Large"] |
documentMeta.preferredLanguage, templateMeta.preferredLanguage | documentMeta.language, templateMeta.language |
reminderIntervalDays as a string, such as "3" | An integer, such as 3. 0 turns reminders off, and null uses the default of 3 days. |
integrationLink with hubspot and deal on POST /api/v1/documents | HUBSPOT and DEAL |
Closed enums are uppercase everywhere, for example member status (ACTIVE), login session status (COMPLETED), form question kind (NAME), document link origin (MANUAL), and documentStyle.theme fonts (OPEN_SANS). Document and identity check statuses spell CANCELLED.
Content and fields
The blocks a document or template is built from, such as text, a PDF, or a form, are its content. A field is only a value that someone fills in. Content has one write path for structure, and fields have one for values.
The content endpoints move from /fields to /content:
2026-09 | 2026-10 |
|---|---|
GET, POST /api/v1/documents/:id/fields | GET, POST /api/v1/documents/:id/content |
GET, PATCH, DELETE /api/v1/documents/:id/fields/:fieldId | GET, PATCH, DELETE /api/v1/documents/:id/content/:contentId |
PATCH /api/v1/documents/:id/fields/:fieldId/placed-fields | PATCH /api/v1/documents/:id/content/:contentId/placed-fields |
The same endpoints on /api/v1/templates/:id/fields | /api/v1/templates/:id/content |
PUT /api/v1/forms/:id/template/fields | PUT /api/v1/forms/:id/template/content |
fields on documents, templates, blocks, and form templates | content |
expand=fields on GET /api/v1/documents/:id and GET /api/v1/templates/:id | expand=content |
initialFields on POST /api/v1/templates | initialContent |
To create content, send { "content": [...] }, also for one block. In 2026-09, the body could be a single block:
{ "type": "TEXT", "position": 0, "fieldMeta": { "type": "TEXT", "content": "<p>Terms</p>" } }In 2026-10:
{
"content": [
{ "type": "TEXT", "position": 0, "fieldMeta": { "type": "TEXT", "content": "<p>Terms</p>" } }
]
}The response has the created blocks in data, each in the shape of GET /api/v1/documents/:id/content/:contentId. The paths in issues start with content. instead of fields..
To fill in a value, use PATCH /api/v1/documents/:id/field-values. In 2026-09, you could address a FORM subfield by key in the field path:
PATCH /api/v1/documents/cm4k2x9p10001abcd1234efgh/fields/key:customer_nameIn 2026-10, the content path takes a block ID only, and values go through field values:
PATCH /api/v1/documents/cm4k2x9p10001abcd1234efgh/field-values{ "values": [{ "key": "customer_name", "value": "Example AB" }] }The response reports each value. In 2026-09, it had a top-level success, and an error was a Swedish string. In 2026-10, each result has success and an error object or null:
{
"results": [
{ "key": "customer_name", "success": true, "error": null }
],
"remaining": [],
"data": []
}A failed result's error is { code, message, userMessage }, with code NOT_FOUND, INVALID_STATE, or VALIDATION_FAILED. The field values are in data instead of values.
Also change the following:
- Removed:
PATCH /api/v1/documents/:id/fields, which updated FORM subfields by key, and thekeyproperty on block create and update requests. To find the block that holds a key, callGET /api/v1/documents/:id/content?key=KEY. - Field values list:
GET /api/v1/documents/:id/field-valuesreturnsdatainstead ofvalues, withpartyIdinstead ofsignerId,kindFORM,PDF_ACROFORM,PDF_PLACED, orINLINEfor a<sajn-field>, andfilledBySENDERorSIGNER. On a draft,PATCHprefills a value withfilledByset toSIGNER, and the party can change it. - Unique keys: a field key names one field within a document or template. A request that adds a second field with the same key fails with
400 VALIDATION_FAILED, and a document that already has a duplicate can't be sent: the send fails with409 DOCUMENT_NOT_READYand the codeDUPLICATE_KEY. One AcroForm field split across PDF blocks, and one<sajn-field>placed again for the same party, count as one field. - Responses:
PATCHon a block and the placed-fields endpoints return the block.DELETEon a block returns{ id, deleted: true }. - Names inside
fieldMeta:signerIdispartyId,selectionSignerIdisselectionPartyId, andvisibilityRule.customInputIdisvisibilityRule.customFieldId. This includesupserton the placed-fields endpoints,initialContentonPOST /api/v1/templates, and blocks. - Enums inside
fieldMeta: every value is uppercase, such askindINPUT,inputTypeSIGNATURE,fillSourceSIGNER,style.alignLEFT, and a FORM subfieldtypesuch asDATEPICKER. A lowercase value fails with400 VALIDATION_FAILED. - VAT in product tables:
momsisvat, andpricesIncludeMoms,defaultMomsRate,showMomsBreakdown, andsummaryLabels.momsarepricesIncludeVat,defaultVatRate,showVatBreakdown, andsummaryLabels.vat. InproductTablesonGET /api/v1/documents/:id, a row'smomsandlineMomsarevatandlineVat, andmomsAmountisvatAmount. Prices stay decimal amounts in the table's currency.
For example, a box in a PDF block's placedFields in 2026-09:
{ "id": "sign-alex", "kind": "input", "inputType": "signature", "fillSource": "signer", "signerId": "cm4k2x9p10002abcd1234efgh" }In 2026-10:
{ "id": "sign-alex", "kind": "INPUT", "inputType": "SIGNATURE", "fillSource": "SIGNER", "partyId": "cm4k2x9p10002abcd1234efgh" }Positions on a PDF
Boxes in placedFields, and the AcroForm fields in formFields, count pages from 1 and measure rect in fractions of the page, from 0 to 1, from the top-left corner. In 2026-09, a signature box near the bottom of the first page of an A4 PDF looks like the following:
{ "id": "sign-alex", "page": 0, "rect": { "x": 72, "y": 96, "width": 200, "height": 48 } }In 2026-10:
{ "id": "sign-alex", "page": 1, "rect": { "x": 0.121, "y": 0.829, "width": 0.336, "height": 0.057 } }To keep sending PDF points from the bottom-left corner, add 1 to page and set unit and origin on each box:
{ "id": "sign-alex", "page": 1, "unit": "POINTS", "origin": "BOTTOM_LEFT", "rect": { "x": 72, "y": 96, "width": 200, "height": 48 } }Responses always give rect in fractions from the top-left corner, with pageWidth and pageHeight in points. To convert back to points from the bottom-left corner, use x = rect.x * pageWidth and y = (1 - rect.y - rect.height) * pageHeight. For the coordinate model, see Place fields on a PDF.
Fields in text
A field that a party fills in inside TEXT or HTML content is a <sajn-field> tag, in responses and requests. In 2026-09, responses returned the editor's internal markup:
<span class="signer-variable" data-id="start-date" data-signer-id="cm4k2x9p10002abcd1234efgh" data-label="Start date" data-field-type="date" data-required="true">Start date</span>In 2026-10:
<sajn-field key="start-date" party="cm4k2x9p10002abcd1234efgh" type="DATE" label="Start date" required="true"></sajn-field>type is TEXT, DATE, or SELECT, and a SELECT field lists its choices in options, separated by commas. For every attribute, see Inline fields in text.
Approvals
Internal approval is its own resource. In 2026-09, you sent the document with an approver:
POST /api/v1/documents/cm4k2x9p10001abcd1234efgh/send{ "approverId": "cm4k2x9p10009abcd1234efgh" }The response was 202 with the document in PENDING_APPROVAL. In 2026-10, request the approval:
POST /api/v1/approval-requests{
"documentId": "cm4k2x9p10001abcd1234efgh",
"approverIds": ["cm4k2x9p10009abcd1234efgh"]
}To use the approvers already on the document, leave out approverIds. The response is the request:
{
"id": "cm4k2x9p10007abcd1234efgh",
"documentId": "cm4k2x9p10001abcd1234efgh",
"status": "PENDING",
"autoSend": true,
"customMessage": null,
"requestedBy": { "id": "cm4k2x9p10008abcd1234efgh", "email": "quinn@example.com", "name": "Quinn Ek" },
"approvers": [
{
"user": { "id": "cm4k2x9p10009abcd1234efgh", "email": "kai@example.com", "name": "Kai Lund" },
"stage": 1,
"orGroup": null,
"status": "PENDING",
"comment": null,
"resolvedAt": null
}
],
"createdAt": "2026-10-01T09:00:00.000Z",
"updatedAt": "2026-10-01T09:00:00.000Z"
}The following endpoints replace the old ones. Each action returns the request:
2026-09 | 2026-10 |
|---|---|
POST /api/v1/documents/:id/send with approverId | POST /api/v1/approval-requests |
GET /api/v1/documents/:id/approval | GET /api/v1/approval-requests?documentId=, or GET /api/v1/approval-requests/:id |
POST /api/v1/documents/:id/approval/approve | POST /api/v1/approval-requests/:id/approve, with an optional comment |
POST /api/v1/documents/:id/approval/reject | POST /api/v1/approval-requests/:id/reject, with a required comment |
DELETE /api/v1/documents/:id/approval | POST /api/v1/approval-requests/:id/cancel |
GET /api/v1/approvers | GET /api/v1/members?permission=APPROVE_DOCUMENT, which also lists you |
GET /api/v1/approval-requests filters by documentId, approverId, and status. A document has approvalRequestId, and the webhook events approval_request.created, approval_request.approved, approval_request.rejected, and approval_request.cancelled report changes.
Members, roles, and invites
A member has one shape everywhere, with the user ID in id. Adding a member and inviting someone are separate endpoints.
In 2026-09, POST /api/v1/members with sendInvite invited someone new:
{ "email": "kai@example.com", "roleId": "cm4k2x9p10005abcd1234efgh", "sendInvite": true }The response had userId, roleId, roleName, invited, and addedAt. In 2026-10, POST /api/v1/members only adds someone who is already in the organization, and returns 404 for any other email address. To invite someone new, call POST /api/v1/member-invites:
{ "email": "kai@example.com", "roleId": "cm4k2x9p10005abcd1234efgh" }The response is the invitation:
{
"id": "cm4k2x9p10006abcd1234efgh",
"email": "kai@example.com",
"role": { "id": "cm4k2x9p10005abcd1234efgh", "name": "Member" },
"status": "PENDING",
"invitedBy": { "id": "cm4k2x9p10008abcd1234efgh", "email": "quinn@example.com", "name": "Quinn Ek" },
"createdAt": "2026-10-01T09:00:00.000Z",
"expiresAt": "2026-10-08T09:00:00.000Z"
}Also change the following:
-
Member shape:
POST,GET, andPATCHon/api/v1/membersreturn{ id, email, name, role, status, lastActiveAt, joinedAt }, whereroleis{ id, name }andstatusisACTIVEorINACTIVE. -
Renamed endpoints:
/api/v1/workspace-rolesis/api/v1/roles, and/api/v1/workspace-permissionsis/api/v1/permissions. -
Resend:
POST /api/v1/member-invites/:id/resendreturns the invitation instead of{ success: true }. -
GET /api/v1/me: returns the user ID asidinstead ofuserId. -
User references: a user is
{ id, email, name }, such asinvitedBy,requestedBy, and an identity check'screatedBy. The following references change shape:2026-092026-10createdByIdon templates, folders, and blockscreatedBysenderUserIdon formssenderuploadedByon files, withfirstNameandlastNameuploadedBy, withnametriggeredByon reminders, with a nullnameandemailfor an automatic remindertriggeredBywithid, ornullfor an automatic reminder
Contacts and companies
The search endpoints fold into the lists, where every filter you pass must match. In 2026-09, a search matched any one filter:
GET /api/v1/contacts/search?email=alex@example.com
GET /api/v1/companies/search?orgNumber=5566778899
GET /api/v1/companies/lookup?orgNr=5566778899In 2026-10:
GET /api/v1/contacts?email=alex@example.com
GET /api/v1/companies?orgNumber=5566778899
GET /api/v1/company-registry/5566778899GET /api/v1/contacts filters by email, phone, externalId, companyId, tagId, and query. GET /api/v1/companies filters by orgNumber, name, and query. The company registry returns basic.orgNumber instead of basic.orgNr.
Also change the following:
GET /api/v1/companies/:id: returns the company without the{ company }wrapper, and withoutcontacts. To list a company's contacts, callGET /api/v1/contacts?companyId=.- Contact address: a contact has
addressLine1,addressLine2,postalCode,city,state, andcountry, which you can set when you create or update it.postalCodereplaceszipCode, also onGET /api/v1/organization. - Contact company: a contact's
companyis the full company object, withcreatedAtandupdatedAt. - Clearing values: in
PATCH /api/v1/contacts/:id,nullclearsemail,phone,nationalId,externalId, andcompanyRole.
Forms, identity checks, and messages
The following resources move or rename:
2026-09 | 2026-10 |
|---|---|
/api/v1/sajn-id | /api/v1/identity-checks |
locale on an identity check, such as sv-SE | language, an ISO 639-1 code such as sv |
Identity check status CANCELED | CANCELLED |
/api/v1/documents/:id/chat | /api/v1/documents/:id/messages |
Form title | name |
/api/v1/forms/:id/document, /document/fields, /document/parties | /api/v1/forms/:id/template, /template/content, /template/parties |
For example, creating an identity check in 2026-09:
POST /api/v1/sajn-id{ "fullName": "Alex Berg", "email": "alex@example.com", "channel": "EMAIL", "locale": "sv-SE", "ssn": "199001011234" }In 2026-10:
POST /api/v1/identity-checks{ "fullName": "Alex Berg", "email": "alex@example.com", "channel": "EMAIL", "language": "sv", "nationalId": "199001011234" }Also change the following:
- Identity check token: the create response no longer returns
token.verificationUrlcarries it. - Identity check lists: items have the same fields as a check you get by ID, with
audits,data, andverificationUrlset tonull.createdByis{ id, email, name }. - Empty contact details: a create request that sets
emailorphoneto an empty string fails with400 VALIDATION_FAILED. Leave the field out instead. - Form responses:
POST /api/v1/forms/:id/unpublishand/rotate-tokenreturn the form,PATCH /api/v1/forms/:id/templatereturns the template, andDELETE /api/v1/forms/:idreturns{ id, deleted: true }.POST /api/v1/formsreturns200instead of201. - Form publish issues:
publishIssues[].messageis English, and the Swedish text is inuserMessage. - Messages and comments: a message's text is
bodyinstead ofcontent, in responses and inPOST /api/v1/documents/:id/messages. Messages and comments name their author asauthor: { type, id, name, email }, instead of a comment's separateauthorType. A comment'sauthoris always present, and itsid,name, andemailarenullfor the AI assistant or an author who no longer exists. - Login sessions:
POST /api/v1/login/sessionsreturns the session with the same fields asGET /api/v1/login/sessions/:id, plusloginUrlandexpiresAt. Inclaims, a claim your client isn't approved for isnull. A session'smethodisSE_BANKIDinstead ofBANKID_SE, and so ismethodinlogin.*webhook events. Theamrclaim keepsBANKID_SE.
Money and limits
Every amount of money is { amount, currency }, with amount in the currency's minor unit, such as öre for SEK. In 2026-09, GET /api/v1/limits looks like the following:
{
"balance": 125000,
"quota": { "aiBudgetOre": 50000, "bankIdSignatures": 100, "smsCost": 0 },
"usage": { "aiSpentOre": 1200, "aiTokens": 1200 }
}In 2026-10:
{
"balance": { "amount": 125000, "currency": "SEK" },
"quota": { "aiBudget": { "amount": 50000, "currency": "SEK" }, "signatures": { "SE_BANKID": 100 } },
"usage": { "aiSpent": { "amount": 1200, "currency": "SEK" } }
}balance is in the organization's currency, and the AI budget fields are always in SEK. An unlimited AI budget is null. bankIdSignatures is signatures.SE_BANKID. The aiTokens aliases and the cost fields quota.additionalBankidCost, quota.smsCost, and additionalCosts, which always returned 0, are removed.
Webhooks
The following changes apply to webhook endpoints on 2026-10. For the full event catalog, see Events.
Manage endpoints
2026-09 | 2026-10 |
|---|---|
webhookUrl | url |
eventTriggers, such as DOCUMENT_SIGNED | events, such as document.fully_signed |
secret in PATCH /api/v1/webhooks/:id | POST /api/v1/webhooks/:id/rotate-secret, which signs with both secrets for 24 hours |
GET /api/v1/webhooks/:id/deliveries lists attempts | Lists deliveries, each with its attempts, eventId, and type |
event filter on deliveries, and status on an attempt's status | type and eventId filters, and status on the delivery's status |
DELETE /api/v1/webhooks/:id returns { success: true } | Returns { id, deleted: true } |
POST /api/v1/events/:id/replay | POST /api/v1/webhooks/:id/deliveries/:deliveryId/retry, which returns the new delivery |
A webhook has status (ENABLED, DISABLED, or PAUSED), pausedAt, and pauseReason. To resume a paused webhook, call POST /api/v1/webhooks/:id/reactivate. The secret is returned only when you create the webhook or rotate its secret. A secret you pass on create must be a Standard Webhooks secret: whsec_ followed by base64.
Event types
Event types are lowercase and dotted. Most names follow from the old ones, such as DOCUMENT_PARTY_SIGNED to document.party.signed and CONTACT_CREATED to contact.created. The following change more:
2026-09 | 2026-10 |
|---|---|
DOCUMENT_SIGNED | document.fully_signed |
DOCUMENT_ARCHIVE_UPLOADED | document.created, with data.source |
DOCUMENT_REMINDER_AUTOMATIC, DOCUMENT_REMINDER_MANUAL | document.party.reminded, with data.trigger set to AUTOMATIC or MANUAL |
ID_CREATED, ID_VERIFIED, and the other ID_* events | identity_check.created, identity_check.verified, and the matching identity_check.* events |
ID_CANCELED | identity_check.cancelled |
SECURITY_DOCUMENT_DOWNLOADED and the other SECURITY_* events | security.document_downloaded and the matching security.* events |
DOCUMENT_MODIFIED | document.updated |
SECURITY_WORKSPACE_MEMBER_REMOVED, SECURITY_WORKSPACE_MEMBER_ROLE_CHANGED, SECURITY_WORKSPACE_ROLE_UPDATED | security.member_removed, security.member_role_changed, security.role_updated |
DOCUMENT_OPENED, DOCUMENT_RECREATED, WORKFLOW_* | Removed. Use document.party.opened and document.updated. |
document.completed means that the sealed, signed PDF is ready. It fires after sajn seals the PDF, also for a document that a member completes early in the dashboard. To act when every party has signed, before sealing, subscribe to document.fully_signed.
Envelope
A delivery is the event itself, the same object that GET /api/v1/events/:id returns. In 2026-09, a delivery looks like the following:
{
"event": "DOCUMENT_PARTY_SIGNED",
"payload": {
"document": { "id": "cm4k2x9p10001abcd1234efgh", "title": "Employment contract" },
"party": { "id": "cm4k2x9p10002abcd1234efgh", "name": "Alex Berg" }
},
"createdAt": "2026-10-01T12:00:04.512Z",
"webhookEndpoint": "https://example.com/webhooks/sajn",
"apiVersion": "2026-09"
}In 2026-10:
{
"id": "cm4k2x9p10003abcd1234efgh",
"type": "document.party.signed",
"createdAt": "2026-10-01T12:00:00.000Z",
"apiVersion": "2026-10",
"workspaceId": "cm4k2x9p10004abcd1234efgh",
"environment": "PRODUCTION",
"actor": null,
"data": {
"object": { "id": "cm4k2x9p10001abcd1234efgh", "name": "Employment contract", "status": "PENDING" },
"party": { "id": "cm4k2x9p10002abcd1234efgh", "name": "Alex Berg", "company": null, "country": "SE" }
}
}To update your receiver, do the following:
- Switch on
typeinstead ofevent. - Read the resource from
data.object. It's the object the REST API returns, withoutexpand: a document event carries the document asGET /api/v1/documents/:idreturns it, and a party event addsdata.party. - Deduplicate on
id. It's the event ID, and it stays the same across retries, as doescreatedAt, which is when the event happened. - When you read past events from
GET /api/v1/events, expectdata.objectto show the resource's current state for an event that no2026-10endpoint subscribed to when it happened. If that resource no longer exists, the list leaves the event out. - Read who caused the event from
actor:{ type, id }, withtypeUSER,API_KEY,OAUTH_APP, orSYSTEM, ornull. - Read earlier values from
data.previousAttributesontemplate.updatedanddocument.expiration_extended, instead ofchangedFieldsandpreviousExpiresAt. - Read what the parties filled in from
data.fieldValuesondocument.party.signedanddocument.completed, in the shape ofGET /api/v1/documents/:id/field-values.
For each event's data, see Payloads.
Signatures
Deliveries are signed according to Standard Webhooks. The webhook-id, webhook-timestamp, and webhook-signature headers replace X-Sajn-Signature, X-Sajn-Delivery, and X-Sajn-Environment, and X-Sajn-Secret isn't sent. webhook-id is the event id.
To verify a delivery, use a Standard Webhooks library with your endpoint's secret, or the following code. Pass it the raw request body, before you parse it:
import { createHmac, timingSafeEqual } from 'node:crypto';
const verifySajnWebhook = (rawBody: string, headers: Headers, secret: string) => {
const id = headers.get('webhook-id');
const timestamp = headers.get('webhook-timestamp');
const signatures = headers.get('webhook-signature');
if (!id || !timestamp || !signatures) return false;
// Reject deliveries older than five minutes.
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest();
// During a secret rotation, the header lists one signature per secret.
return signatures.split(' ').some((entry) => {
const [version, signature] = entry.split(',');
const received = Buffer.from(signature ?? '', 'base64');
return version === 'v1' && received.length === expected.length && timingSafeEqual(received, expected);
});
};For more information, see Verify signatures.
Was this page helpful?
Last updated on