Signers

Understanding signers and participants in sajn

Signers

Signers are individuals who need to interact with a document. Each signer has a unique role and can track their progress through the signing process.

Signer Types

Signers can be either individuals or companies:

INDIVIDUAL

Regular person signing on their own behalf.

COMPANY

Company representative signing on behalf of their organization. Requires company information.

Signer Roles

sajn supports four different signer roles:

SIGNER

The primary role - must sign the document for it to be completed.

{
  "role": "SIGNER",
  "name": "John Doe",
  "email": "[e-mail]"
}

ORGANIZER

The person who organized the document. Receives notifications but doesn’t need to sign.

REVIEWER

Reviews the document and can leave comments, but doesn’t need to sign.

ACCEPTOR

For acceptance-type documents - accepts rather than signs the document.

Signer Information

Each signer has the following information:

{
  "type": "INDIVIDUAL",
  "name": "John Doe",
  "email": "[e-mail]",
  "phone": "[phone]",
  "ssn": "197001011234",
  "role": "SIGNER",
  "signingOrder": 1,
  "deliveryMethod": "EMAIL",
  "requiredSignature": "DRAWING",
  "twoStepVerification": "NONE",
  "contactId": "contact_123"
}

For company signers:

{
  "type": "COMPANY",
  "name": "John Doe",
  "email": "[e-mail]",
  "companyName": "Acme Corp",
  "companyOrgNumber": "556123-4567",
  "role": "SIGNER",
  "signingOrder": 1,
  "deliveryMethod": "EMAIL",
  "requiredSignature": "BANKID"
}

Required Fields

• type: Signer type (INDIVIDUAL or COMPANY)
• name: Signer’s full name
• Either email OR phone (depending on distribution method)
• role: Signer role (defaults to SIGNER)

For company signers, also required:

• companyName: Company name
• companyOrgNumber: Company organization number

Optional Fields

• phone: For SMS notifications
• ssn: Swedish personal number (required for BankID signing)
• contactId: Link to existing contact in sajn
• signingOrder: Order for sequential signing

Signing Order

When using sequential signing (signingOrder: "SEQUENTIAL"), assign each signer a number:

{
  "signers": [
    {
      "name": "Manager",
      "email": "[e-mail]",
      "role": "SIGNER",
      "signingOrder": 1,
      "deliveryMethod": "EMAIL",
      "requiredSignature": "BANKID"
    },
    {
      "name": "Employee",
      "email": "[e-mail]",
      "role": "SIGNER",
      "signingOrder": 2,
      "deliveryMethod": "EMAIL",
      "requiredSignature": "DRAWING"
    }
  ]
}

The manager must sign first before the employee can access the document.

For parallel signing, signingOrder is optional and will be ignored.

Delivery and Signature Settings

Each signer can have individual delivery and signature settings configured when adding them to a document.

deliveryMethod

How the signer receives their signing invitation:

Method	Description
EMAIL	Signing invitation sent via email (default)
SMS	Signing link sent via SMS (requires phone number)
NONE	No automatic delivery - retrieve signing URL manually

requiredSignature

The signature type required from this signer:

Type	Description
DRAWING	Free-hand signature drawing (SES)
BANKID	Swedish BankID electronic signature (AES) - requires SSN
CLICK_TO_SIGN	Simple click-to-sign (SES)
MANUAL	For in-person signing

twoStepVerification

Additional verification before signing:

Value	Description
NONE	No additional verification (default)
SMS_BEFORE_SIGNING	SMS code required before signing

For SMS verification before signing, use twoStepVerification: "SMS_BEFORE_SIGNING" combined with your chosen signature type.

Signer Status

Track each signer’s progress through two status fields:

Read Status

Status	Description
NOT_OPENED	Signer hasn’t opened the document yet
OPENED	Signer opened the document
READ	Signer read the entire document

Signing Status

Status	Description
NOT_SIGNED	Signer hasn’t signed yet
SIGNED	Signer has signed the document
REJECTED	Signer rejected the document

Retrieving Signing URLs

To get a signer’s signing URL, call the get signer endpoint:

GET /api/v1/documents/{documentId}/signers/{signerId}

Response includes the signing URL:

{
  "id": "signer_123",
  "name": "John Doe",
  "email": "[e-mail]",
  "token": "abc123...",
  "signingUrl": "https://app.sajn.se/sign/doc_123?token=abc123..."
}

Each time you retrieve a signing URL, an audit log entry is created. Only fetch signing URLs when you need to share them with signers.

Never share signing URLs publicly. Each URL is tied to a specific signer and should only be sent to that individual.

Linking Contacts

Signers are typically linked to contacts in your sajn account:

{
  "contactId": "contact_123",
  "role": "SIGNER"
}

This automatically populates signer information from the contact and tracks signing history.

BankID Integration

For BankID signatures, the signer must provide their Swedish personal number (SSN) and have requiredSignature set to BANKID:

{
  "name": "John Doe",
  "email": "[e-mail]",
  "ssn": "197001011234",
  "role": "SIGNER",
  "deliveryMethod": "EMAIL",
  "requiredSignature": "BANKID"
}

Notifications

Signers receive notifications based on their individual deliveryMethod setting:

• EMAIL: Receives signing invitation via email
• SMS: Receives signing link via SMS
• NONE: No automatic notification (retrieve and share the signing URL yourself)

Each signer can have a different delivery method, allowing you to mix email, SMS, and manual distribution in the same document.

Updating Signers

Signers can be updated before they sign:

PATCH /api/v1/documents/{id}/signers/{signerId}

Once a signer has signed, their information cannot be modified.

Best Practices

Accurate Information

Ensure signer information is accurate before sending - corrections after sending are limited.

Clear Communication

Use the custom message field to provide context about what they’re signing.

Appropriate Roles

Use REVIEWER for people who need visibility but not signing authority.

Sequential for Approval

Use sequential signing for approval workflows where order matters.

Next Steps

Contacts

Learn about managing contacts

Send for Signing

Guide to sending documents