HTML Fields

HTML fields enable you to create custom-styled document sections using HTML and CSS. These API-only fields provide advanced formatting control beyond the standard TEXT field, allowing precise control over document appearance.

Overview

HTML fields allow you to add custom-styled content to documents with full control over HTML structure and CSS styling. Unlike the TEXT field (which uses the Tiptap editor format), HTML fields accept raw HTML and are perfect for:

Branded headers and footers - Add logos, colors, and custom layouts
Custom-styled sections - Create professional document layouts with precise styling
Image-rich content - Embed images from URLs or inline base64
Complex layouts - Use tables, multi-column layouts, and advanced CSS

Key Features

API-Only Access - Not visible in the UI editor, only via REST API
Automatic Sanitization - HTML is sanitized server-side for security
Safe Subset of HTML - Formatting tags and links allowed (no scripts; links restricted to http, https, mailto, tel)
Inline CSS Styling - Full control over colors, fonts, spacing, borders
Image Support - HTTP/HTTPS URLs and base64 data URIs
PDF-Ready - Renders perfectly in generated PDF documents

When to Use HTML Fields

Use HTML fields when you need:

Precise visual control - Exact colors, spacing, and layout
Brand consistency - Match your company’s visual identity
Complex layouts - Multi-column sections or advanced tables
Embedded images - Logos, signatures, or diagrams

Use TEXT fields when you need:

Simple rich text - Basic formatting with the Tiptap editor
UI editing - Content editable in the dashboard
Collaborative editing - Multiple users editing in the UI

Creating HTML Fields

Field Properties

When creating an HTML field, you can specify the following properties: type (string, required)

Must be "HTML"

position (number, optional)

Determines the order fields appear in the document (0-based index)
If omitted, the field is appended to the end
Use to control field ordering when creating multiple fields

key (string, optional)

Unique key identifier for API access
Must match pattern: ^[a-z0-9_-]*$ (lowercase letters, numbers, underscores, hyphens)
Allows referencing the field via API using key: prefix (e.g., /api/v1/documents/{docId}/fields/key:header-section)

fieldMeta (object, required)

type (string, required) - Must be "HTML"
content (string, required) - The HTML content string

Basic Example

Create a document with an HTML field containing styled content:

curl -X POST https://app.sajn.se/api/v1/documents/doc_xyz789/fields \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [{
      "type": "HTML",
      "fieldMeta": {
        "type": "HTML",
        "content": "<div style=\"text-align: center; padding: 20px;\"><h1 style=\"color: #003366; font-size: 28px; margin-bottom: 10px;\">Service Agreement</h1><p style=\"color: #666; font-size: 14px;\">Effective Date: January 1, 2024</p></div>"
      }
    }]
  }'

Response:

{
  "fields": [
    {
      "fieldId": "field_456xyz",
      "type": "HTML",
      "position": 0,
      "fieldMeta": {
        "type": "HTML",
        "content": "<div style=\"text-align: center; padding: 20px;\"><h1 style=\"color: #003366; font-size: 28px; margin-bottom: 10px;\">Service Agreement</h1><p style=\"color: #666; font-size: 14px;\">Effective Date: January 1, 2024</p></div>"
      }
    }
  ]
}

The response includes a fieldId for each created field, which you can use to reference the field in subsequent API calls (e.g., updating or deleting the field).

Complete Example with All Properties

# Step 1: Create document
curl -X POST https://app.sajn.se/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "type": "SIGNABLE"
  }'

# Step 2: Add HTML field with position and key
curl -X POST https://app.sajn.se/api/v1/documents/doc_xyz789/fields \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [{
      "type": "HTML",
      "position": 0,
      "key": "header-section",
      "fieldMeta": {
        "type": "HTML",
        "content": "<div style=\"background-color: #f8f9fa; padding: 30px; border-bottom: 3px solid #003366;\"><h1 style=\"color: #003366; margin: 0; font-size: 32px;\">Professional Service Agreement</h1><p style=\"color: #666; margin-top: 10px; font-size: 14px;\">Between Company AB and Client Ltd</p></div>"
      }
    }]
  }'

