HTML content
Add custom-styled sections to a document with sanitized HTML and inline CSS
In this guide, you add HTML content blocks to a document: sections written in HTML with inline CSS, for branded headers, styled sections, and layouts that a TEXT block can't express. sajn sanitizes the HTML on the server, and the sealed PDF renders it as written.
HTML blocks are an API feature. Use them for content your code generates. For content that people edit in the sajn app, use TEXT blocks or a template.
Before you begin
- Store your API key in the
SAJN_API_KEYenvironment variable. To create a key, go to workspace settings in the sajn app, then Utvecklare (Developer) > API-nycklar (API keys). - Have a
DRAFTdocument. For more information, see Create a document. - To send a full HTML file, escape it as a JSON string first. For more information, see Format HTML for JSON.
Add HTML content
Create the HTML block
Send a POST request to /api/v1/documents/DOCUMENT_ID/content with the block in a content array. Both type and fieldMeta.type are HTML, and fieldMeta.content holds the HTML:
curl -X POST https://app.sajn.se/api/v1/documents/DOCUMENT_ID/content \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{
"content": [
{
"type": "HTML",
"position": 0,
"fieldMeta": {
"type": "HTML",
"content": "<div style=\"text-align: center; padding: 20px;\"><h1 style=\"color: #003366;\">Service agreement</h1><p style=\"color: #666666;\">Effective from 2026-11-01</p></div>"
}
}
]
}'Replace DOCUMENT_ID with the document ID. The response has the created block in data, and fieldMeta.content holds the sanitized HTML:
{
"data": [
{
"id": "cm4k2xd5s0005abcd7890uvwx",
"documentId": "cm4k2x9p10001abcd1234efgh",
"templateId": null,
"type": "HTML",
"position": 0,
"fieldMeta": {
"type": "HTML",
"content": "<div style=\"text-align:center;padding:20px\"><h1 style=\"color:#003366\">Service agreement</h1><p style=\"color:#666666\">Effective from 2026-11-01</p></div>"
},
"createdAt": "2026-10-01T10:00:00.000Z",
"updatedAt": "2026-10-01T10:00:00.000Z"
}
]
}Compare the stored content with what you sent. sajn removes tags, attributes, and CSS values that aren't in the allowlists that follow, without an error.
Add several blocks in order
To add a header and a footer around other content, send several blocks in the content array. position is each block's 0-based place among the document's content blocks:
curl -X POST https://app.sajn.se/api/v1/documents/DOCUMENT_ID/content \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{
"content": [
{ "type": "HTML", "position": 0,
"fieldMeta": { "type": "HTML", "content": "<div style=\"padding: 20px;\"><h1>Header</h1></div>" } },
{ "type": "HTML", "position": 1,
"fieldMeta": { "type": "HTML", "content": "<div style=\"border-top: 1px solid #cccccc;\"><p>Footer</p></div>" } }
]
}'The response has the created blocks in data, in request order.
Update the content
To replace the HTML of a block, send a PATCH request with the block's id and the full fieldMeta:
curl -X PATCH https://app.sajn.se/api/v1/documents/DOCUMENT_ID/content/CONTENT_ID \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{ "type": "HTML", "fieldMeta": { "type": "HTML", "content": "<h1>Updated header</h1>" } }'Replace CONTENT_ID with the block's id. The response is the updated block. The page's look, such as orientation, page size, and background, is set on the document in documentStyle. For its properties, see Create a new document.
Add fields that parties fill in
To let a party fill in a value inside the HTML, such as an address or a start date, put a <sajn-field> tag where the value goes:
<p>Delivery address: <sajn-field key="delivery-address" party="PARTY_ID" type="TEXT" label="Delivery address"></sajn-field></p>Replace PARTY_ID with the id of the party who fills in the field. The party fills it in on the signing page, and can't sign until it's filled in unless you set required="false". For every attribute, see Inline fields in text.
Allowed HTML tags
HTML blocks 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 withsrc,alt,width,height,titleattributes
Links
<a>- Links withhref,target,rel,title(allowed schemes: http, https, mailto, tel only; dangerous schemes like javascript:, data:, vbscript: are stripped; all links forced totarget="_blank"andrel="noopener noreferrer"for security)
Other
<br>,<hr>- Line breaks and horizontal rules<label>,<input>- Checkbox lists;<input>keeps onlytype,checked, anddisabled<blockquote>- Quoted text<pre>,<code>- Code blocks
Allowed attributes
All elements:
style- Inline CSS stylesclass- CSS class names
Images (<img>):
src- Image source (HTTP/HTTPS URLs or data URIs)alt- Alternative textwidth,height- Dimensionstitle- 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_blankfor securityrel- Forced tonoopener noreferrerfor securitytitle- Link title
Removed tags
The following tags are automatically removed for security:
<script>- JavaScript (XSS protection)<iframe>- Embedded content<form>- Forms<style>- Style tags (use inline styles instead)
Allowed CSS properties
CSS works only in inline style attributes. 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 colorbackground- 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, rem, %, pt)font-weight- Font weight (normal, bold, 100-900)font-style- Font style (normal, italic)font-family- Font familyline-height- Line heightletter-spacing- Letter spacingtext-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 spacingpadding,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 dimensionsmax-width,max-height- Maximum dimensionsmin-width,min-height- Minimum dimensionsdisplay- 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 sizesgrid-column- Column placement for grid itemsgrid-row- Row placement for grid itemsgrid-area- Shorthand for grid placementgrid-gap- Gap between grid items (legacy, usegapinstead)row-gap- Gap between rowscolumn-gap- Gap between columnsgap- Gap between grid items (px, em, rem, %, fr)
List markers
<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 hosting
HTML blocks support both hosted image URLs and inline base64 data URIs. Use hosted URLs.
Host images instead of inlining them
Always reference images by a hosted https:// URL. Do not embed images as base64
data: URIs in HTML content.
Base64 inflates the image by ~33%, can't be cached or deduplicated, and is stored inline in every document you create from a template — so the same image is copied on every send. A handful of multi-MB base64 blocks can dominate your account's storage and slow document rendering. Inline base64 images are strongly discouraged and may be rejected in a future API version.
To host an image, upload it once with the presigned file-upload flow
or any public URL you control, and reference the resulting https:// URL.
The same URL can be reused across every document and template — no per-document copies.
Use a hosted HTTPS URL
<img src="https://cdn.example.com/logo.png"
alt="Company Logo"
style="max-width: 200px; display: block; margin: 0 auto;" />Avoid inline base64 data URIs
Accepted today for backwards compatibility, but avoid it — prefer a hosted URL:
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAA..."
alt="Embedded Image"
style="width: 100px;" />HTML content can be up to 100 MB, so existing integrations keep working. We recommend keeping content small, with text and hosted image URLs, because the limit can be lowered in a future API version.
Sanitization
HTML blocks are automatically sanitized server-side for security:
Kept
- Formatting tags (
<p>,<div>,<span>, headings) - Links (
<a>) with http, https, mailto, tel URLs (forcedtarget="_blank"andrel="noopener noreferrer") - Inline CSS styles (colors, fonts, spacing)
- Images from HTTP/HTTPS/data URIs
- Tables, lists, and basic structure
Removed
<script>tags - JavaScript removed<iframe>tags - No embedded content<style>tags - No global stylesonclick,onerror- No event handlersjavascript:,data:,vbscript:- Dangerous URL schemes stripped from links
Example
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.
Handle errors
Validation errors are 400 VALIDATION_FAILED, and issues lists every problem with its path. The most common one is a type that doesn't match fieldMeta.type:
{
"code": "VALIDATION_FAILED",
"message": "fieldMeta.type is HTML, but the field type is TEXT. They must match.",
"userMessage": "Förfrågan innehåller ogiltiga värden.",
"requestId": "req_V1StGXR8Z5jdHi6BmyT2",
"issues": [
{
"path": "content.0.fieldMeta.type",
"code": "INVALID_VALUE",
"message": "fieldMeta.type is HTML, but the field type is TEXT. They must match."
}
]
}A content change on a document that isn't a DRAFT returns 409 INVALID_STATE. Disallowed HTML isn't an error: sajn removes it. For the error shape and every code, see Errors.
Next steps
Was this page helpful?
Last updated on