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"
            }
          ]
        }
      ]
    }
  ]
}

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"
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Sorting and Filtering Records in the REST API

Top Level Properties

data (object)

html (string)

preview (string)

Content Objects

Content Type Details

Paragraph Types

Rich Text

Mentions

Attachments

Date Pill

Tables

Heading

Block Quote

Horizontal Rule

Code Block

Images

Callout

Checklist

Table of Contents