A SmartDoc field travels through the REST API as JSON. Its data object holds a content array of typed blocks, such as paragraphs, headings, tables and checklists.

It can also carry an html copy and a preview of the first 500 characters. Attachments and images are read-only through the API.

Example: a vendor risk team writes each vendor's review summary into a SmartDoc field from a script. The script sends a heading, a short paragraph and a checklist of follow-up tasks.

Plan Availability	All plan types. Every request counts toward the monthly API allowance: 25,000 on Team, 100,000 on Professional, 500,000 on Enterprise, custom on Signature.
Permissions	Any member with an API key. The key acts with that member's role and permissions.
Platform	API
Related Reading	SmartDoc Field Sorting and Filtering Records in the REST API Uploading and Downloading Files from the SmartSuite API API Overview: connect SmartSuite with the REST API.

Top-level properties

Property.	Required.	What it holds.
data.	Yes.	type, always "doc", and content, the array of content objects.
html.	No.	The content as HTML. You can leave it out when you create or update.
preview.	No.	The first 500 characters as plain text, for summaries.

Content objects

Each block in the content array is a content object with up to three keys:

type (string): the block type, such as "paragraph" or "table".
attrs (object): settings for that type, such as alignment or color.
content (array): the content objects nested inside, for blocks that hold other blocks.

Supported content types

Type.	Notes.
Text and paragraphs.	Rich text with styles, colors and links.
Mentions.	An @mention of a member.
Attachments.	File references. Read-only through the API.
Dates.	Date pills with a format.
Tables.	Header rows and body rows.
Headings.	Levels 1 to 6, with optional alignment.
Code blocks.	Code with syntax highlighting.
Images.	Stored images. Read-only through the API.
Callouts.	Highlighted blocks such as notes or warnings.
Checklists.	Items that can be checked.
Table of contents.	An index of the document's sections.

Example: a paragraph with colored text

{
  "type": "paragraph",
  "attrs": {
    "textAlign": "left"
  },
  "content": [
    {
      "type": "text",
      "marks": [
        {
          "type": "color",
          "attrs": {
            "color": "rgb(224,62,62)"
          }
        }
      ],
      "text": "Sample Text"
    }
  ]
}

Example: a mention

{
  "type": "mention",
  "attrs": {
    "id": "62fe860fec9cc3b6b91272ad",
    "application": {
      "id": "62fe860fec9cc3b6b91272ab",
      "name": "Members",
      "slug": "members"
    },
    "title": "John Doe",
    "prefix": "@"
  }
}

Example: a 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"
            }
          ]
        }
      ]
    }
  ]
}

In the vendor example, the follow-up tasks are a checklist like this one, with one item per task.

Example: a 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"
            }
          ]
        }
      ]
    }
  ]
}

Tip: Validate the JSON before you send it, and test nested blocks first. A table holds rows, and each row holds cells.

Frequently asked questions

Do I have to send the html property?

No. html is optional when you create or update. The data object is required.

Can I add an image or attachment to a SmartDoc through the API?

No. Attachments and images are read-only through the API. To add a file to a record, use the file upload endpoint. See Uploading and Downloading Files from the SmartSuite API.

What is the preview property for?

It holds the first 500 characters as plain text, so a list or a summary can show the start of the document.

Where are the SmartDoc endpoints?

In the SmartSuite developer documentation. A SmartDoc is a field value, so it is read and written with the record endpoints.

Need more help? Ask the SmartSuite Community, where builders, administrators and the SmartSuite team answer questions about building on SmartSuite. For your account, billing or data, select the chat button in the lower-right corner of SmartSuite to reach support.

Last verified 1 Nov 2026.

Structure of SmartDoc Objects