Response:

{
  "fields": [
    {
      "fieldId": "field_456xyz",
      "type": "HTML",
      "position": 0,
      "key": "header-section",
      "fieldMeta": {
        "type": "HTML",
        "content": "<div style=\"background-color: #f8f9fa; padding: 30px; border-bottom: 3px solid #003366;\"><h1 style=\"color: #003366; margin: 0; font-size: 32px;\">Professional Service Agreement</h1><p style=\"color: #666; margin-top: 10px; font-size: 14px;\">Between Company AB and Client Ltd</p></div>"
      }
    }
  ]
}

Multiple Fields with Position Control

When creating multiple HTML fields, use position to control their order:

curl -X POST https://app.sajn.se/api/v1/documents/doc_xyz789/fields \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {
        "type": "HTML",
        "position": 0,
        "key": "header",
        "fieldMeta": {
          "type": "HTML",
          "content": "<div style=\"text-align: center; padding: 20px;\"><h1>Document Header</h1></div>"
        }
      },
      {
        "type": "HTML",
        "position": 1,
        "key": "footer",
        "fieldMeta": {
          "type": "HTML",
          "content": "<div style=\"text-align: center; padding: 20px; border-top: 1px solid #ccc;\"><p>Document Footer</p></div>"
        }
      }
    ]
  }'

Response:

{
  "fields": [
    {
      "fieldId": "field_789abc",
      "type": "HTML",
      "position": 0,
      "key": "header",
      "fieldMeta": {
        "type": "HTML",
        "content": "<div style=\"text-align: center; padding: 20px;\"><h1>Document Header</h1></div>"
      }
    },
    {
      "fieldId": "field_789def",
      "type": "HTML",
      "position": 1,
      "key": "footer",
      "fieldMeta": {
        "type": "HTML",
        "content": "<div style=\"text-align: center; padding: 20px; border-top: 1px solid #ccc;\"><p>Document Footer</p></div>"
      }
    }
  ]
}

Document Style Settings

Documents support layout and appearance configuration through the documentStyle parameter. This controls document-level settings like orientation, padding, and background color.

Configuring Document Styles

When creating or updating a document, you can specify layout and style settings:

curl -X POST https://app.sajn.se/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Professional Agreement",
    "type": "SIGNABLE",
    "documentStyle": {
      "orientation": "PORTRAIT",
      "paddingEnabled": true,
      "backgroundColor": "#ffffff"
    }
  }'

Supported Properties

The documentStyle object supports the following properties: orientation (string)

PORTRAIT - Default orientation (816x1054px)
LANDSCAPE - Landscape orientation (1054x816px)

paddingEnabled (boolean)

true - Shows padding around document content (default)
false - Content fills entire page edge-to-edge

backgroundColor (string)

