Learn how to create, update, and manage SmartDoc objects in the SmartSuite REST API. This guide explains the JSON structure of SmartDocs and how to work with various content types and formatting options.
Plan Availability | All plan types |
Permissions | Solution Creators: Can manage and update SmartDoc fields in their Solutions. |
Related Reading |
Overview
SmartDocs are fields in SmartSuite that support rich text and complex formatting. These are represented in JSON with a structured hierarchy of properties and objects.
Top-Level Properties
A SmartDoc object consists of three main properties:
1. data
Defines the core structure of the SmartDoc, with these key elements:
type(string): Always set to"doc".content(array): Contains the content objects (see below for details).
2. html
(Optional) Contains the SmartDoc content in HTML format. Can be omitted during creation or updates.
3. preview
(Optional) Provides the first 500 characters of the SmartDoc content as plain text. Useful for summaries or previews.
Content Objects
Content objects are the building blocks of SmartDocs. They can represent text, images, tables, and more.
Properties of Content Objects:
type(string): Specifies the type of content (e.g.,"paragraph","table").attrs(object): Holds type-specific attributes (e.g., alignment, color).content(array): Nested content objects for composite elements.
Supported Content Types:
Text and Paragraphs: Rich text with support for styles, colors, and links.
Mentions: Tagging SmartSuite members using
@mention.Attachments: File references (read-only for API use).
Dates: Insert date pills with specific formatting.
Tables: Create tables with headers and rows.
Headings: Define headings with levels (1–6) and optional alignment.
Code Blocks: Add code snippets with syntax highlighting.
Images: Reference stored images (read-only for API use).
Callouts: Highlight information with styles like warnings or notes.
Checklists: Create interactive lists with checkable items.
Table of Contents (TOC): Generate an index of document sections.
Example JSON Structures
Paragraph with Rich Text
{ "type": "paragraph", "attrs": { "textAlign": "left" }, "content": [ { "type": "text", "marks": [ { "type": "color", "attrs": { "color": "rgb(224,62,62)" } } ], "text": "Sample Text" } ] }
Mention a Member
{ "type": "mention", "attrs": { "id": "62fe860fec9cc3b6b91272ad", "application": { "id": "62fe860fec9cc3b6b91272ab", "name": "Members", "slug": "members" }, "title": "John Doe", "prefix": "@" } }
Checklist
{ "type": "check_list", "content": [ { "type": "check_list_item", "attrs": { "checked": false }, "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Task 1" } ] } ] }, { "type": "check_list_item", "attrs": { "checked": true }, "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Task 2" } ] } ] } ] }
Table
{ "type": "table", "content": [ { "type": "table_row", "content": [ { "type": "table_header", "content": [ { "type": "text", "text": "Column 1" } ] }, { "type": "table_header", "content": [ { "type": "text", "text": "Column 2" } ] } ] }, { "type": "table_row", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Row 1 Data" } ] }, { "type": "paragraph", "content": [ { "type": "text", "text": "Row 2 Data" } ] } ] } ] }
Practical Scenarios and Use Cases
1. Creating a Task Description
Scenario: You want to add a detailed description with text formatting to a task.
Solution: Use a "paragraph" type with rich text and formatting like bold or color.
2. Generating Meeting Notes
Scenario: You want a document with headings, bullet points, and a table of contents.
Solution: Combine "heading", "bullet_list", and "toc" types.
3. Adding Attachments to Reports
Scenario: A report requires a linked Excel file.
Solution: Use the "attachment" type to reference the file.
Tips for Working with SmartDoc Objects
Ensure Valid JSON: Double-check JSON syntax to avoid errors.
Use Appropriate Types: Select the content type that matches your desired output.
Test Nested Structures: Complex content like tables may require nested content objects.
For further details, visit SmartSuite API Documentation.