Skip to main content

Field Types and Properties

SmartSuite API Field Type Guide

This documents all of the currently supported SmartSuite field types and their corresponding value formats, as well as their option formats.

Notice

We may add more field types in the future and this will not be considered a breaking change. API consumers are expected to handle unknown field types gracefully. Further, object definitions are not meant to exhaustively describe the shape, new properties can be added and will not be considered a breaking change.

Field Types

  • Auto Number

System Field Formats

Auto Number

The automatically generated number associated with the record. These numbers are unique within the Table.

Note that this is a system field and is read only.

number

Example
"autonumber": 1

Record Id

A field that displays the record id.

Note that this is a system field and is read only.

string

Example
“record_id”: “6455294a7715e71aecd9c56a”

Application Slug

The application slug is used internally by SmartSuite

string

Example
"application_slug": "s4o4zlr7"

Application Id

A field that displays the record's Table (App) id.

Note that this is a system field and is read only.

string

Example
"application_id": "6418cd08b64e448d78141297"

First Created

The record creator and created date and time.

Note that this is a system field and is read only.

Object containing the following object literals

keytypevalue
bystringId of user who created the record
onDatetime in ISO formatDate record was created
Example
"first_created": {
"by": "63a1f65723aaf6bcb564b1f1",
"on": "2023-05-05T16:05:37.529000Z"
}

Followed By

List of Members by Id who are following the record.

array of strings

Example
"followed_by": []

Last Updated

The user who last updated the record, and the date and time of the update.

Note that this is a system field and is read only.

Object containing the following object literals

keytypevalue
bystringId of user who updated the record
ondatetimeDatetime (in ISO format) of last update
Example
"last_updated": {
"by": "63a1f65723aaf6bcb564b1f1",
"on": "2023-05-05T16:05:37.529000Z"
}

Deleted Date

Date the record was deleted.

Note that this is a system field and is read only. The “deleted_by” field is also set to the user id of the deleting user. Date property and deleted_by fields are null if not deleted.

Object containing the following object literals

keytypevalue
datedatetimeDate (ISO format) the record was deleted, null if not deleted.
include_timebooleanThis value is always true.
Example
    "deleted_date": {
"date": "2023-05-09T19:58:59.089000Z",
"include_time": true
},
"deleted_by": "63a1f65723aaf6bcb564b1f1"

Comments Count

Count of the open comments for the record.

int

Example
  "comments_count": 0

Text Field Formats

Address

An address that can be displayed on a map.

Object containing the following object literals

keytypevalue
location_addressstringAddress line 1
location_address2stringAddress line 2
location_citystringName of City
location_statestringName of State
location_zipstringZip/postal code
location_countrystringCountry
location_longitudenumberAddress longitude
location_latitudenumberAddress latitude
sys_rootstringConcatenated Address string
Example
"sd27e602f7": {
"location_address": "15549 West 166th Street",
"location_address2": "",
"location_city": "Olathe",
"location_state": "Kansas",
"location_zip": "66062",
"location_country": "United States",
"location_longitude": "-94.76601199999999",
"location_latitude": "38.827365",
"sys_root": "15549 West 166th Street, Olathe, Kansas, 66062, United States"
}

Checklist

Manage a list of things that need to get done.

Object containing the following object literals

typevalue
items
array
idnumber
contentobject

data

html

preview

completeddate
assigneedate
due_datedate
completed_atdate
due_datedate
total_itemsnumber
completed_itemsnumber
Example
"s1e50979f6": {
"items": [
{
"id": "483d963c-5454-4da0-a869-4043be0a4c69",
"content": {
"data": {
"type": "doc",
"content": [
{
"type": "paragraph",
"attrs": {
"textAlign": null
},
"content": [
{
"type": "text",
"text": "test"
}
]
}
]
},
"html": "<div class=\"rendered\">\n <p>test</p>\n</div>",
"preview": "test"
},
"completed": true,
"assignee": "63a1f65723aaf6bcb564b1f1",
"due_date": "2023-05-10",
"completed_at": "2023-05-09T16:21:03.892000Z"
},
{
"id": "6fe35a31-c69c-4120-af14-47b3ed692ec3",
"content": {
"data": {
"type": "doc",
"content": [
{
"type": "paragraph",
"attrs": {
"textAlign": null
},
"content": [
{
"type": "text",
"text": "test2"
}
]
}
]
},
"html": "<div class=\"rendered\">\n <p>test2</p>\n</div>",
"preview": "test2"
},
"completed": false,
"assignee": "63d43a8cab58a15ffdca6315",
"due_date": "2023-05-12",
"completed_at": null
}
],
"total_items": 2,
"completed_items": 1
}

