Skip to main content
In this guide, you create a draft document through the API. You add the parties who sign it, set the invitation and signing settings, and fill in custom field values. The document stays a 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_KEY environment variable. Every example on this page reads it from there:
    Replace API_KEY with your API key.
Every request sends the 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 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:
The response is the full document, in the same shape as Get a document by ID. content is null unless you pass expand=content. The following example leaves out documentMeta and some party fields:
Store the document 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 documentMeta. Set the deadline in expiresAt. You can send these fields when you create the document, or later with a PATCH request:
Replace DOCUMENT_ID with the document id from the previous step.The most-used documentMeta fields are the following:
  • signingMode: PARALLEL invites every party at once. SEQUENTIAL invites them one at a time, in the order of each party’s signingOrder. For more information, see Multi-party signing.
  • reminderIntervalDays: the number of days between automatic reminders, as an integer. 0 turns them off, and null uses the default of 3 days. For more information, see Reminders and expiration.
  • language: the language of the emails and the signing page, such as sv or en.
  • redirectUrl and redirectEnabled: 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.
For every field, see Create a new document.
3

Fill in custom field values

To set the workspace’s custom fields on the document, send customFields with each field’s customFieldId and value. To find the IDs, call List all custom fields:
Replace 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 PDF field. 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.
The document is ready to send. Continue with Send a document for signing.

Create and send in one request

To create a document with its content and send it in one request, add content and send to the POST /api/v1/documents request:
  • content takes content blocks in the same shape as Create document content. position is optional; by default, each block follows the blocks before it, including any that the template adds.
  • Give a party a ref, such as buyer. A block names the party by its ref wherever it takes a party ID: in partyId inside fieldMeta, or in the party attribute of a <sajn-field> tag.
  • fieldValues fills in values by key, in the same shape as values in Fill in values on a document. sajn writes them after parties and content, and before send.
  • send: true sends the document after sajn creates it, the same way as Send a document for signing.
The following request creates a one-page agreement in which the buyer fills in a delivery address, and sends it:
The response is the document with the status 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 a templateId. 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.
Replace 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 a templatePartyId: 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:
A party with 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 a company 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 on code:
  • 400 VALIDATION_FAILED: the body is invalid, for example a party without contactId that has no name, or neither an email nor a phone, a company with name but no orgNumber, or a flat key such as companyName. The issues array lists each problem with its path, such as parties.0.email.
  • 404 NOT_FOUND: a contactId or the templateId doesn’t exist in the workspace.
  • 429 RATE_LIMITED: wait the number of seconds in the Retry-After header, and then retry.
To retry a 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.