Create a new document

Create a new document in DRAFT status. You can optionally include parties, 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 parties 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 Parties: 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 party details

Note: The legacy signers field is also accepted as input for backwards compatibility, but is deprecated and will stop working in API v2. Use parties going forward. If both are provided, parties takes precedence.

Party Examples:

{
  "parties": [
    {
      "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-Party 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 parties 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 parties if needed: POST /api/v1/documents/{docId}/parties
5. Send for signing: POST /api/v1/documents/{docId}/send

Note: Each party 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 parties
POST /api/v1/documents
{
  "name": "Employment Contract",
  "templateId": "template-id-with-form-fields",
  "parties": [
    {
      "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, party IDs, tokens, and signing URLs for all added parties. The legacy signers field is also included in the response (same content as parties) for backwards compatibility, but is deprecated.

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": [],
  "parties": [],
  "externalId": "<string>",
  "expiresAt": "<string>",
  "templateId": "<string>",
  "responsibleUserId": "<string>",
  "documentMeta": {
    "subject": "<string>",
    "message": "<string>",
    "forceReadFullDocument": true,
    "showChatToSigners": true,
    "value": "<string>",
    "redirectUrl": "<string>",
    "redirectEnabled": true
  },
  "documentStyle": {
    "paddingEnabled": true,
    "backgroundColor": "<string>",
    "backgroundOpacity": 0.5,
    "backgroundImageUrl": "<string>",
    "backgroundImageOpacity": 0.5
  },
  "customFields": [
    {
      "customInputId": "<string>",
      "value": "<string>"
    }
  ]
}
'

200

{
  "documentId": "<string>",
  "signers": [
    {
      "signerId": "<string>",
      "name": "<string>",
      "email": "[e-mail]",
      "signingOrder": 123,
      "companyName": "<string>",
      "companyOrgNumber": "<string>",
      "country": "<string>",
      "contactId": "<string>"
    }
  ],
  "parties": [
    {
      "signerId": "<string>",
      "name": "<string>",
      "email": "[e-mail]",
      "signingOrder": 123,
      "companyName": "<string>",
      "companyOrgNumber": "<string>",
      "country": "<string>",
      "contactId": "<string>"
    }
  ],
  "externalId": "<string>",
  "expiresAt": "<string>"
}

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

[DEPRECATED — use parties instead, will be removed in API v2] Array of signers to add to the document during creation. If both signers and parties are provided, parties takes precedence.

Option 1

Option 2

Show child attributes

parties · object[] · required

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

Option 1

Option 2

Show child attributes

externalId · string | null

Your external reference ID for tracking this document

expiresAt · string | 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

[DEPRECATED — use parties instead, will be removed in API v2] Array of created parties. Same content as parties.

Show child attributes

parties · object[] · required

Array of created parties. Use GET /documents/:id/parties/:partyId to retrieve signing URLs.

Show child attributes

externalId · string | null

Your external reference ID

expiresAt · string | null

Document expiration date