Color Picker

Allow the selection of a color palette in HEX, RGB or CMYK formats.

Array of objects

keytypevalue
namestringColor name (optional)
valuestringColor hex value
Example - single
"s85fff4632": [
{
"name": "reddish",
"value": "#814C4C"
}
]
Example - multiple
    "s021a2cd98": [
{
"name": "",
"value": "#AB5F5F"
},
{
"name": "",
"value": "#4B1616"
}
]

Email

Allows a user to store email values. Allows to store multiple emails per field.

Array of strings

Example - single
"sdd0608960": [
"peter@smartsuite.com"
]
Example - multiple
"s9dc4f8924": [
"peter@smartsuite.com",
"peter.novosel@gmail.com"
]

Full Name

Capture a person's full name and title.

Object containing the following object literals

keytypevalue
titlenumber
  • 1 - Mr.
  • 2 - Mrs.
  • n - custom titles defined for the field
first_namestringFirst Name
middle_namestringMiddle Name
last_namestringLast Name
sys_rootstringFull (concatenated) name
Example
"sa60d0cace": {
"title": "1",
"first_name": "Peter",
"middle_name": "N",
"last_name": "Novosel",
"sys_root": "Mr. Peter N Novosel"
}

IP Address

Allows a user to store multiple IPv4/IPv6 values with country codes.

array of objects

keytypevalue
country_codestring2 character country code
addressstringIPv4 or IPv6 address
Example
         [{
"country_code": "",
"address": "127.0.0.0",
},{
"country_code": "us",
"address": "2001:0db8:11a3:09d7:1f34:8a2e:07a0:765d",
},{
"country_code": "",
"address": "::ffff:​127.0.0.1",
}
]

Allows a user to store link values. Allow to store multiple links per field.

Array of strings

Example - single
"s1a561b4ae": [
"www.smartsuite.com"
]
Example - multiple
"s093436126": [
"www.google.com",
"http://www.amazon.com"
]

Phone

Add one or more formatted phone numbers.

Object containing the following object literals

keytypevalue
Phone_countrystringCountry code
Phone_numberstringPhone number
Phone_extensionstringExtension
Phone_typenumber

phone number type:

  • 1 = office
  • 2 = mobile
  • 4 = home
  • 5 = fax
  • 8 = other
