Go to section:
The SmartSuite REST API gives you the ability to retrieve record data with the /records/list/ endpoint. The reason that this endpoint accepts POST requests (typically GET is used for retrieval) is that the body of the request can contain JSON representing sort and filter instructions for the request.
NOTE:
SmartSuite does not consider adding keys to response objects as breaking changes, so the shape of objects may change without notice. Existing keys will not be removed without a deprecation warning and timeframe.
Authorization
Just like other REST API endpoints, SmartSuite uses token-based authentication for record requests. You can generate or manage your API key in your User Profile. All API requests must be authenticated and made over HTTPS.
IMPORTANT! Your API key conveys the same privileges as the Member account it is generated in, so it should be treated as securely as a password.
You authenticate to the API by providing your API key in the Authorization header, as well as your Workspace Id in an Account-Id header, as shown below.
KEY:VALUE
Authorization: Token API_KEY_HEREAccount-Id: WORKSPACE_ID_HERE
NOTE: Your Workspace Id is the 8 characters that follow https://app.smartsuite.com/ in the SmartSuite URL when you’re logged in.
Example: https://app.smartsuite.com/sv25cxf2/solution/62c4b…
Retrieving Records
There are two ways to retrieve records in the SmartSuite API:
Retrieve a single record
You can use the following endpoint to retrieve a single record:
GET https://app.smartsuite.com/api/v1/applications/[App Id]/records/[Record Id]/
This endpoint does not accept any sorting or filtering parameters, as a single record is retrieved per call.
Retrieve a list of records
This endpoint retrieves a list of records from SmartSuite:
POST https://app.smartsuite.com/api/v1/applications/[App Id]/records/list/
[App Id] is the App’s unique id
This endpoint supports sort and filter directives that are specified in the JSON body.
Note: You should set Content-Type to application/JSON when including sort and filter JSON as part of your request.
Specifying Sort and Filter Parameters
Both sort and filter parameters are specified in the body of the POST request, and must be formatted as valid JSON.
Sorting and filtering can be specified independently, or can be combined in the request. Here is an example of a JSON structure that includes a sort and a filter:
{
"filter": {
"operator": "and",
"fields": [
{
"field": "title",
"comparison": "is_not_empty",
"value": ""
}
]
},
"sort": [
{
"field": "title",
"direction": "asc"
}
]
}
Sort Syntax
The syntax for sort is simple - you specify a key value of "sort" and a value that is an array of sort objects. Each sort object contains two JSON object literals:
field: the field id ("slug" value) to perform the sort on
direction: direction of the sort, which varies by field type
You can include multiple sorts in the array. The sort should be returned as an array even if you are sorting by a single field.
Example of a single sort:
"sort": [
{
"field": "title",
"direction": "desc"
}
]
Example of multiple sorts:
"sort": [
{
"field": "title",
"direction": "asc"
},
{
"field": "s228acd4ea",
"direction": "desc"
}
]
Multiple sorts are applied in the order specified, so in the above example the records would first be sorted by title and then by the field with id s228acd4ea.
Filter Syntax
Filter syntax resembles sort syntax as it consists of a key value "filter" which contains a filter object. The filter object contains a JSON literal with key "operator" that has a string value, and a second JSON literal with key "fields" that has an array of field objects as its value.
operator: Valid operators include:
and - requires all specified filters to match
or - requires at least one filter specified filter to match
fields: An array of Filter objects that have the following JSON literals:
field - the field id ("slug")
comparison - the comparison operator, which varies by field type
value - the value to compare, the format of which depends on field type being filtered
Note: The operator is required in the request body even if only a single filter is being applied, with a value of and or or being specified (both return the same records).
Example of an and filter:
"filter": {
"operator": "and",
"fields": [
{
"field": "status",
"comparison": "is_not",
"value": "Complete"
},
{
"field": "s251d4318b",
"comparison": "is_equal_to",
"value": 0
}
]
}
Filter Values
The value you pass in the filter corresponds to the field's type:
Text Type. Pass a double-quote enclosed string to the filter
Number Type. Pass a number or a number enclosed in quotes (number as string is interpreted properly)
Date Type. Pass a Date Value Object (see below)
Date Value Object
Dates differ from string and number type fields in that they require passing a Date Value Object as their value. They have two JSON literals:
date_mode
date_mode_value
"value": {
"date_mode": "exact_date",
"date_mode_value": "2023-02-01"
}
See the Date Modes and Values section below for more details.
Operators by Field Type
The following table lists the valid sort and filter options by field type. A few notes:
For filters that do not require a value, specify null or an empty string "" for the value
The field "Type" is the name for the field type in the SmartSuite API. It is used when creating or modifying fields using the API.
Filter options are case sensitive. Ex: "is_not_empty" is valid while "Is_Not_Empty" isn't.
Field | Sort Options | Filter Options |
Name: Text Type: textfield | asc desc | is is_not is_empty is_not_empty contains not_contains |
Name: Address Type: addressfield
Operations applied to the full string version of concatenated address | asc desc | is is_not is_empty is_not_empty contains not_contains |
Name: Checklist Type: checklistfield | asc desc | is_empty is_not_empty |
Name: Color Picker Type: colorpickerfield | asc desc | is is_not is_empty is_not_empty contains not_contains |
Name: Email Type: emailfield | asc desc | is is_not is_empty is_not_empty contains not_contains |
Name: Full Name Type: fullnamefield | asc desc | is is_not is_empty is_not_empty contains not_contains |
Name: IP Address Type: ipaddressfield | asc desc | is is_not is_empty is_not_empty contains not_contains |
Name: Link Type: linkfield | asc desc | is is_not is_empty is_not_empty contains not_contains |
Name: Phone Type: phonefield | asc desc | is is_not is_empty is_not_empty contains not_contains |
Name: Phone Type: phonefield | asc desc | is is_not is_empty is_not_empty contains not_contains |
Name: Record Title Type: recordtitlefield | asc desc | is is_not is_empty is_not_empty contains not_contains |
Name: SmartDoc Type: richtextareafield | asc desc | is_empty is_not_empty |
Name: Social Network Type: socialnetworkfield | asc desc | is is_not is_empty is_not_empty contains not_contains |
Name: Text Area Type: textareafield | asc desc | is is_not is_empty is_not_empty contains not_contains |
Name: Currency Type: currencyfield | asc desc | is_equal_to is_not_equal_to is_greater_than is_less_than is_equal_or_greater_than is_equal_or_less_than is_empty is_not_empty |
Name: Number Type: numberfield | asc desc | is_equal_to is_not_equal_to is_greater_than is_less_than is_equal_or_greater_than is_equal_or_less_than is_empty is_not_empty |
Name: Number Slider Type: numbersliderfield | asc desc | is_equal_to is_not_equal_to is_greater_than is_less_than is_equal_or_greater_than is_equal_or_less_than is_empty is_not_empty |
Name: Percent Complete Type: percentcompletefield | asc desc | is_equal_to is_not_equal_to is_greater_than is_less_than is_equal_or_greater_than is_equal_or_less_than is_empty is_not_empty |
Name: Percent Complete Type: percentcompletefield | asc desc | is_equal_to is_not_equal_to is_greater_than is_less_than is_equal_or_greater_than is_equal_or_less_than is_empty is_not_empty |
Name: Percent Type: percentfield | asc desc | is_equal_to is_not_equal_to is_greater_than is_less_than is_equal_or_greater_than is_equal_or_less_than is_empty is_not_empty |
Name: Rating Type: ratingfield | asc desc | is_equal_to is_not_equal_to is_greater_than is_less_than is_equal_or_greater_than is_equal_or_less_than is_empty is_not_empty |
Name: Vote Type: votefield | asc desc | is_equal_to is_not_equal_to is_greater_than is_less_than is_equal_or_greater_than is_equal_or_less_than is_empty is_not_empty |
Name: Count Type: countfield | asc desc | is_equal_to is_not_equal_to is_greater_than is_less_than is_equal_or_greater_than is_equal_or_less_than is_empty is_not_empty |
Name: Single Select Type: singleselectfield | asc desc | is is_not is_any_of is_none_of is_empty is_not_empty |
Name: Multiple Select Type: multipleselectfield | asc desc | has_any_of has_all_of is_exactly has_none_of is_empty is_not_empty |
Name: Status Type: statusfield | asc desc | is is_not is_any_of is_none_of is_empty is_not_empty |
Name: Tag Type: tagsfield | asc desc | has_any_of has_all_of is_exactly has_none_of is_empty is_not_empty |
Name: Yes / No Type: yesnofield | asc desc | is |
Name: Date Type: datefield | asc desc | is is_not is_before is_on_or_before is_on_or_after is_empty is_not_empty |
Name: Date Range Type: datefield
Note: You have to refer to the two dates in date range in this way:
[Field Slug].from_date [Field Slug].to_date | asc desc | is is_not is_before is_on_or_before is_on_or_after is_empty is_not_empty |
Name: Due Date Type: duedatefield | asc desc | is is_not is_before is_on_or_before is_on_or_after is_empty is_not_empty is_overdue is_not_overdue |
Name: Duration Type: durationfield | asc desc | is_equal_to is_not_equal_to is_greater_than is_less_than is_equal_or_greater_than is_equal_or_less_than is_empty is_not_empty |
Name: Time Type: timefield | asc desc | is_equal_to is_not_equal_to is_greater_than is_less_than is_equal_or_greater_than is_equal_or_less_than is_empty is_not_empty |
Name: Time Tracking Log Type: timetrackingfield | asc desc | is_equal_to is_not_equal_to is_greater_than is_less_than is_equal_or_greater_than is_equal_or_less_than is_empty is_not_empty |
Name: Formula Type: formulafield | asc desc | Formula can be filtered with operators that correspond to it's return type.
Use the operators for Text, Number or Date based on the type it returns. |
Name: Lookup Type: lookupfield | asc desc | Lookup can be filtered with the operators available to its target field type. |
Name: Rollup Type: rollupfield | asc desc | is_equal_to is_not_equal_to is_greater_than is_less_than is_equal_or_greater_than is_equal_or_less_than is_empty is_not_empty |
Name: Files & Images Type: filefield | asc desc | file_name_contains file_type_is is_empty is_not_empty
Valid file types:
|
Name: Signature Type: signaturefield | asc desc | is_empty is_not_empty |
Name: Record ID Type: recordidfield | asc desc | is is_not contains not_contains |
Name: First Created Type: firstcreatedfield | asc desc | is is_not is_before is_on_or_before is_on_or_after contains |
Name: Last Updated Type: lastupdatedfield | asc desc | is is_not is_before is_on_or_before is_on_or_after contains |
Name: Open Comments Type: commentscountfield | asc desc | is_equal_to is_not_equal_to is_greater_than is_less_than is_equal_or_greater_than is_equal_or_less_than is_empty is_not_empty |
Name: Linked Record Type: linkedrecordfield | asc desc | has_any_of has_all_of is_exactly has_none_of is_empty is_not_empty |
Name: Assigned To Type: userfield | asc desc | has_any_of has_all_of is_exactly has_none_of is_empty is_not_empty |
Name: Auto Number Type: autonumberfield | asc desc | is_equal_to is_not_equal_to is_greater_than is_less_than is_equal_or_greater_than is_equal_or_less_than |
Name: Sub-Items Type: subitemsfield
Note: Sub-Items filters are based on the count of items present in the field, so it is a numeric-type filter | asc desc | is_equal_to is_not_equal_to is_greater_than is_less_than is_equal_or_greater_than is_equal_or_less_than |
Date Modes and Values
The following date modes and corresponding values are supported:
Date Mode | Values |
is | today yesterday one_week_ago one_week_from_now one_month_ago one_month_from_now one_year_ago one_year_from_now next_number_of_days past_number_of_days date_range |
is_not | today yesterday one_week_ago one_week_from_now one_month_ago one_month_from_now one_year_ago one_year_from_now next_number_of_days past_number_of_days date_range |
is_before | today yesterday one_week_ago one_week_from_now one_month_ago one_month_from_now one_year_ago one_year_from_now exact_date |
is_on_or_before | today yesterday one_week_ago one_week_from_now one_month_ago one_month_from_now one_year_ago one_year_from_now exact_date |
is_on_or_after | today yesterday one_week_ago one_week_from_now one_month_ago one_month_from_now one_year_ago one_year_from_now exact_date |
is_empty | null |
is_not_empty | null |
Related Articles