Parties

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:

Role	What the party does	Must act for the document to complete
`SIGNER`	Signs the document.	Yes
`REVIEWER`	Is invited to review the document. Doesn’t sign.	No
`ORGANIZER`	Is added to follow the document as its organizer. Doesn’t sign.	No

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:

{
  "name": "Quinn Holm",
  "email": "[email protected]",
  "role": "SIGNER",
  "country": "SE",
  "company": {
    "id": "cm4k2x9p50007abcd7890uvwx",
    "name": "Example AB",
    "orgNumber": "556677-8899",
    "role": "CEO"
  }
}

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 either a contactId, or a name and an email.
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. 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:

{
  "name": "Partnership agreement",
  "expiresAt": "2030-01-01T00:00:00Z",
  "documentMeta": { "signingMode": "SEQUENTIAL" },
  "parties": [
    {
      "contactId": "cm4k2x9p40006abcd3456qrst",
      "role": "SIGNER",
      "signingOrder": 1,
      "requiredSignature": "SE_BANKID"
    },
    {
      "name": "Quinn Holm",
      "email": "[email protected]",
      "role": "SIGNER",
      "signingOrder": 2,
      "requiredSignature": "CLICK_TO_SIGN"
    }
  ]
}

To set a phone number or national ID on a party you added by name, 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 deliveryMethod field decides how a party receives the signing invitation:

Value	Delivery
`EMAIL`	An email with the signing link. The default. Requires an email address.
`SMS`	A text message with the signing link. Requires a phone number.
`NONE`	Nothing. You get the signing URL from the API and give it to the party yourself.
`IN_APP`	Nothing. The party signs in person, on your device.

You can mix delivery methods on one document.

Signature method

The requiredSignature field decides how a party signs. The method also decides the legal level of the signature:

Value	Method
`CLICK_TO_SIGN`	Click to sign
`DRAWING`	A drawn signature
`SE_BANKID`	Swedish BankID
`DK_MITID`, `DK_MITID_ERHVERV`	Danish MitID, personal or business
`FI_FTN`	Finnish Trust Network
`NO_BANKID_BIOMETRIC`, `NO_BANKID_HIGH`, `NO_QES`	Norwegian BankID
`NL_IDIN`	Dutch iDIN
`MANUAL`	Signed on paper, outside sajn. Used for imported documents.

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 opening

The twoStepVerification field adds a check that the party must pass before the document opens. It’s independent of requiredSignature, so you can, for example, put a BankID check in front of a click-to-sign document:

Value	Check
`NONE`	No check. The default.
`SMS_BEFORE_SIGNING`	A code sent by SMS. Requires a phone number.
`EMAIL_BEFORE_SIGNING`	A code sent by email. Requires an email address.
`PIN_BEFORE_SIGNING`	A PIN that you share with the party yourself
`SE_BANKID_BEFORE_SIGNING`	Swedish BankID
`DK_MITID_BEFORE_SIGNING`, `DK_MITID_ERHVERV_BEFORE_SIGNING`	Danish MitID
`FI_FTN_BEFORE_SIGNING`	Finnish Trust Network
`NO_BANKID_BIOMETRIC_BEFORE_SIGNING`, `NO_BANKID_HIGH_BEFORE_SIGNING`	Norwegian BankID
`NL_IDIN_BEFORE_SIGNING`	Dutch iDIN

For the list your account can use, call GET /helpers/two-step-verifications. To require the same check from every party, set documentMeta.accessVerification instead. For more information, see Identity verification.

Party status

Three fields track each party’s progress:

Field	Values
`sendStatus`	`NOT_SENT`, `SENT`, `DELIVERED`, `BOUNCED`, `FAILED`
`readStatus`	`NOT_OPENED`, `OPENED`, `READ`
`signingStatus`	`NOT_SIGNED`, `SIGNED`, `REJECTED`

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}:

{
  "id": "cm4k2x9p20002abcd5678ijkl",
  "name": "Quinn Holm",
  "role": "SIGNER",
  "signingStatus": "NOT_SIGNED",
  "signingUrl": "https://app.sajn.se/sign/cm4k2x9p10001abcd1234efgh?token=SIGNING_TOKEN"
}

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.

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.

Get started

Core concepts

Guides

Webhooks

API fundamentals

Upgrading

sajn Login

API reference

Roles

Individuals and companies

Add a party

Signing order

Delivery

Signature method

Verification before opening

Party status

Signing URLs

Change a party

Next steps

Signing methods

Contacts

Multi-party signing

Send for signing

​Roles

​Individuals and companies

​Add a party

​Signing order

​Delivery

​Signature method

​Verification before opening

​Party status

​Signing URLs

​Change a party

​Next steps

Signing methods

Contacts

Multi-party signing

Send for signing

Roles

Individuals and companies

Add a party

Signing order

Delivery

Signature method

Verification before opening

Party status

Signing URLs

Change a party

Next steps