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.
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
"autonumber": 1
Record Id
A field that displays the record id.
Note that this is a system field and is read only.
string
“record_id”: “6455294a7715e71aecd9c56a”
Application Slug
The application slug is used internally by SmartSuite
string
"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
"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
key | type | value |
---|---|---|
by | string | Id of user who created the record |
on | Datetime in ISO format | Date record was created |
"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
"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
key | type | value |
---|---|---|
by | string | Id of user who updated the record |
on | datetime | Datetime (in ISO format) of last update |
"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
key | type | value |
---|---|---|
date | datetime | Date (ISO format) the record was deleted, null if not deleted. |
include_time | boolean | This value is always true. |
"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
"comments_count": 0
Text Field Formats
Address
An address that can be displayed on a map.
Object containing the following object literals
key | type | value |
---|---|---|
location_address | string | Address line 1 |
location_address2 | string | Address line 2 |
location_city | string | Name of City |
location_state | string | Name of State |
location_zip | string | Zip/postal code |
location_country | string | Country |
location_longitude | number | Address longitude |
location_latitude | number | Address latitude |
sys_root | string | Concatenated Address string |
"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
type | value | ||
---|---|---|---|
itemsarray | id | number | |
content | object | data html preview | |
completed | date | ||
assignee | date | ||
due_date | date | ||
completed_at | date | ||
due_date | date | ||
total_items | number | ||
completed_items | number |
"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
key | type | value |
---|---|---|
name | string | Color name (optional) |
value | string | Color hex value |
"s85fff4632": [
{
"name": "reddish",
"value": "#814C4C"
}
]
"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
"sdd0608960": [
"peter@smartsuite.com"
]
"s9dc4f8924": [
"peter@smartsuite.com",
"peter.novosel@gmail.com"
]
Full Name
Capture a person's full name and title.
Object containing the following object literals
key | type | value |
---|---|---|
title | number |
|
first_name | string | First Name |
middle_name | string | Middle Name |
last_name | string | Last Name |
sys_root | string | Full (concatenated) name |
"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
key | type | value |
---|---|---|
country_code | string | 2 character country code |
address | string | IPv4 or IPv6 address |
[{
"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",
}
]
Link
Allows a user to store link values. Allow to store multiple links per field.
Array of strings
"s1a561b4ae": [
"www.smartsuite.com"
]
"s093436126": [
"www.google.com",
"http://www.amazon.com"
]
Phone
Add one or more formatted phone numbers.
Object containing the following object literals
key | type | value |
---|---|---|
Phone_country | string | Country code |
Phone_number | string | Phone number |
Phone_extension | string | Extension |
Phone_type | number | phone number type:
|
Sys_root | string | Unformatted phone number |
Sys_title | string | Formatted phone number |
"s4209c693e": [
{
"phone_country": "US",
"phone_number": "913 555 1212",
"phone_extension": "",
"phone_type": 1,
"sys_root": "19135551212",
"sys_title": "+1 913 555 1212"
}
]
"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
"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
key | type | value |
---|---|---|
data | object | SmartDoc Object |
html | string | HTML representation of the SmartDoc's content |
preview | string | Text representation of the SmartDoc's content |
"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
key | type | value |
---|---|---|
Facebook_username | string | Facebook username |
twitter_username | string | Twitter username |
instagram_username | string | Instagram username |
linkedin_username | string | LinkedIn username |
"s284633643": {
"facebook_username": "myuser",
"twitter_username": "",
"instagram_username": "",
"linkedin_username": ""
}
Text Area
Add text that can span multiple lines.
Use \n for line breaks.
string
"sa1dd2f880": "test\n123\ntesting 1,2,3..."
Text
Add a single line of text like a name or a title.
string
"sa1dd2f880": "Hello World!"
Date Field Formats
Date
Add a date with an option to include time.
Date Object containing the following object literals
key | type | value |
---|---|---|
date | datetime | Date in ISO format |
include_time | boolean | Indicate whether time is to be included in the date’s display |
"sb4c5ca5fc": {
"date": "2023-05-09T06:00:00Z",
"include_time": true
}
Date Range
Add a date range.
Date Range Object containing the following object literals
key | type | value |
---|---|---|
from_date | date object | Starting date of the range |
to_date | date object | End date of the range |
"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
key | type | value |
---|---|---|
from_date | date object | Start date (optional) |
to_date | date object | Due date |
is_overdue | boolean | True if overdue (read-only) |
status_is_completed | boolean | True if complete (read-only) |
status_updated_on | datetime | Date that the due date's linked status field was last updated (read-only) |
"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.
Duration values are in seconds.
Number as text
"s3031d9687": "94530.0"
Time
Add a specific time.
Time is reflected in 24 hour format.
string
"sff346911b": "21:15:00"
Time Tracking Log
Track time spent working on a specific task or project.
Object containing the following object literals
key | type | value |
---|---|---|
time_track_logs | array of time log objects | Individual time entries |
total_duration | number | Total time in seconds |
Time Log Object
Object containing the following object literals
key | type | value |
---|---|---|
user_id | string | Id of the Member associated with the log entry |
date_time | datetime | Date and time of entry |
duration | number | Duration in seconds |
time_range | date range object | Time range for the event (nullable) Note: The include_time property should always be set to true |
note | string | Note text attached to the time entry. |
"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
"s584654fd2": "19.95"
Number
Add a number with optional formatting.
number as string
"s6878322bd": "120"
Number Slider
Select a number within a range using a numeric slider.
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
"s35edcfdbc": 59
Percent Complete
Track a completion percentage using a graphical slider.
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
"sd5758e92c": 72
Percent
Add a number that is displayed as a percentage.
number as a string
"s95338b75f": "42"
Rating
Add a visual rating using a scale of your choice.
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
"s239cbad2a": 4
Vote
Allow team members to vote on things like feature requests.
Object containing the following object literals
key | type | value |
---|---|---|
total_votes | number | Total votes for the record |
votes | array of vote objects | Individual votes |
Vote Object
Object containing the following object literals
key | type | value |
---|---|---|
user_id | string | Member Id of the voter |
date | string | Date of the vote in YYYY-MM-DD format |
"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.
"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.
"se799fd212": "ace70ec5-b046-4ba6-80b8-cf39b6390fd6"
Status
Track the overall status of things like tasks, activities or projects.
Object containing the following object literals
key | type | value |
---|---|---|
value | ||
string | ||
Id of the status value. | ||
updated_on | ||
Datetime in ISO format | ||
Date Status field was last updated. |
"s63d179f79": {
"value": "backlog",
"updated_on": "2023-05-09T22:58:48.291000Z"
}
Tag
Allows a user to select tags from the list of tags.
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.
"sccb7d6601": [
"645acfd07bb0b8858a01bf30",
"645acfd07bb0b8858a01bf31",
"645acfe3de5fba70e93c6e02",
"645acfe3de5fba70e93c6e03"
]
Yes / No
Field type that is used to represent a selected / non selected state.
Boolean
"s227a7b29a": true
Reference Field Formats
Assigned To
Assign a Member or Members to a record.
array of strings
Assigned To fields configured for either single and multiple values return an array.
"assigned_to": [
"63a1f65723aaf6bcb564b1f1"
]
Button
Create a button that triggers an action.
string
Buttons configured with a static URL will always return null. Dynamic buttons will return the generated URL value.
"s9d2ba74c3": "https://www.fakesite.com?id=test"
Linked Record
Add a link to a record or records in another Table.
array of strings
Linked Record fields configured for either single and multiple values return an array.
"s570c86b38": [
"6455294a7715e71aecd9c56a",
"645c1dee9f83b887865d99ec"
]
File Field Formats
Files and Images
Get information about the files attached to a Files and Images field.
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
key | type | value |
---|---|---|
handle | string | The file handle, which can be used to retrieve the file’s data. |
metadata | object |
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.
key | type | value |
---|---|---|
container | string | SmartSuite internal use |
filename | string | Name of the file |
key | string | SmartSuite internal use |
mimetype | string | MIME type of the file |
size | number | Size of the file in bytes |
"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
key | type | value |
---|---|---|
text | string | Text entered as signature. Empty string if signature was drawn. |
image_base64 | string | Base64-encoded drawn image data, null if text was entered as signature. |
"s67210aeb8": {
"text": null,
"image_base64": "data:image/png;base64,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",
"drawing": []
}