Skip to main content
POST
Add a party to document

Authorizations

Authorization
string
header
required

API key, e.g. Authorization: Bearer sajn_svc_.... Not scope-limited: acts with its owner's workspace role.

Scopes

documents:write

Create documents and edit the documents the user created.

Headers

Sajn-Version
enum<string>

API version for this request. Without it, the request uses the organization's default version; an organization without a default is pinned to the latest version by its first request.

Available options:
2026-09,
2026-10
Sajn-Workspace
string

ID of the workspace this request acts in, from GET /api/v1/workspaces. Without it, an API key acts in its default workspace. The token's user must be a member of the workspace; an OAuth token only accepts the workspace it was granted for. A workspace that doesn't exist or can't be reached returns 403 WORKSPACE_ACCESS_DENIED.

Idempotency-Key
string

Makes 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.

Maximum string length: 255

Path Parameters

id
string
required

The document ID.

Body

application/json

Body

Create signer request

contactId
string
required

ID of the contact to add as a signer

Minimum string length: 1
role
enum<string>
default:SIGNER

Party role: SIGNER, ORGANIZER, or REVIEWER.

Available options:
SIGNER,
ORGANIZER,
REVIEWER
signingOrder
number | null

Signing order for sequential signing (ignored for parallel)

delivery
enum<string>[]

How the party gets the invitation: ["EMAIL"], ["SMS"], ["EMAIL", "SMS"] for both, or ["IN_APP"] to sign in person on your device. [] sends nothing, so you share the signing URL yourself. Each channel needs the matching contact detail.

Available options:
EMAIL,
SMS,
IN_APP
signatureMethod
enum<string>

How the party signs: DRAWING, SE_BANKID, CLICK_TO_SIGN, or another eID. Call GET /api/v1/helpers/signature-methods for the methods your account can use. Defaults to the workspace setting.

Available options:
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,
ZEALID_QES
signVerification
enum<string> | null

Verification the party passes before signing: PIN, SMS, EMAIL, or an eID such as SE_BANKID. null means none. Call GET /api/v1/helpers/two-step-verifications for the methods your account can use.

Available options:
PIN,
SMS,
EMAIL,
SE_BANKID,
NO_BANKID_BIOMETRIC,
NO_BANKID_HIGH,
DK_MITID,
DK_MITID_ERHVERV,
FI_FTN,
NL_IDIN,
null
openVerification
enum<string> | null

Verification this party passes before the document opens, in place of the document's openVerification: SMS, EMAIL, or an eID such as SE_BANKID. null uses the document's. PIN only gates signing, so it isn't accepted here.

Available options:
PIN,
SMS,
EMAIL,
SE_BANKID,
NO_BANKID_BIOMETRIC,
NO_BANKID_HIGH,
DK_MITID,
DK_MITID_ERHVERV,
FI_FTN,
NL_IDIN,
null

Response

200

id
string
required

The party ID

documentId
string
required

The ID of the document the party belongs to

email
string<email> | null
required

Signer email address

Pattern: ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
name
string
required

Signer full name

phone
string | null
required

Signer phone number (for SMS notifications)

type
enum<string>
required

Party type: INDIVIDUAL or COMPANY

Available options:
INDIVIDUAL,
COMPANY
company
object | null
required

The company the party signs for, or null for a private individual

externalId
string | null
required

Your external reference ID for this signer

contactId
string | null
required

ID of the contact this party was created from, if any

nationalId
string | null
required

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
string | null
required

ISO 3166-1 alpha-2 country code of the party, such as SE

role
enum<string>
required

Signer role: SIGNER, ORGANIZER, or REVIEWER

Available options:
SIGNER,
ORGANIZER,
REVIEWER
signingOrder
number | null
required

Order for sequential signing (null for parallel)

signedAt
string<date-time> | null
required

Date and time when the signer signed (null if not signed)

readStatus
enum<string>
required

Read status: NOT_OPENED, OPENED, or READ

Available options:
NOT_OPENED,
OPENED,
READ
signingStatus
enum<string>
required

Signing status: NOT_SIGNED, SIGNED, or REJECTED

Available options:
NOT_SIGNED,
SIGNED,
REJECTED
delivery
enum<string>[]
required

How the party gets the invitation: ["EMAIL"], ["SMS"], ["EMAIL", "SMS"] for both, or ["IN_APP"] to sign in person on your device. [] sends nothing, so you share the signing URL yourself. Each channel needs the matching contact detail.

Available options:
EMAIL,
SMS,
IN_APP
signatureMethod
enum<string> | null
required

How the party signs: DRAWING, SE_BANKID, CLICK_TO_SIGN, or another eID.

Available options:
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,
ZEALID_QES,
null
signVerification
enum<string> | null
required

Verification the party passes before signing: PIN, SMS, EMAIL, or an eID such as SE_BANKID. null means none. Call GET /api/v1/helpers/two-step-verifications for the methods your account can use.

Available options:
PIN,
SMS,
EMAIL,
SE_BANKID,
NO_BANKID_BIOMETRIC,
NO_BANKID_HIGH,
DK_MITID,
DK_MITID_ERHVERV,
FI_FTN,
NL_IDIN,
null
openVerification
enum<string> | null
required

Verification this party passes before the document opens, in place of the document's openVerification: SMS, EMAIL, or an eID such as SE_BANKID. null uses the document's. PIN only gates signing, so it isn't accepted here.

Available options:
PIN,
SMS,
EMAIL,
SE_BANKID,
NO_BANKID_BIOMETRIC,
NO_BANKID_HIGH,
DK_MITID,
DK_MITID_ERHVERV,
FI_FTN,
NL_IDIN,
null
sendStatus
enum<string> | null
required

Send status: NOT_SENT, SENT, DELIVERED, BOUNCED, or FAILED

Available options:
NOT_SENT,
SENT,
DELIVERED,
BOUNCED,
FAILED,
null
signingUrl
string
required

Complete signing URL for this signer

identityVerified
boolean
required

True when an eID verified this signer — either by signing with one or by passing an eID verification gate.

identityMismatch
boolean
required

True 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 a national ID match to sign and the attempt was refused, because no signature exists; those attempts appear only in the document audit trail.

createdAt
string<date-time>
required

When the party was added to the document