The SmartDoc field contains rich text and formatting that requires a relatively complex JSON structure to represent. This article examines the structure of SmartDocs and discusses common formatting options and how to configure them when creating or updating SmartDoc fields via the SmartSuite REST API.
Top Level Properties
The SmartDoc object contains three top-level properties:
data (object)
The data object has two top-level properties.
type (string)
This property should always be set to “doc”content (array of content objects)
The content object holds information about the SmartDoc’s content and structure, and has a large array of configuration options. See the section on Content objects later in this document
html (string)
SmartDoc content in html format. This property can be omitted from create and update requests.
preview (string)
The first 500 text characters of the SmartDoc content. This property can be omitted from create and update requests.
Content Objects
Content objects specify the individual components of a SmartDoc. They can hold paragraphs of text, references to files and images, and much more.
Content Objects can have the following properties:
type (string) - Specifies the content type (see list below)
attrs (object) - Specifies type-specific details, such as the filename for attachments
content (array of content objects) - Type-specific content
Supported types:
paragraph types - Inserts text and other supported types into a paragraph, including:
text - paragraph with rich text
mentions - insert an @mention
attachment - inserts a file attachment
date_pill - inserts a date pill
table - Inserts a table
heading - Inserts heading text
blockquote - Inserts a quote block
horizontal_rule - Inserts a horizontal rule
code_block - Inserts a code block
image - Inserts an image
callout - Inserts a callout
check_list - Inserts a checklist
toc - Inserts a table of contents
Content Type Details
Paragraph Types
The paragraph type supports rich text, inserting @mentions, inserting attachments and inserting date pills.
Rich Text
Use the following properties to create a paragraph of text:
type (string):
"paragraph" - regular paragraph text
"paragraph_small" - small font paragraph text
attrs
textAlign (nullable string): left, center, right, or null
content
type (string): set this to "text"
marks (array of objects) - have the listed properties
type
code
"type": "code"
strong
"type": "strong"
em
"type": "em"
color
"type": "color"
"attrs": {
"color": "rgb(224,62,62)" <-- Color in RGB
}
highlight
"type": "highlight"
"attrs": {
"color": "rgb(224,62,62)" <-- Color in RGB
}
link
"type": "link"
"attrs": {
"href": "www.smartsuite.com"
}
attrs
color
href
text (string): the text for your paragraph
Example:
{
"type": "paragraph",
"attrs": {
"textAlign": null
},
"content": [
{
"type": "text",
"marks": [
{
"type": "color",
"attrs": {
"color": "rgb(224,62,62)"
}
}
],
"text": "Test"
}
]
}
Mentions
To insert an @mention, use the standard paragraph type and attrs properties, and then specify the following properties in the content object.
type (string): "mention"
attrs (object)
id (string): Unique Id of the mentioned SmartSuite Member
application (object)
id (string): Unique Id of the Workspace's Members application
name (string): "Members"
slug (string): "members"
title (string): display name of the mentioned Member
prefix: symbol to prefix name (generally "@")
Example:
"content": [
{
"type": "mention",
"attrs": {
"id": "62fe860fec9cc3b6b91272ad",
"application": {
"id": "62fe860fec9cc3b6b91272ab",
"name": "Members",
"slug": "members"
},
"title": "Peter Novosel",
"prefix": "@"
}
}
]
Attachments
You can read information about attachments from their content objects, but there is currently no way to create and upload a new attachment via the API. Here is a description of attachment properties:
type (string): "attachment"
attrs (object)
file (object)
handle (string): An internal system identifier for the file
metadata
container (string): internal value
filename (string): the original filename
key (string): a unique identifier for the stored file
mimetype (string): the mimetype of the file
size (int): the file size in bytes
transform_options (object): internal system transform information
author (int): an internal identifier for the creating user
security (object): internal system signatures for the file
file_type (string): the file's type
icon (string): a string indicating the filetype icon to be displayed
video_conversion_status (string): the file's video conversion status
video_thumbnail_handle (string): an internal id for the file's video thumbnail
converted_video_handle (nullable string): an internal id for the file's converted video file
Example:
"content": [
{
"type": "attachment",
"attrs": {
"file": {
"handle": "wsRhi2SaRpGQ1Ua8FWE8",
"metadata": {
"container": "smart-suite-media",
"filename": "Story Stats.xlsx",
"key": "A5ElHyRYR9CptzYAaZjv_Story Stats.xlsx",
"mimetype": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"size": 49565
},
"transform_options": {},
"author": 10368,
"security": {
"policy": "eyJjYWxsIjogWyJyZWFkIiwgImNvbnZlcnQiXSwgImV4cGlyeSI6IDE2NjEyODQ2NDIuODYzMzM4LCAiaGFuZGxlIjogIndzUmhpMlNhUnBHUTFVYThGV0U4IiwgIm1heFNpemUiOiA1MzY4NzA5MTIwfQ==",
"signature": "026d51049c7434c2963a2f9b26b3f33cce62411ad1c3c7fed58381b6fd4d1f08"
},
"file_type": "spreadsheet",
"icon": "xlsx",
"video_conversion_status": "none",
"video_thumbnail_handle": "",
"converted_video_handle": null
}
}
}
]
Date Pill
To insert a date pill, use the standard paragraph type and attrs properties, and then specify the following properties in the content object.
type (string): "date_pill"
attrs (object)
date (string): A date formatted as YYYY-MM-DD
Example:
"content": [
{
"type": "date_pill",
"attrs": {
"date": "2022-08-08"
}
}
]
Tables
To insert a table, use the standard paragraph type and attrs properties, and then specify the following properties in the content object.
type (string): "table"
content (object)
type (string): "table_row"
content
type (string): one of:
"table_header" - row formatted as a header
"table_row" - row formatted as content
attrs (object)
colspan (int): number of columns spanned
rowspan (int): number of rows spanned
colwidth (nullable int): column width in pixels, null indicates auto-sized columns
background (nullable string): color for background in RGB, e.g. "rgb(221,235,241)" or null for no background
content
(Any valid paragraph-type object)
Heading
Use the following properties to create text formatted as a heading:
type (string): "heading"
attrs
level (int): An integer with value in the range of 1 to 6, representing the header level (1 is largest, 6 is smallest)
id (test): A system-generated id for the heading (leave blank)
collapse: true for default collapsed section, false for expanded
textAlign (nullable string): left, center, right, or null
indentation (int): The level of indentation for the heading
content
type (string): set this to "text"
marks (array of objects)
type
code
"type": "code"
strong
"type": "strong"
em
"type": "em"
color
"type": "color"
"attrs": {
"color": "rgb(224,62,62)" <-- Color in RGB
}
highlight
"type": "highlight"
"attrs": {
"color": "rgb(224,62,62)" <-- Color in RGB
}
link
"type": "link"
"attrs": {
"href": "www.smartsuite.com"
}
attrs
color
href
content
type: set to "text"
text (string): the text for your heading
Example:
{
"type": "heading",
"attrs": {
"level": 6,
"id": "e8c3-fe6",
"collapse": false,
"textAlign": null,
"indentation": 0
},
"content": [
{
"type": "text",
"text": "Heading Small"
}
]
}
Block Quote
Use the following properties to create a quote block:
type (string): "blockquote"
attrs
textAlign (nullable string): left, center, right, or null
content
type (string): set this to "text"
marks (array of objects) - have the listed properties
type
code (object)
"type": "code"
strong (object)
"type": "strong"
em (object)
"type": "em"
color (object)
"type": "color"
"attrs": {
"color": "rgb(224,62,62)" <-- Color in RGB
}
highlight (object)
"type": "highlight"
"attrs": {
"color": "rgb(224,62,62)" <-- Color in RGB
}
link (object)
"type": "link"
"attrs": {
"href": "www.smartsuite.com"
}
text (string): the text for your block quote
Example:
{
"type": "blockquote",
"content": [
{
"type": "paragraph",
"attrs": {
"textAlign": "center"
},
"content": [
{
"type": "text",
"marks": [
{
"type": "code"
},
{
"type": "strong"
},
{
"type": "em"
},
{
"type": "color",
"attrs": {
"color": "rgb(224,62,62)"
}
},
{
"type": "highlight",
"attrs": {
"color": "rgb(235,236,237)"
}
},
{
"type": "link",
"attrs": {
"href": "www.google.com"
}
}
],
"text": "Foo"
}
]
}
]
}
Horizontal Rule
Use the following property to insert a horizontal rule.
type: "horizontal_rule"
Example:
{
"type": "horizontal_rule"
}
Code Block
Use the following properties to create a code block:
type (string): "code_block"
attrs (object)
language (string): the language represented in the code block, e.g. "javascript"
lineWrapping (boolean): true for line wrapping, false for no wrapping
content
type (string): "text"
text (string): text of the code block - new lines should be represented as \n and double-quotes should be \ escaped
Example:
{
"type": "code_block",
"attrs": {
"language": "javascript",
"lineWrapping": true
},
"content": [
{
"type": "text",
"text": "var myVar = \"test\";\n\n"
}
]
}
Images
You can read information about images from their properties, but there is currently no way to create and upload a new image via the API. Here is a description of image properties:
type (string): "image"
attrs (object)
file (object)
handle (string): An internal system identifier for the image
metadata
container (string): internal value
filename (string): the original filename
key (string): a unique identifier for the stored file
mimetype (string): the mimetype of the image
size (int): the image size in bytes
transform_options (object): internal system transform information
author (int): an internal identifier for the creating user
security (object): internal system signatures for the file
file_type (string): the file's type
icon (string): a string indicating the filetype icon to be displayed
video_conversion_status (string): the file's video conversion status
video_thumbnail_handle (string): an internal id for the file's video thumbnail
converted_video_handle (nullable string): an internal id for the file's converted video file
alignment (nullable string): left, center, right, or null
size (object)
width (int): image width in pixels
caption (string): text of the image's caption
Example:
{
"type": "image",
"attrs": {
"file": {
"handle": "OKoorlQPm9IjVa2T08xw",
"metadata": {
"container": "smartsuite-development-media",
"filename": "rose.png",
"key": "rwiMToONQamioYIgohVA_rose.png",
"mimetype": "image/png",
"size": 21166
},
"transform_options": {},
"author": 5,
"security": {
"policy": "eyJjYWxsIjogWyJyZWFkIiwgImNvbnZlcnQiXSwgImV4cGlyeSI6IDE2NjE0NTkzNDguNDQxNzc2LCAiaGFuZGxlIjogIk9Lb29ybFFQbTlJalZhMlQwOHh3IiwgIm1heFNpemUiOiA1MzY4NzA5MTIwfQ==",
"signature": "7083f7e45b4a28874cc96e0fb19442c795ce2a87ed9b551d8826d52fa91eaf89"
},
"file_type": "image",
"icon": "image",
"video_conversion_status": "none",
"video_thumbnail_handle": "",
"converted_video_handle": null
},
"alignment": "center",
"size": {
"width": 400
},
"caption": ""
}
}
Callout
Use the following properties to create a callout:
type (string): "callout"
attrs (object)
type (string): the type of callout
info
note
success
warning
error
decision
content (object)
(any valid paragraph-type object)
Example:
{
"type": "callout",
"attrs": {
"type": "warning"
},
"content": [
{
"type": "paragraph",
"attrs": {
"textAlign": null
},
"content": [
{
"type": "text",
"text": "Warning - danger Will Robinson!"
}
]
}
]
}
Checklist
Use the following properties to create a checklist:
type (string): "check_list"
content (array of checklist objects), which have the following properties:
type (string): "check_list_item"
attrs (object)
checked (boolean): true for checked, false for unchecked
content (array of objects)
any valid content object
Example:
{
"type": "check_list",
"content": [
{
"type": "check_list_item",
"attrs": {
"checked": true
},
"content": [
{
"type": "paragraph",
"attrs": {
"textAlign": null
},
"content": [
{
"type": "text",
"text": "Item 1"
}
]
}
]
},
{
"type": "check_list_item",
"attrs": {
"checked": false
},
"content": [
{
"type": "paragraph",
"attrs": {
"textAlign": null
},
"content": [
{
"type": "text",
"text": "Item 2"
}
]
}
]
}
]
}
Table of Contents
Use the following properties to create a table of contents:
type (string): "toc"
attrs (object)
expanded (boolean): true for expanded by default, false for collapsed by default
content (array of objects) - toc objects have the following properties
type (string): "bullet_list"
content (array of content objects)
Array of any valid paragraph-type objects
Note: "marks" object must contain the following object to identify the link to the header:
type (string): "link"
attrs (object)
href (string): Id of the heading prefixed with a hash symbol, e.g. "#6jehfqaq5k"
Example:
{
"type": "toc",
"attrs": {
"expanded": true
},
"content": [
{
"type": "bullet_list",
"content": [
{
"type": "list_item",
"content": [
{
"type": "paragraph",
"attrs": {
"textAlign": null
},
"content": [
{
"type": "text",
"marks": [
{
"type": "link",
"attrs": {
"href": "#6jehfqaq5k"
}
}
],
"text": "Heading 1"
}
]
},
{
"type": "bullet_list",
"content": [
{
"type": "list_item",
"content": [
{
"type": "paragraph",
"attrs": {
"textAlign": null
},
"content": [
{
"type": "text",
"marks": [
{
"type": "link",
"attrs": {
"href": "#adpdkzkydl"
}
}
],
"text": "Heading 2"
}
]
}
]
}
]
}
]
}
]
}
]
}