Skip to main content
A party is a person on a document. Each party has a role, which decides whether they sign, and their own settings for how sajn reaches them and how they prove who they are. You manage parties with the /documents/{id}/parties endpoints and read them from the parties array of a document.
API version 2026-10 removes the /signers endpoints and the signers field. To move from them, see Migrate from signers to parties.

Roles

The role field decides what a party does: A document completes when every SIGNER has signed. A document needs at least one SIGNER before you can send it. Reviewers and organizers also receive the sealed PDF when the document completes.
API version 2026-10 rejects the ACCEPTOR role. Use SIGNER instead. In API version 2026-09, ACCEPTOR is accepted on input and treated as SIGNER.

Individuals and companies

A party’s type is COMPANY when it has a company, and INDIVIDUAL otherwise. A company party is a person who signs on behalf of the company. The party’s company object holds the company, and is null for a private individual. The following excerpt shows a company party:
To add a company party by name, send company with name, orgNumber, and optionally role. To make a party a private individual, update the party with company: null. A party’s country is an ISO 3166-1 alpha-2 code, such as SE.

Add a party

You can add parties when you create the document, or afterward:
  • When you create the document, each entry in parties takes an optional contactId, and the party’s details beside it: name, email, phone, nationalId, externalId, company, and country. Details you send override the contact’s for this document. Without a contactId, a party needs a name, and an email or a phone.
  • After you create it, POST /documents/{id}/parties takes a contactId. To add someone who isn’t a contact yet, create the contact first.
A party added from a contact gets its name, email, phone number, national ID, and company from the contact, except the details you send yourself. It keeps its own copy: changing the contact later doesn’t change the party. The following request creates a document with two parties, one from a contact and one by name:
To change a party’s details later, update the party.

Signing order

The document’s documentMeta.signingMode decides whether parties sign at the same time:
  • PARALLEL invites every party when you send the document, and they sign in any order. The party’s signingOrder is ignored.
  • SEQUENTIAL invites parties one at a time, in ascending signingOrder. sajn invites the next party only after the previous one has signed.

Delivery

The delivery field decides how a party receives the signing invitation. It’s a list of channels: IN_APP can’t be combined with another channel. Parties on one document can use different channels.

Signature method

The signatureMethod field decides how a party signs. The method also decides the legal level of the signature: eID schemes are switched on market by market. To build a picker, call GET /helpers/signature-methods instead of hard-coding the list. For what each method proves, see Signing methods. To check that the right person signs with an eID, set the party’s nationalId. sajn compares it with the identity the eID returns. Without it, sajn compares names. The identity the eID verified is available from GET /documents/{id}/signatures.

Verification before signing

The signVerification field adds a check that the party must pass before they sign. It’s independent of signatureMethod, so you can, for example, put a BankID check in front of a click-to-sign signature: For the list your account can use, call GET /helpers/two-step-verifications.

Verification before opening

To require a check before the document opens, set documentMeta.openVerification on the document. Every party passes it, and it takes the same values as signVerification. To give one party a different check before opening, set the party’s own openVerification. It overrides the document’s for that party, and null uses the document’s. A party’s openVerification can’t be PIN, because a PIN only gates signing; use signVerification for a PIN. For more information, see Identity verification.

Party status

Three fields track each party’s progress: signedAt holds the time the party signed. identityVerified is true when an eID verified the party, either as the signature or as the check before opening. When a party rejects the document, the document’s status becomes REJECTED, and nobody else can sign it.

Signing URLs

Each party has its own signing URL. To get it, call GET /documents/{id}/parties/{partyId}:
Only this endpoint returns signingUrl. The party list and the document leave it out. sajn records an audit log entry each time you fetch a signing URL, so fetch it only when you give it to the party. To follow a party’s status, use the document.party.* webhook events, not this endpoint.
A signing URL lets anyone who holds it act as that party. Give it only to that party, and never publish it.

Change a party

On a draft, you can update every property of a party, and null clears phone, externalId, nationalId, or a key of company. You can remove a party who hasn’t signed, from a draft or a sent document. After you send the document, you can correct the name, email, and phone of a party who hasn’t signed. Any other property returns 409 INVALID_STATE; to change it, withdraw the document first. After a party signs, their details can’t change.

Next steps

Signing methods

What each signature method proves, and when to use it.

Contacts

Reuse people across documents.

Multi-party signing

Send one document to several parties.

Send for signing

Send a document and follow its progress.