Sys_rootstringUnformatted phone number
Sys_titlestringFormatted phone number
Example - single
"s4209c693e": [
{
"phone_country": "US",
"phone_number": "913 555 1212",
"phone_extension": "",
"phone_type": 1,
"sys_root": "19135551212",
"sys_title": "+1 913 555 1212"
}
]
Example - multiple
"s87hf1a0": [
{
"phone_country": "US",
"phone_number": "913 555 1212",
"phone_extension": "",
"phone_type": 1,
"sys_root": "19135551212",
"sys_title": "+1 913 555 1212"
},
{
"phone_country": "US",
"phone_number": "708 555 1111",
"phone_extension": "",
"phone_type": 1,
"sys_root": "17085551111",
"sys_title": "+1 708 555 1111"
}

Record Title (Primary Field)

System field that contains the title of a record, also known as the primary field.

Note that Record Titles that are set to Auto-Generated are read only. Values sent in record creates or updates for Auto-Generated Titles are ignored without generating an error.

string

Example
"title": "My Record"

SmartDoc

Create entire documents that combine free-form rich text, multimedia and much more.

The SmartDoc data structure is described in a separate page.

Object containing the following object literals

keytypevalue
dataobjectSmartDoc Object
htmlstringHTML representation of the SmartDoc's content
previewstringText representation of the SmartDoc's content
Example
    "s325d95fa1": {
"data": {
"type": "doc",
"content": [
{
"type": "paragraph",
"attrs": {
"textAlign": null
},
"content": [
{
"type": "text",
"text": "Hello "
},
{
"type": "text",
"marks": [
{
"type": "strong"
}
],
"text": "world"
}
]
}
]
},
"html": "<div class=\"rendered\">\n <p>Hello <strong>world</strong></p>\n</div>",
"preview": "Hello <strong>world</strong>"
}

Social Network

Add links to one or more social networks.

Object containing the following object literals

keytypevalue
Facebook_usernamestringFacebook username
twitter_usernamestringTwitter username
instagram_usernamestringInstagram username
linkedin_usernamestringLinkedIn username
Example
"s284633643": {
"facebook_username": "myuser",
"twitter_username": "",
"instagram_username": "",
"linkedin_username": ""
}

Text Area

Add text that can span multiple lines.

Note

Use \n for line breaks.

string

Example
"sa1dd2f880": "test\n123\ntesting 1,2,3..."

Text

Add a single line of text like a name or a title.

string

Example
"sa1dd2f880": "Hello World!"

Date Field Formats

Date

Add a date with an option to include time.

Date Object containing the following object literals

keytypevalue
datedatetimeDate in ISO format
include_timebooleanIndicate whether time is to be included in the date’s display
Example
"sb4c5ca5fc": {
"date": "2023-05-09T06:00:00Z",
"include_time": true
}

Date Range

Add a date range.

Date Range Object containing the following object literals

keytypevalue
from_datedate objectStarting date of the range
to_datedate objectEnd date of the range
Example
"sd8f20e21a": {
"from_date": {
"date": "2023-05-09T00:00:00Z",
"include_time": false
},
"to_date": {
"date": "2023-05-12T00:00:00Z",
"include_time": false
}
}

Due Date

Visually track and manage due dates.

Object containing the following object literals

keytypevalue
from_datedate objectStart date (optional)
to_datedate objectDue date
is_overduebooleanTrue if overdue (read-only)
status_is_completedbooleanTrue if complete (read-only)
status_updated_ondatetimeDate that the due date's linked status field was last updated (read-only)
Example
"s1a23f61ca": {
"from_date": {
"date": null,
"include_time": false
},
"to_date": {
"date": "2023-05-12T00:00:00Z",
"include_time": false
},
"is_overdue": false,
"status_is_completed": false,
"status_updated_on": "2023-05-09T19:25:04.981000Z"
}

Duration

Track a time duration in days, hours and minutes.

Note

Duration values are in seconds.

Number as text

Example
"s3031d9687": "94530.0"

Time

Add a specific time.

Note

Time is reflected in 24 hour format.

string

Example
"sff346911b": "21:15:00"

Time Tracking Log

Track time spent working on a specific task or project.

Object containing the following object literals

keytypevalue
time_track_logsarray of time log objectsIndividual time entries
total_durationnumberTotal time in seconds

Time Log Object

Object containing the following object literals

keytypevalue
user_idstringId of the Member associated with the log entry
date_timedatetimeDate and time of entry
durationnumberDuration in seconds
time_rangedate range object

Time range for the event (nullable)

Note: The include_time property should always be set to true

notestringNote text attached to the time entry.
Example
"s09ca45598": {
"time_track_logs": [
{
"user_id": "63a1f65723aaf6bcb564b1f1",
"date_time": "2023-05-09T19:46:16.751000Z",
"duration": 45000,
"time_range": null,
"timer_start": null,
"note": "test note"
},
{
"user_id": "63a1f65723aaf6bcb564b1f1",
"date_time": "2023-05-09T19:47:04.470000Z",
"duration": 3600,
"time_range": null,
"timer_start": null,
"note": ""
},
{
"user_id": "63a1f65723aaf6bcb564b1f1",
"date_time": "2023-05-09T19:50:29.930000Z",
"duration": 20400,
"time_range": {
"from_date": {
"date": "2023-05-09T19:50:00Z",
"include_time": true
},
"to_date": {
"date": "2023-05-10T01:30:00Z",
"include_time": true
}
},
"timer_start": null,
"note": ""
},
{
"user_id": "63a1f65723aaf6bcb564b1f1",
"date_time": "2023-05-09T19:50:29.930000Z",
"duration": 21,
"time_range": {
"from_date": {
"date": "2023-05-09T19:50:50.391000Z",
"include_time": true
},
"to_date": {
"date": "2023-05-09T19:51:11.496000Z",
"include_time": true
}
},
"timer_start": "2023-05-09T19:50:50.391000Z",
"note": ""
}
],
"total_duration": 69021
}

Number Field Formats

Currency

Add a number that is displayed with currency formatting.

number as string

Example
"s584654fd2": "19.95"

Number

Add a number with optional formatting.

number as string

Example
"s6878322bd": "120"

Number Slider

Select a number within a range using a numeric slider.

Note

Specifying a number above the maximum value will set the maximum value, and specifying a number below the minimum value will set the minimum value. If a value increment is set, the value will be set to the nearest increment.

number

Example
 "s35edcfdbc": 59

Percent Complete

Track a completion percentage using a graphical slider.

Note

Specifying a number above the maximum value will set the maximum value, and specifying a number below the minimum value will set the minimum value. If a value increment is set, the value will be set to the nearest increment.

number

Example
"sd5758e92c": 72

Percent

Add a number that is displayed as a percentage.

number as a string

Example
"s95338b75f": "42"

Rating

Add a visual rating using a scale of your choice.

Note

Specifying a number above the maximum value will set the maximum value, and specifying a number below the minimum value will set the minimum value. If a value increment is set, the value will be set to the nearest increment.

number

Example
 "s239cbad2a": 4

Vote

Allow team members to vote on things like feature requests.

Object containing the following object literals

keytypevalue
total_votesnumberTotal votes for the record
votesarray of vote objectsIndividual votes

Vote Object

Object containing the following object literals

keytypevalue
user_idstringMember Id of the voter
datestringDate of the vote in YYYY-MM-DD format
Example

"sacb0b6750": {
"total_votes": 1,
"votes": [
{
"user_id": "63a1f65723aaf6bcb564b1f1",
"date": "2023-05-09"
}
]
}

List Field Formats

Multiple Select

Add a list where multiple choices can be selected.

array of strings

Strings are the ids of individual list items.

Example
    "s710a06b7f": [
"120ed618-06bb-4acd-8880-05a0cea3e415",
"1da865e2-48a6-4e1a-9158-de51cdf9f6b7",
"0612b2a5-068e-450f-b850-703dfa1b1b9e"
]

Single Select

Add a list where only one choice can be selected.

string

String is the id of the selected list item.

Example
"se799fd212": "ace70ec5-b046-4ba6-80b8-cf39b6390fd6"

Status

Track the overall status of things like tasks, activities or projects.

Object containing the following object literals

keytypevalue
value
string
Id of the status value.
updated_on
Datetime in ISO format
Date Status field was last updated.
Example

"s63d179f79": {
"value": "backlog",
"updated_on": "2023-05-09T22:58:48.291000Z"
}

Tag

Allows a user to select tags from the list of tags.

Note

If a Tags Field is private, its tags are available to all private Tags Fields within a solution. If it's public, then every public field within an account can access its tags.

array of strings

String is the id of the selected tag.

Example
    "sccb7d6601": [
"645acfd07bb0b8858a01bf30",
"645acfd07bb0b8858a01bf31",
"645acfe3de5fba70e93c6e02",
"645acfe3de5fba70e93c6e03"
]

Yes / No

Field type that is used to represent a selected / non selected state.

Boolean

Example
"s227a7b29a": true

Reference Field Formats

Assigned To

Assign a Member or Members to a record.

array of strings

Note

Assigned To fields configured for either single and multiple values return an array.

Example
"assigned_to": [
"63a1f65723aaf6bcb564b1f1"
]

Button

Create a button that triggers an action.

string

Note

Buttons configured with a static URL will always return null. Dynamic buttons will return the generated URL value.

Example
"s9d2ba74c3": "https://www.fakesite.com?id=test"

Linked Record

Add a link to a record or records in another Table.

array of strings

Note

Linked Record fields configured for either single and multiple values return an array.

Example
"s570c86b38": [
"6455294a7715e71aecd9c56a",
"645c1dee9f83b887865d99ec"
]

File Field Formats

Files and Images

Get information about the files attached to a Files and Images field.

Note

This endpoint cannot be used to attach files to the record. Please refer to this article for information on uploading and downloading file data.

array of file objects which contain the following object literals

keytypevalue
handlestringThe file handle, which can be used to retrieve the file’s data.
metadataobject

transform_options object Note: Always empty, this field is used internally by SmartSuite. icon string Name of the SmartSuite icon displayed for the file, if one exists. file_type string Short file type (if known to SmartSuite). created_on ISO date Date file was added. updated_on ISO date Date file was last updated. description string Reserved for future use (attaching a note to the file/image).

File Metadata object

Object containing file information.

keytypevalue
containerstringSmartSuite internal use
filenamestringName of the file
keystringSmartSuite internal use
mimetypestringMIME type of the file
sizenumberSize of the file in bytes
Example
"see6d6120d": [
{
"handle": "a4d988eCTCKZ62XMqUIj",
"metadata": {
"container": "smart-suite-media",
"filename": "image (48).png",
"key": "wK07pocQeibIB7oSWMya_image (48).png",
"mimetype": "image/png",
"size": 51443
},
"transform_options": {},
"icon": "image",
"file_type": "image",
"created_on": "2023-05-11T15:15:37.263000Z",
"updated_on": "2023-05-11T15:15:37.263000Z",
"description": ""
}
]

Signature

object containing the following object literals

keytypevalue
textstringText entered as signature. Empty string if signature was drawn.
image_base64stringBase64-encoded drawn image data, null if text was entered as signature.
Example
"s67210aeb8": {
"text": null,
"image_base64": "data:image/png;base64,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",
"drawing": []
}