Skip to main content
All CollectionsAPI
Structure of SmartDoc Objects
Structure of SmartDoc Objects

Learn about working with SmartDoc objects in the SmartSuite REST API

Peter Novosel avatar
Written by Peter Novosel
Updated over a week ago

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

      • 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

      • 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)

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

Did this answer your question?