Multi-party signing

In this guide, you create a document that several parties sign. You choose whether they sign in parallel, in a fixed sequence, or in groups, and you track each party until the document is completed.

Before you begin

Store your API key in the SAJN_API_KEY environment variable. To create a key, go to workspace settings in the sajn app, then Utvecklare (Developer) > API-nycklar (API keys).
Read Create a document for the basics of creating a draft.

Choose a signing order

The document’s documentMeta.signingMode decides when each party is invited, and each party’s signingOrder sets its position in a sequence:

PARALLEL: every party is invited when you send the document and can sign in any order. This is the fastest option, and we recommend it when the order doesn’t matter.
SEQUENTIAL: parties are invited in ascending signingOrder. Parties with the same signingOrder form a group: they’re invited together, and the next group is invited when everyone in the group has signed.

With SEQUENTIAL, a party hears nothing until it’s their turn. In the sajn app, a party who is waiting shows as Väntar på tur (Waiting for turn).

Create a document with a signing sequence

Create the document with ordered parties

The following request creates a partnership agreement. The two people from Example AB sign first, at the same time. When both have signed, the two people from Sample Oy are invited:

curl -X POST https://app.sajn.se/api/v1/documents \
  -H "Authorization: Bearer $SAJN_API_KEY" \
  -H "Sajn-Version: 2026-10" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Partnership agreement",
    "templateId": "TEMPLATE_ID",
    "documentMeta": { "signingMode": "SEQUENTIAL" },
    "parties": [
      { "name": "Alex Andersson", "email": "[email protected]", "role": "SIGNER", "signingOrder": 1 },
      { "name": "Kai Berg", "email": "[email protected]", "role": "SIGNER", "signingOrder": 1 },
      { "name": "Quinn Virtanen", "email": "[email protected]", "role": "SIGNER", "signingOrder": 2 },
      { "name": "Robin Laine", "email": "[email protected]", "role": "SIGNER", "signingOrder": 2 }
    ]
  }'

const response = await fetch("https://app.sajn.se/api/v1/documents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SAJN_API_KEY}`,
    "Sajn-Version": "2026-10",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Partnership agreement",
    templateId: "TEMPLATE_ID",
    documentMeta: { signingMode: "SEQUENTIAL" },
    parties: [
      { name: "Alex Andersson", email: "[email protected]", role: "SIGNER", signingOrder: 1 },
      { name: "Kai Berg", email: "[email protected]", role: "SIGNER", signingOrder: 1 },
      { name: "Quinn Virtanen", email: "[email protected]", role: "SIGNER", signingOrder: 2 },
      { name: "Robin Laine", email: "[email protected]", role: "SIGNER", signingOrder: 2 },
    ],
  }),
});
const document = await response.json();
console.log(document.id);

import os

import requests

response = requests.post(
    "https://app.sajn.se/api/v1/documents",
    headers={
        "Authorization": f"Bearer {os.environ['SAJN_API_KEY']}",
        "Sajn-Version": "2026-10",
    },
    json={
        "name": "Partnership agreement",
        "templateId": "TEMPLATE_ID",
        "documentMeta": {"signingMode": "SEQUENTIAL"},
        "parties": [
            {"name": "Alex Andersson", "email": "[email protected]", "role": "SIGNER", "signingOrder": 1},
            {"name": "Kai Berg", "email": "[email protected]", "role": "SIGNER", "signingOrder": 1},
            {"name": "Quinn Virtanen", "email": "[email protected]", "role": "SIGNER", "signingOrder": 2},
            {"name": "Robin Laine", "email": "[email protected]", "role": "SIGNER", "signingOrder": 2},
        ],
    },
)
response.raise_for_status()
print(response.json()["id"])

Replace TEMPLATE_ID with the ID of a template that holds the agreement’s content. The response is the document, with one entry in parties for each party.

Send the document

Send the document as usual:

curl -X POST https://app.sajn.se/api/v1/documents/DOCUMENT_ID/send \
  -H "Authorization: Bearer $SAJN_API_KEY" \
  -H "Sajn-Version: 2026-10" \
  -H "Content-Type: application/json" \
  -d '{}'

Replace DOCUMENT_ID with the document id. Only the parties with signingOrder 1 are invited.

Track the parties

