Create a new document

Create a new document in DRAFT status. You can optionally include signers, metadata, and responsible user during creation.

Document Types:

• SIGNABLE (default) - Standard signing document
• ACCEPTABLE - Document that requires acceptance rather than signature
• ARCHIVE_IMPORTED - Imported from external archive

Template Support: Use templateId to create a document from a template. Template fields and template parties are automatically copied unless signers are explicitly provided in the request.

Responsible User: Use responsibleUserId to assign a specific team member as responsible for the document. Defaults to the creating user if not specified.

Adding Signers: Two approaches are supported:

1. Contact-based (recommended): Provide contactId to reference existing contacts - automatically inherits all contact details
2. Manual: Provide name and email to manually specify signer details

Signer Examples:

{
  "signers": [
    {
      "contactId": "contact-123",
      "role": "SIGNER",
      "signingOrder": 1,
      "deliveryMethod": "EMAIL",
      "requiredSignature": "BANKID"
    },
    {
      "name": "John Doe",
      "email": "[e-mail]",
      "role": "SIGNER",
      "signingOrder": 2,
      "deliveryMethod": "SMS",
      "requiredSignature": "DRAWING"
    }
  ]
}

Per-Signer Settings:

• deliveryMethod - How to notify: EMAIL (default), SMS, or NONE
• requiredSignature - Signature type: DRAWING, BANKID, or CLICK_TO_SIGN
• twoStepVerification - 2FA: NONE (default) or SMS_BEFORE_SIGNING

Complete Workflow with Templates:

1. Create template (manually in dashboard) with FORM fields containing keys (e.g., “name”, “phone”, “email”)
2. Create document from template (this endpoint) - include signers with their deliveryMethod and requiredSignature settings
3. Fill form fields using key-based updates: PATCH /api/v1/documents/{docId}/fields/key:name
4. Add more signers if needed: POST /api/v1/documents/{docId}/signers
5. Send for signing: POST /api/v1/documents/{docId}/send

Note: Each signer can have their own deliveryMethod (EMAIL, SMS, NONE) and requiredSignature (DRAWING, BANKID, CLICK_TO_SIGN) configured when adding them.

Example workflow:

# Step 1: Create document from template with signers
POST /api/v1/documents
{
  "name": "Employment Contract",
  "templateId": "template-id-with-form-fields",
  "signers": [
    {
      "type": "contact",
      "contactId": "contact-456",
      "role": "SIGNER",
      "deliveryMethod": "EMAIL",
      "requiredSignature": "BANKID"
    }
  ]
}

# Step 2: Fill form fields using keys
PATCH /api/v1/documents/{docId}/fields/key:name
{
  "fieldMeta": {"type": "input", "value": "Andreas"}
}

PATCH /api/v1/documents/{docId}/fields/key:phone
{
  "fieldMeta": {"type": "input", "value": "0767767712"}
}

# Step 3: Send for signing
POST /api/v1/documents/{docId}/send
{}

Response: Returns the created document ID, signer IDs, tokens, and signing URLs for all added signers.

POST /api/v1/documents

Create a new document

cURL

curl --request POST \
  --url https://app.sajn.se/api/v1/documents \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "name": "<string>",
  "signers": [],
  "externalId": "<string>",
  "expiresAt": "2023-11-07T05:31:56Z",
  "type": "SIGNABLE",
  "templateId": "<string>",
  "responsibleUserId": "<string>",
  "documentMeta": {
    "subject": "<string>",
    "message": "<string>",
    "signingOrder": "PARALLEL",
    "forceReadFullDocument": true,
    "showChatToSigners": true,
    "preferredLanguage": "sv",
    "value": "<string>",
    "redirectUrl": "<string>",
    "redirectEnabled": true
  },
  "documentStyle": {
    "orientation": "PORTRAIT",
    "paddingEnabled": true,
    "backgroundColor": "<string>",
    "backgroundOpacity": 0.5,
    "backgroundImageUrl": "<string>",
    "backgroundImageSize": "FILL",
    "backgroundImagePosition": "TOP_LEFT",
    "backgroundImageRepeat": "REPEAT",
    "backgroundImageOpacity": 0.5,
    "pageSize": "A4"
  },
  "customFields": [
    {
      "customInputId": "<string>",
      "value": "<string>"
    }
  ]
}
'

200

{
  "documentId": "<string>",
  "signers": [
    {
      "signerId": "<string>",
      "name": "<string>",
      "role": "SIGNER",
      "type": "INDIVIDUAL",
      "email": "[e-mail]",
      "signingOrder": 123,
      "companyName": "<string>",
      "companyOrgNumber": "<string>",
      "contactId": "<string>"
    }
  ],
  "externalId": "<string>",
  "expiresAt": "2023-11-07T05:31:56Z"
}

Headers

authorization · string · required

Bearer token for API authentication

Body

application/json

Body

name · string · required

Document name/title

Minimum string length: 1

signers · object[] · required

Array of signers to add to the document during creation. Provide either contactId to reference existing contacts, or name and email to manually specify signer details.

Option 1

Option 2

Show child attributes

externalId · string | null

Your external reference ID for tracking this document

expiresAt · string<date-time> | null

Expiration date for the document

type · enum<string>

Document type: SIGNABLE (default), ACCEPTABLE, or ARCHIVE_IMPORTED

Available options: SIGNABLE, ACCEPTABLE, ARCHIVE_IMPORTED

templateId · string | null

Template ID to create document from. Template fields and template parties are copied by default.

responsibleUserId · string

User ID of the person responsible for this document. Must be a member of your organization. Defaults to the creating user.

documentMeta · object

Document metadata including subject, message, signing order, etc.

Show child attributes

documentStyle · object

Document styling configuration including orientation, padding, background, and layout

Show child attributes

customFields · object[]

Custom field values for the document

Show child attributes

Response

200

application/json

200

documentId · string · required

Unique identifier for the created document

signers · object[] · required

Array of created signers. Use GET /documents/:id/signers/:signerId to retrieve signing URLs.

Show child attributes

externalId · string | null

Your external reference ID

expiresAt · string<date-time> | null

Document expiration date