Parties
The people on a document: their role, signing order, delivery, signature method, and verification
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": "quinn@example.com",
"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
partiestakes an optionalcontactId, and the party's details beside it:name,email,phone,nationalId,externalId,company, andcountry. Details you send override the contact's for this document. Without acontactId, a party needs aname, and anemailor aphone. - After you create it,
POST /documents/{id}/partiestakes acontactId. 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:
{
"name": "Partnership agreement",
"expiresAt": "2030-01-01T00:00:00Z",
"documentMeta": { "signingMode": "SEQUENTIAL" },
"parties": [
{
"contactId": "cm4k2x9p40006abcd3456qrst",
"role": "SIGNER",
"signingOrder": 1,
"signatureMethod": "SE_BANKID"
},
{
"name": "Quinn Holm",
"email": "quinn@example.com",
"phone": "+46705550123",
"nationalId": "199001011234",
"role": "SIGNER",
"signingOrder": 2,
"signatureMethod": "CLICK_TO_SIGN"
}
]
}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:
flowchart LR
subgraph PARALLEL
ps["Send"] --> pa["Party A"]
ps --> pb["Party B"]
ps --> pc["Party C"]
end
subgraph SEQUENTIAL
ss["Send"] --> sa["1: Party A"] --> sb["2: Party B"] --> sc["3: Party C"]
endPARALLELinvites every party when you send the document, and they sign in any order. The party'ssigningOrderis ignored.SEQUENTIALinvites parties one at a time, in ascendingsigningOrder. 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:
| 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. |
["EMAIL", "SMS"] | Both an email and a text message. Requires an email address and a phone number. |
["IN_APP"] | Nothing. The party signs in person, on your device. |
[] | Nothing. You get the signing URL from the API and give it to the party yourself. |
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:
| 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 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:
| Value | Check |
|---|---|
null | No check. The default. |
SMS | A code sent by SMS. Requires a phone number. |
EMAIL | A code sent by email. Requires an email address. |
PIN | A PIN that you share with the party yourself |
SE_BANKID | Swedish BankID |
DK_MITID, DK_MITID_ERHVERV | Danish MitID |
FI_FTN | Finnish Trust Network |
NO_BANKID_BIOMETRIC, NO_BANKID_HIGH | Norwegian BankID |
NL_IDIN | Dutch iDIN |
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:
| 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, 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
Was this page helpful?
Last updated on