Each signature fires a document.party.signed webhook event. The event has the whole document in data.object and the party who signed in data.party:

{
  "id": "cm4k2xh1w0009abcd4680klmn",
  "type": "document.party.signed",
  "createdAt": "2026-10-02T10:30:00.000Z",
  "apiVersion": "2026-10",
  "workspaceId": "cm4k2x7c00000abcd0000wxyz",
  "environment": "PRODUCTION",
  "actor": null,
  "data": {
    "object": {
      "id": "cm4k2x9p10001abcd1234efgh",
      "name": "Partnership agreement",
      "status": "PENDING",
      "parties": [
        { "id": "cm4k2xa3f0002abcd5678ijkl", "name": "Alex Andersson", "role": "SIGNER", "signingStatus": "SIGNED" },
        { "id": "cm4k2xa3f0003abcd5678ijkl", "name": "Kai Berg", "role": "SIGNER", "signingStatus": "NOT_SIGNED" }
      ]
    },
    "party": {
      "id": "cm4k2xa3f0002abcd5678ijkl",
      "name": "Alex Andersson",
      "email": "[email protected]",
      "externalId": null,
      "role": "SIGNER",
      "signingStatus": "SIGNED",
      "signedAt": "2026-10-02T10:30:00.000Z"
    }
  }
}

The example leaves out some document and party fields. To count the parties who haven’t signed, filter data.object.parties on signingStatus. When every signing party has signed, document.fully_signed fires, followed by document.completed when the sealed PDF is ready. For every event, see Webhook events.To check the state without webhooks, call Get a document by ID and read each party’s signingStatus and readStatus.

Give parties roles that don’t sign

Every party has a role:

SIGNER: signs the document.
REVIEWER: reviews the document without signing.
ORGANIZER: organizes the document without signing.

Only SIGNER parties have to sign before the document is completed.

Common sequences

The following patterns use "signingMode": "SEQUENTIAL" in the document’s documentMeta:

Your company signs first, then the customer: give your signatory signingOrder 1 and the customer’s signatory 2.
Two companies sign, then witnesses: give both companies’ signatories 1, and every witness 2.
An employee signs, then a manager countersigns: give the employee 1 and the manager 2.

For a board resolution or a document where everyone signs on equal terms, use PARALLEL and leave out signingOrder.

Things to plan for

In a sequence, one party who doesn’t sign blocks everyone after them. Set an expiration date and keep automatic reminders on. For more information, see Reminders and expiration.
When a party rejects the document, the document’s status becomes REJECTED, and the document.party.rejected and document.rejected events fire. To try again, create and send a new document.
To change the order of a sent document, withdraw it, update the parties’ signingOrder, and send it again. documentMeta.signingMode can’t change while the document is sent.

Handle errors

400 VALIDATION_FAILED: a party is invalid, for example without email. Read issues for the path, such as parties.2.email.
409 INVALID_STATE on PATCH /api/v1/documents/DOCUMENT_ID with a changed documentMeta.signingMode after sending, or on PATCH /api/v1/documents/DOCUMENT_ID/parties/PARTY_ID with a changed signingOrder: the setting is locked. Withdraw the document first.
400 VALIDATION_FAILED with documentMeta.signingOrder in the request: the setting is named signingMode in documentMeta.

For the error shape and every code, see Errors.

Next steps

Reminders and expiration

Keep a long sequence moving.

Set the signing method

Use a different signing method for each party.

Webhooks

Track signing progress as it happens.

Parties

Learn how parties, roles, and contacts relate.

Get started

Core concepts

Guides

Webhooks

API fundamentals

Upgrading

sajn Login

API reference

Multi-party signing

Before you begin

Choose a signing order

Create a document with a signing sequence

Give parties roles that don’t sign

Common sequences

Things to plan for

Handle errors

Next steps

Reminders and expiration

Set the signing method

Webhooks

Parties

​Before you begin

​Choose a signing order

​Create a document with a signing sequence

​Give parties roles that don’t sign

​Common sequences

​Things to plan for

​Handle errors

​Next steps

Reminders and expiration

Set the signing method

Webhooks

Parties

Before you begin

Choose a signing order

Create a document with a signing sequence

Give parties roles that don’t sign

Common sequences

Things to plan for

Handle errors

Next steps