Multi-party signing
Send one document to several parties and control whether they sign at the same time, one after another, or in groups
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_KEYenvironment 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 ascendingsigningOrder. Parties with the samesigningOrderform 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": "alex@example.com", "role": "SIGNER", "signingOrder": 1 },
{ "name": "Kai Berg", "email": "kai@example.com", "role": "SIGNER", "signingOrder": 1 },
{ "name": "Quinn Virtanen", "email": "quinn@example.net", "role": "SIGNER", "signingOrder": 2 },
{ "name": "Robin Laine", "email": "robin@example.net", "role": "SIGNER", "signingOrder": 2 }
]
}'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": "alex@example.com",
"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 read the state once, such as when a user opens the document in your app, call Get a document by ID and read each party's signingStatus and readStatus. Don't call it in a loop to wait for signatures. Without a webhook endpoint, see Wait for signatures.
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
signingOrder1 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 thedocument.party.rejectedanddocument.rejectedevents 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.signingModecan't change while the document is sent.
Handle errors
400 VALIDATION_FAILED: a party is invalid, for example withoutemail. Readissuesfor the path, such asparties.2.email.409 INVALID_STATEonPATCH /api/v1/documents/DOCUMENT_IDwith a changeddocumentMeta.signingModeafter sending, or onPATCH /api/v1/documents/DOCUMENT_ID/parties/PARTY_IDwith a changedsigningOrder: the setting is locked. Withdraw the document first.400 VALIDATION_FAILEDwithdocumentMeta.signingOrderin the request: the setting is namedsigningModeindocumentMeta.
For the error shape and every code, see Errors.
Next steps
Was this page helpful?
Last updated on