Add a party to document
2026-09, which is deprecated and stops working on October 1, 2027. To move your integration, see Upgrading to 2026-10.Add a party (signer/participant) to a document. The party must reference an existing contact.
Party Roles:
SIGNER- Must sign the documentORGANIZER- Document organizer (no signature required)REVIEWER- Reviews document (no signature required)ACCEPTOR- Deprecated. Still accepted on input but stored asSIGNER; never returned. Removed in v2.
Per-Party Settings:
deliveryMethod- How to notify:EMAIL(default),SMS, orNONE(use signing URL directly)requiredSignature- Signature type:DRAWING,BANKID(Swedish BankID),CLICK_TO_SIGN,MANUAL, or a national eID scheme. eID schemes are switched on market by market — callGET /api/v1/helpers/signature-methodsfor the set your account can actually use rather than hard-coding a listtwoStepVerification- identity gate passed BEFORE the document opens:NONE(default),PIN_BEFORE_SIGNING,SMS_BEFORE_SIGNING,EMAIL_BEFORE_SIGNING, or an eID gate such asBANKID_BEFORE_SIGNING— callGET /api/v1/helpers/two-step-verificationsfor the live list
Signing Order: For SEQUENTIAL signing, specify the order (1, 2, 3...). For PARALLEL signing, order is ignored.
Response: Returns the created party. Use GET /documents/:id/parties/:partyId to retrieve the signing URL.
AuthorizationBearer <token>Personal API key, e.g. Authorization: Bearer sajn_sk_.... Not scope-limited — acts as the issuing user.
id*stringIdempotency-Key?stringMakes retries safe. A retry with the same key and the same request replays the stored response for 24 hours (header Idempotent-Replayed: true); the same key with a different request returns 400.
length <= 255Body
application/json- body
Create signer request
contactId*stringID of the contact to add as a signer
1 <= lengthrole*unknownParty role: SIGNER, ORGANIZER, or REVIEWER. (ACCEPTOR is deprecated and treated as SIGNER.)
"SIGNER"signingOrder?|Signing order for sequential signing (ignored for parallel)
deliveryMethod?stringHow to send to this signer: EMAIL (default), SMS, or NONE
"EMAIL""SMS""NONE""IN_APP"requiredSignature?stringSignature type required: DRAWING (default), BANKID, or CLICK_TO_SIGN
"NONE""DRAWING""SE_BANKID""MANUAL""CLICK_TO_SIGN""NO_BANKID_BIOMETRIC""NO_BANKID_HIGH""NO_QES""DK_MITID""DK_MITID_ERHVERV""FI_FTN""NL_IDIN"twoStepVerification?stringTwo-step verification: NONE (default), SMS_BEFORE_SIGNING, EMAIL_BEFORE_SIGNING, or BANKID_BEFORE_SIGNING
"NONE""SMS_BEFORE_SIGNING""EMAIL_BEFORE_SIGNING""PIN_BEFORE_SIGNING""SE_BANKID_BEFORE_SIGNING""NO_BANKID_BIOMETRIC_BEFORE_SIGNING""NO_BANKID_HIGH_BEFORE_SIGNING""DK_MITID_BEFORE_SIGNING""DK_MITID_ERHVERV_BEFORE_SIGNING""FI_FTN_BEFORE_SIGNING""NL_IDIN_BEFORE_SIGNING"200
application/json- response
id*stringUnique signer identifier
documentId*stringDocument ID this signer belongs to
email?|Signer email address
^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$emailname*stringSigner full name
phone?|Signer phone number (for SMS notifications)
companyName?|Company name
companyRole?|Role/title within the company
companyOrgNumber?|Company organization number
externalId?|Your external reference ID for this signer
companyId?|Linked company ID
ssn?|National identity number supplied by the sender when creating the document. Optional — BankID works without it, falling back to a name check. This is input and is never overwritten with what the eID verified: read the verified identity from GET /api/v1/documents/{id}/signatures.
country?|ISO 3166-1 alpha-3 country code for the signer (e.g. SWE)
role*stringSigner role: SIGNER, ORGANIZER, or REVIEWER
"SIGNER""ORGANIZER""REVIEWER"signingOrder?|Order for sequential signing (null for parallel)
signedAt*|Date and time when the signer signed (null if not signed)
date-timereadStatus*stringRead status: NOT_OPENED, OPENED, or READ
"NOT_OPENED""OPENED""READ"signingStatus*stringSigning status: NOT_SIGNED, SIGNED, or REJECTED
"NOT_SIGNED""SIGNED""REJECTED"deliveryMethod*|How documents are sent to this signer: EMAIL, SMS, or NONE
"EMAIL""SMS""NONE""IN_APP"requiredSignature*|Signature type required: DRAWING, BANKID, CLICK_TO_SIGN, etc.
"NONE""DRAWING""BANKID""MANUAL""CLICK_TO_SIGN""NO_BANKID_BIOMETRIC""NO_BANKID_HIGH""NO_QES""DK_MITID""DK_MITID_ERHVERV""FI_FTN""NL_IDIN"twoStepVerification*|Two-step verification: NONE, SMS_BEFORE_SIGNING, EMAIL_BEFORE_SIGNING, or BANKID_BEFORE_SIGNING
"NONE""PIN_BEFORE_SIGNING""SMS_BEFORE_SIGNING""EMAIL_BEFORE_SIGNING""BANKID_BEFORE_SIGNING""NO_BANKID_BIOMETRIC_BEFORE_SIGNING""NO_BANKID_HIGH_BEFORE_SIGNING""DK_MITID_BEFORE_SIGNING""DK_MITID_ERHVERV_BEFORE_SIGNING""FI_FTN_BEFORE_SIGNING""NL_IDIN_BEFORE_SIGNING"sendStatus*|Send status: NOT_SENT, SENT, DELIVERED, BOUNCED, or FAILED
"NOT_SENT""SENT""DELIVERED""BOUNCED""FAILED"identityVerified*booleanTrue when an eID verified this signer — either by signing with one or by passing an eID verification gate.
identityMismatch*booleanTrue when an eID completed, the identity did not match the intended signer, and the signature was still recorded — read GET /api/v1/documents/{id}/signatures to see what differed. Stays false when the workspace requires an SSN match to sign and the attempt was refused, because no signature exists; those attempts appear only in the document audit trail.
curl -X POST 'https://app.sajn.se/api/v1/documents/string/parties' \ -H 'authorization: string' \ -H 'Content-Type: application/json' \ -d '{ "contactId": "string", "role": "SIGNER"}'{ "id": "string", "documentId": "string", "email": "user@example.com", "name": "string", "phone": "string", "companyName": "string", "companyRole": "string", "companyOrgNumber": "string", "externalId": "string", "companyId": "string", "ssn": "string", "country": "string", "role": "SIGNER", "signingOrder": 0, "signedAt": "2019-08-24T14:15:22Z", "readStatus": "NOT_OPENED", "signingStatus": "NOT_SIGNED", "deliveryMethod": "EMAIL", "requiredSignature": "NONE", "twoStepVerification": "NONE", "sendStatus": "NOT_SENT", "identityVerified": true, "identityMismatch": true}Was this page helpful?