Background color in hex format (e.g., #ffffff, #f8f9fa)
Default: #ffffff (white)
Must be a valid 6-character hex color

Combining with HTML Field Styles

The documentStyle settings control the document canvas, while HTML field inline styles control content appearance. Use them together:

documentStyle - Document orientation, page padding, page background
HTML inline styles - Text colors, fonts, spacing, borders, content layout

Allowed HTML Tags

HTML fields support a safe subset of HTML tags for formatting and layout. All HTML content is automatically sanitized server-side.

Text Formatting

<p>, <span>, <div> - Basic containers
<b>, <strong> - Bold text
<i>, <em> - Italic text
<u> - Underlined text
<s> - Strikethrough text
<mark> - Highlighted text
<small>, <sub>, <sup> - Size and position

Headings

<h1>, <h2>, <h3>, <h4>, <h5>, <h6> - All heading levels

Lists

<ul> - Unordered lists
<ol> - Ordered lists
<li> - List items

Tables

<table>, <thead>, <tbody>, <tfoot> - Table structure
<tr>, <td>, <th> - Table rows and cells
<caption> - Table caption

Images

<img> - Images with src, alt, width, height, title attributes

Other

<br>, <hr> - Line breaks and horizontal rules
<blockquote> - Quoted text
<pre>, <code> - Code blocks

Allowed Attributes

All elements:

style - Inline CSS styles
class - CSS class names

Images (<img>):

src - Image source (HTTP/HTTPS URLs or data URIs)
alt - Alternative text
width, height - Dimensions
title - Image title

Tables:

<table>: border, cellpadding, cellspacing, width
<td>, <th>: colspan, rowspan, align, valign

Text elements:

<p>, <div>, <h1> through <h6>: align

Links (<a>):

href - URL (http, https, mailto, tel only)
target - Forced to _blank for security
rel - Forced to noopener noreferrer for security
title - Link title

Not Allowed

The following tags are automatically removed for security:

<script> - JavaScript (XSS protection)
<iframe> - Embedded content
<form>, <input> - Form elements
<style> - Style tags (use inline styles instead)

Allowed CSS Properties

CSS can only be applied via inline style attributes on elements. The following properties are supported:

Colors

<div style="color: #003366; background-color: #f8f9fa;">
  Styled text
</div>

color - Text color (hex, rgb, rgba)
background-color - Background color
background - Background shorthand

Typography

<p style="font-size: 16px; font-weight: bold; font-family: Arial, sans-serif; line-height: 1.5;">
  Custom typography
</p>

font-size - Font size (px, em, rem, %, pt)
font-weight - Font weight (normal, bold, 100-900)
font-style - Font style (normal, italic)
font-family - Font family
line-height - Line height
letter-spacing - Letter spacing
text-align - Text alignment (left, right, center, justify)
text-decoration - Text decoration (underline, line-through)
text-transform - Text transform (uppercase, lowercase, capitalize)

Spacing

<div style="margin: 20px; padding: 15px;">
  Spaced content
</div>

margin, margin-top/right/bottom/left - Outer spacing
padding, padding-top/right/bottom/left - Inner spacing

Borders

<div style="border: 2px solid #003366; border-radius: 8px;">
  Bordered box
</div>

border - Border shorthand (format: widthpx style #color, e.g., 2px solid #003366)
border-top/right/bottom/left - Individual borders (same format as border shorthand)
border-color - Border color (hex format)
border-width - Border width (px values)
border-style - Border style (solid, dashed, dotted, none)
border-radius - Rounded corners (px, em, rem, %)

Layout

<div style="width: 100%; max-width: 600px; display: block;">
  Layout container
</div>

width, height - Element dimensions
max-width, max-height - Maximum dimensions
min-width, min-height - Minimum dimensions
display - Display type (block, inline, inline-block, flex, grid, none)
vertical-align - Vertical alignment (top, middle, bottom, baseline)
box-sizing - Box model (border-box, content-box)

Flexbox

<div style="display: flex; flex-direction: row; justify-content: space-between; align-items: center; gap: 20px;">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>

flex-direction - Direction of flex items (row, row-reverse, column, column-reverse)
flex-wrap - Wrapping behavior (nowrap, wrap, wrap-reverse)
align-items - Cross-axis alignment (flex-start, flex-end, center, baseline, stretch, start, end)
align-content - Multi-line alignment (flex-start, flex-end, center, space-between, space-around, stretch, start, end)
justify-content - Main-axis alignment (flex-start, flex-end, center, space-between, space-around, space-evenly, start, end)
gap - Gap between flex items (px, em, rem, %)

Grid

<div style="display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 20px;">
  <div>Column 1</div>
  <div>Column 2</div>
  <div>Column 3</div>
</div>

grid-template-columns - Column track sizes (e.g., 1fr 1fr 1fr, repeat(3, 1fr), 200px auto 1fr)
grid-template-rows - Row track sizes
grid-column - Column placement for grid items
grid-row - Row placement for grid items
grid-area - Shorthand for grid placement
grid-gap - Gap between grid items (legacy, use gap instead)
row-gap - Gap between rows
column-gap - Gap between columns
gap - Gap between grid items (px, em, rem, %, fr)

Lists

<ul style="list-style-type: circle;">
  <li>Item 1</li>
</ul>

list-style-type - List marker style (disc, circle, square, decimal, lower-alpha, upper-alpha, lower-roman, upper-roman, none)

Image Support

HTML fields support three types of image sources:

1. HTTPS URLs

<img src="https://example.com/logo.png"
     alt="Company Logo"
     style="max-width: 200px; display: block; margin: 0 auto;" />

2. HTTP URLs

<img src="http://example.com/signature.jpg"
     alt="Signature"
     style="width: 150px; height: 50px;" />

3. Base64 Data URIs

Perfect for embedding images directly in the HTML:

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
     alt="Embedded Image"
     style="width: 100px;" />

Security Features

HTML fields are automatically sanitized server-side for security:

Safe & Allowed

Formatting tags (<p>, <div>, <span>, headings)
Links (<a>) with http, https, mailto, tel URLs (forced target="_blank" and rel="noopener noreferrer")
Inline CSS styles (colors, fonts, spacing)
Images from HTTP/HTTPS/data URIs
Tables, lists, and basic structure

Blocked & Removed

<script> tags - JavaScript removed
<iframe> tags - No embedded content
<style> tags - No global styles
onclick, onerror - No event handlers
javascript:, data:, vbscript: - Dangerous URL schemes stripped from links

Example: Sanitization in Action

Input:

<div>
  <h1>Title</h1>
  <script>alert('xss')</script>
  <a href="javascript:alert('xss')">Malicious</a>
  <a href="https://example.com">Safe Link</a>
  <img src="https://safe.com/image.png" alt="Safe" />
</div>

Output (Sanitized):

<div>
  <h1>Title</h1>

  <a href="https://example.com" target="_blank" rel="noopener noreferrer">Safe Link</a>
  <img src="https://safe.com/image.png" alt="Safe" />
</div>

The malicious javascript: link is stripped; the safe https link is preserved with target="_blank" and rel="noopener noreferrer" added.

Error Handling

Common Errors

Invalid HTML Content

{
  "message": "Ogiltlig field meta för denna typ av fält."
}

Ensure the content is valid HTML and uses only allowed tags. Field Type Mismatch

{
  "message": "Field meta matchar inte fälttypen."
}

Verify both type and fieldMeta.type are set to 'HTML'.

Next Steps

Creating Documents

Learn how to create documents via the API

Send for Signing

Send HTML-styled documents for signatures

File Uploads

Upload PDF files to combine with HTML fields

Document Fields API

Complete API reference for document fields

Getting Started

Core Concepts

Document Creation

Contacts & CRM

Signing & Delivery

Integrations

​HTML Fields

​Overview

​Key Features

​When to Use HTML Fields

​Creating HTML Fields

​Field Properties

​Basic Example

​Complete Example with All Properties

​Multiple Fields with Position Control

​Document Style Settings

​Configuring Document Styles

​Supported Properties

​Combining with HTML Field Styles

​Allowed HTML Tags

​Text Formatting

​Headings

​Lists

​Tables

​Images

​Links

​Other

​Allowed Attributes

​Not Allowed

​Allowed CSS Properties

​Colors

​Typography

​Spacing

​Borders

​Layout

​Flexbox

​Grid

​Lists

​Image Support

​1. HTTPS URLs

​2. HTTP URLs

​3. Base64 Data URIs

​Security Features

​Safe & Allowed

​Blocked & Removed

​Example: Sanitization in Action

​Error Handling

​Common Errors

​Next Steps

Creating Documents

Send for Signing

File Uploads

Document Fields API

HTML Fields

Overview

Key Features

When to Use HTML Fields

Creating HTML Fields

Field Properties

Basic Example

Complete Example with All Properties

Multiple Fields with Position Control

Document Style Settings

Configuring Document Styles

Supported Properties

Combining with HTML Field Styles

Allowed HTML Tags

Text Formatting

Headings

Lists

Tables

Images

Links

Other

Allowed Attributes

Not Allowed

Allowed CSS Properties

Colors

Typography

Spacing

Borders

Layout

Flexbox

Grid

Lists

Image Support

1. HTTPS URLs

2. HTTP URLs

3. Base64 Data URIs

Security Features

Safe & Allowed

Blocked & Removed

Example: Sanitization in Action

Error Handling

Common Errors

Next Steps