DRAFT until you send it for signing.
Before you begin
- Create an API key. In the sajn app, go to workspace settings, then Utvecklare (Developer) > API-nycklar (API keys).
-
Store the key in the
SAJN_API_KEYenvironment variable. Every example on this page reads it from there:ReplaceAPI_KEYwith your API key.
Sajn-Version: 2026-10 header, so the examples behave the same no matter what your organization’s default version is. For more information, see API versioning.
Create the document
1
Create a draft with its parties
Send a The response is the full document, in the same shape as Get a document by ID. Store the document
POST request to /api/v1/documents with a name and the parties who take part. Each party is an existing contact, referenced by contactId, or a person given by name and an email or a phone. Details you send beside a contactId, such as email or nationalId, override the contact’s for this document:content is null unless you pass expand=content. The following example leaves out documentMeta and some party fields:id and each party id. The other document and party endpoints take them as path parameters.If you leave out expiresAt, the document gets the workspace’s default expiration, if the workspace has one. If you leave out signatureMethod, the party gets the workspace’s default signing method.2
Configure the invitation and signing settings
Set the invitation message, the signing order, and the automatic reminders in Replace
documentMeta. Set the deadline in expiresAt. You can send these fields when you create the document, or later with a PATCH request:DOCUMENT_ID with the document id from the previous step.The most-used documentMeta fields are the following:signingMode:PARALLELinvites every party at once.SEQUENTIALinvites them one at a time, in the order of each party’ssigningOrder. For more information, see Multi-party signing.reminderIntervalDays: the number of days between automatic reminders, as an integer.0turns them off, andnulluses the default of 3 days. For more information, see Reminders and expiration.language: the language of the emails and the signing page, such assvoren.redirectUrlandredirectEnabled: where to send a party after signing. For more information, see Redirect after signing.internalRecipients: up to five email addresses that get a copy of the sealed PDF when the document is completed.
3
Fill in custom field values
To set the workspace’s custom fields on the document, send Replace
customFields with each field’s customFieldId and value. To find the IDs, call List all custom fields:DOCUMENT_ID with the document ID. The response’s customFields array lists every value on the document. For more information, see Custom fields.4
Add the content
A document created without a template has no content. Add it in one of the following ways:
- Upload a PDF file and attach it as a
PDFfield. For more information, see Upload files. - Add text and HTML content. For more information, see HTML content.
- Create the document from a template that already has content, as described in the following section.
Create and send in one request
To create a document with its content and send it in one request, addcontent and send to the POST /api/v1/documents request:
contenttakes content blocks in the same shape as Create document content.positionis optional; by default, each block follows the blocks before it, including any that the template adds.- Give a party a
ref, such asbuyer. A block names the party by itsrefwherever it takes a party ID: inpartyIdinsidefieldMeta, or in thepartyattribute of a<sajn-field>tag. fieldValuesfills in values bykey, in the same shape asvaluesin Fill in values on a document. sajn writes them afterpartiesandcontent, and beforesend.send: truesends the document after sajn creates it, the same way as Send a document for signing.
PENDING. In the stored content, each ref is replaced by the party’s ID.
sajn checks the content before it creates anything. A ref that no party has, or a field key that two fields use, fails with 400 VALIDATION_FAILED and creates nothing. If the document is created but the send fails, for example because it isn’t ready, the document stays a DRAFT, and the error message names its ID. Fix the problem, and then send the draft with POST /api/v1/documents/DOCUMENT_ID/send.
Create a document from a template
To reuse content and parties, pass atemplateId. The new document copies the template’s content, parties, and settings.
If you also send parties, they replace the template’s parties, and signature and initials boxes placed on a PDF for the template’s parties are removed. To keep the template’s parties and their boxes, name a template party in templatePartyId, as described in the following section.
TEMPLATE_ID with the ID of a template from List all templates.
Fill in a template’s parties
A template’s parties often have signature boxes placed on its PDF. To fill in such a party, give it atemplatePartyId: the ID of a party in the template’s parties, from Get a template. The document’s copy of that party keeps its boxes and settings, and the details you send replace its own.
When one party names a templatePartyId, the template’s other parties are kept too, and a party without templatePartyId is added as a new party:
templatePartyId needs no name or email: it keeps the template party’s details unless you send new ones. An ID that isn’t a party of the template fails with 400 VALIDATION_FAILED, and sajn creates nothing.
fieldValues fills in the template’s values by key. To see a document’s keys, call GET /api/v1/documents/DOCUMENT_ID/field-values. You can also fill in values after you create the document, with Fill in values on a document.
Add a company party
A party with acompany is a COMPANY party, which signs on behalf of the company. Set the company’s name and orgNumber together, and optionally the party’s role at the company. Leave out company for a private individual:
country is an ISO 3166-1 alpha-2 code, such as SE. The response returns the company as company, with id, name, orgNumber, and role, and company is null for a private individual.
To deliver the invitation by SMS, send the party’s phone with "delivery": ["SMS"], or "delivery": ["EMAIL", "SMS"] to send both. Each channel needs its contact detail: an email address for EMAIL, and a phone number for SMS.
Handle errors
Errors have the same shape on every endpoint. Branch oncode:
400 VALIDATION_FAILED: the body is invalid, for example a party withoutcontactIdthat has noname, or neither anemailnor aphone, acompanywithnamebut noorgNumber, or a flat key such ascompanyName. Theissuesarray lists each problem with itspath, such asparties.0.email.404 NOT_FOUND: acontactIdor thetemplateIddoesn’t exist in the workspace.429 RATE_LIMITED: wait the number of seconds in theRetry-Afterheader, and then retry.
POST request safely, send the same Idempotency-Key header on every attempt. For more information, see Errors and Idempotency.
Next steps
Send for signing
Send the draft and track each party’s progress.
Upload files
Attach a PDF file as the document’s content.
Set the signing method
Choose BankID, eID, drawn, or click-to-sign for each party.
Create a new document
See every request field in the API reference.

