Creating Documents

Learn how to create documents with various configurations for different use cases.

Basic Document Creation

Create a simple document in draft status:

curl -X POST https://app.sajn.se/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Contract - John Doe",
    "type": "SIGNABLE"
  }'

Response:

{
  "documentId": "doc_123abc",
  "externalId": null,
  "expiresAt": null,
  "signers": []
}

Adding Signers During Creation

Include signers when creating the document. Each signer can have their own delivery method and signature type:

{
  "name": "Employment Contract",
  "type": "SIGNABLE",
  "signers": [
    {
      "name": "John Doe",
      "email": "[email protected]",
      "role": "SIGNER",
      "signingOrder": 1,
      "deliveryMethod": "EMAIL",
      "requiredSignature": "DRAWING"
    },
    {
      "name": "Jane Manager",
      "email": "[email protected]",
      "role": "SIGNER",
      "signingOrder": 2,
      "deliveryMethod": "EMAIL",
      "requiredSignature": "BANKID",
      "twoStepVerification": "SMS_BEFORE_SIGNING"
    }
  ]
}

The response includes signer IDs:

{
  "documentId": "doc_123",
  "signers": [
    {
      "signerId": "signer_1",
      "type": "INDIVIDUAL",
      "name": "John Doe",
      "email": "[email protected]",
      "contactId": null
    }
  ]
}

To retrieve a signer’s signing URL, use GET /api/v1/documents/{id}/signers/{signerId}. This endpoint returns the complete signing URL with token.

Company Signers and SMS Delivery

Create documents with company signers and SMS delivery with two-step verification:

{
  "name": "Business Contract",
  "type": "SIGNABLE",
  "signers": [
    {
      "type": "INDIVIDUAL",
      "name": "John Doe",
      "phone": "+46701234567",
      "role": "SIGNER",
      "signingOrder": 1,
      "deliveryMethod": "SMS",
      "requiredSignature": "DRAWING",
      "twoStepVerification": "SMS_BEFORE_SIGNING"
    },
    {
      "type": "COMPANY",
      "name": "Jane Smith",
      "email": "[email protected]",
      "companyName": "Acme Corp",
      "companyOrgNumber": "556123-4567",
      "role": "SIGNER",
      "signingOrder": 2,
      "deliveryMethod": "EMAIL",
      "requiredSignature": "BANKID"
    }
  ]
}

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

Setting Document Metadata

Configure signing workflow and notifications:

{
  "name": "Service Agreement",
  "type": "SIGNABLE",
  "documentMeta": {
    "subject": "Please sign the service agreement",
    "message": "Thank you for choosing our services. Please review and sign the attached agreement.",
    "signingOrder": "SEQUENTIAL",
    "forceReadFullDocument": true,
    "preferredLanguage": "sv"
  }
}

Delivery method and signature type are configured per-signer, not at the document level. See Adding Signers above.

Setting Expiration

Make the document expire after 30 days:

{
  "name": "Time-Sensitive Agreement",
  "expiresAt": "2024-12-31T23:59:59Z"
}

Using External IDs

Link to your own system:

{
  "name": "Contract #12345",
  "externalId": "contract_12345_from_my_crm"
}

Creating from Templates

Use a template to pre-populate fields:

{
  "name": "Employment Contract - John Doe",
  "templateId": "template_abc123"
}

Template Workflow with Form Fields

When creating documents from templates that contain FORM fields with keys, you can fill those fields programmatically. Here’s the complete workflow:

Create document from template (this creates a copy of template fields)
Fill form fields using key-based updates: PATCH /api/v1/documents/{docId}/fields/key:{fieldKey}
Send for signing: POST /api/v1/documents/{docId}/send

Example:

# Step 1: Create from template with signers
curl -X POST https://app.sajn.se/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Contract",
    "templateId": "template_abc123",
    "signers": [{
      "name": "John Doe",
      "email": "[email protected]",
      "role": "SIGNER",
      "deliveryMethod": "EMAIL",
      "requiredSignature": "BANKID"
    }]
  }'

# Step 2: Fill a form field by its key
curl -X PATCH https://app.sajn.se/api/v1/documents/doc_123/fields/key:employee_name \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fieldMeta": {"type": "input", "value": "John Doe"}}'

# Step 3: Send for signing
curl -X POST https://app.sajn.se/api/v1/documents/doc_123/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Delivery method and signature type are configured per-signer when adding them, not at send time.

For more details on updating fields, see Update Document Field.

Adding Custom Fields

Include custom field values during creation:

{
  "name": "Project Agreement",
  "customFields": [
    {
      "customInputId": "field_project_name",
      "value": "Website Redesign"
    },
    {
      "customInputId": "field_budget",
      "value": "50000"
    }
  ]
}

Complete Example: Business Contract

Here’s a complete example creating a business contract with all features:

{
  "name": "Service Agreement - Acme Corp",
  "type": "SIGNABLE",
  "externalId": "agreement_2024_001",
  "expiresAt": "2024-02-15T23:59:59Z",
  "documentMeta": {
    "subject": "Service Agreement for Your Review",
    "message": "Please review and sign this service agreement. Contact us if you have any questions.",
    "signingOrder": "SEQUENTIAL",
    "forceReadFullDocument": true,
    "showCommentsToSigners": true,
    "preferredLanguage": "sv",
    "validFrom": "2024-01-01T00:00:00Z",
    "validTo": "2024-12-31T23:59:59Z",
    "value": "500000"
  },
  "signers": [
    {
      "name": "Jane Manager",
      "email": "[email protected]",
      "role": "SIGNER",
      "signingOrder": 1,
      "deliveryMethod": "EMAIL",
      "requiredSignature": "DRAWING"
    },
    {
      "name": "John Client",
      "email": "[email protected]",
      "role": "SIGNER",
      "signingOrder": 2,
      "deliveryMethod": "EMAIL",
      "requiredSignature": "BANKID",
      "twoStepVerification": "SMS_BEFORE_SIGNING"
    }
  ],
  "customFields": [
    {
      "customInputId": "project_name",
      "value": "Digital Transformation"
    },
    {
      "customInputId": "department",
      "value": "IT"
    }
  ]
}

Next Steps

File Uploads

Upload PDF files to add to your documents

Send for Signing

Learn how to send documents to signers

Signer-Fillable Fields

Let signers fill in fields during signing

Document Fields

Add form fields and content sections

API Reference

Complete API reference for creating documents

​Creating Documents

​Basic Document Creation

​Adding Signers During Creation

​Company Signers and SMS Delivery

​Setting Document Metadata

​Setting Expiration

​Using External IDs

​Creating from Templates

​Template Workflow with Form Fields

​Adding Custom Fields

​Complete Example: Business Contract

​Next Steps

File Uploads

Send for Signing

Signer-Fillable Fields

Document Fields

API Reference

Creating Documents

Basic Document Creation

Adding Signers During Creation

Company Signers and SMS Delivery

Setting Document Metadata

Setting Expiration

Using External IDs

Creating from Templates

Template Workflow with Form Fields

Adding Custom Fields

Complete Example: Business Contract

Next Steps