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.

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
bystring or objectId of user who created the record. With hydrated=true, an expanded member object (id, full_name, email) instead.
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
bystring or objectId of user who updated the record. With hydrated=true, an expanded member object (id, full_name, email) instead.
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_longitudestringAddress longitude, as a numeric string
location_latitudestringAddress latitude, as a numeric string
sys_rootstringConcatenated Address string
Example
"sd27e602f7": {
"location_address": "123 Main Street",
"location_address2": "",
"location_city": "Springfield",
"location_state": "Illinois",
"location_zip": "62701",
"location_country": "United States",
"location_longitude": "-94.76601199999999",
"location_latitude": "38.827365",
"sys_root": "123 Main Street, Springfield, Illinois, 62701, United States"
}

Checklist​

Manage a list of things that need to get done.

Object containing the following object literals

typevalue
items
array
idstringItem Id (UUID)
contentobjectSmartDoc object:

data

html

preview

completedbooleanWhether the item is completed
assigneestringMember Id of the assignee
due_datedateDue date
completed_atdatetimeWhen the item was completed, or null
total_items
number
Number of items
completed_items
number
Number of completed items
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": [
"jane.doe@example.com"
]
Example - multiple
"s9dc4f8924": [
"jane.doe@example.com",
"jane.doe@example.org"
]

Full Name​

Capture a person's full name and title.

Object containing the following object literals

keytypevalue
titlestring
  • "1" - Mr.
  • "2" - Mrs.
  • other values - 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": "Jane",
"middle_name": "N",
"last_name": "Doe",
"sys_root": "Mr. Jane Q Doe"
}

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.

Array of objects

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
valuestringId of the status value.
updated_ondatetimeDate Status field was last updated (ISO format).
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.
metadataobjectFile Metadata object (see below).
transform_optionsobjectNote: Always empty, this field is used internally by SmartSuite.
iconstringName of the SmartSuite icon displayed for the file, if one exists.
file_typestringShort file type (if known to SmartSuite).
created_ondatetimeDate file was added (ISO format).
updated_ondatetimeDate file was last updated (ISO format).
descriptionstringReserved 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": []
}