Sorting and Filtering Records
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.
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.
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_HERE |
| Account-Id | WORKSPACE_ID_HERE |
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/[tableId]/records/[Record Id]/
[tableId] is the Table (App) unique 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/[tableId]/records/list/
[tableId] is the Table (App) unique id
This endpoint supports sort and filter directives that are specified in the JSON body.
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:
| Key | Value |
|---|---|
| field | 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.
"sort": [
{
"field": "title",
"direction": "desc"
}
]
"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.
| Key | Type | Value |
|---|---|---|
| operator | string | Valid operators include:
|
| fields | array of filter objects | An array of Filter objects that have the following JSON literals:
|
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 |
|
|
| Name: Address Type: addressfield Operations applied to the full string version of concatenated address |
|
|
| Name: Checklist Type: checklistfield |
|
|
| Name: Color Picker Type: colorpickerfield |
|
|
| Name: Email Type: emailfield |
|
|
| Name: Full Name Type: fullnamefield |
|
|
| Name: IP Address Type: ipaddressfield |
|
|
| Name: Link Type: linkfield |
|
|
| Name: Phone Type: phonefield |
|
|
| Name: Record Title Type: recordtitlefield |
|
|
| Name: SmartDoc Type: richtextareafield |
|
|
| Name: Social Network Type: socialnetworkfield |
|
|
| Name: Text Area Type: textareafield |
|
|
| Name: Currency Type: currencyfield |
|
|
| Name: Number Type: numberfield |
|
|
| Name: Number Slider Type: numbersliderfield |
|
|
| Name: Percent Complete Type: percentcompletefield |
|
|
| Name: Percent Type: percentfield |
|
|
| Name: Rating Type: ratingfield |
|
|
| Name: Vote Type: votefield |
|
|
| Name: Count Type: countfield |
|
|
| Name: Single Select Type: singleselectfield |
|
|
| Name: Multiple Select Type: multipleselectfield |
|
|
| Name: Status Type: statusfield |
|
|
| Name: Tag Type: tagsfield |
|
|
| Name: Yes / No Type: yesnofield |
|
|
| Name: Date Type: datefield |
|
|
| Name: Date Range Type: daterangefield Note: You have to refer to the two dates in date range in this way: [Field Slug].from_date [Field Slug].to_date |
|
|
| Name: Due Date Type: duedatefield |
|
|
| Name: Duration Type: durationfield |
|
|
| Name: Time Type: field |
|
|
| Name: Time Tracking Log Type: timetrackingfield |
|
|
| Name: Formula Type: formulafield |
| 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 |
| Lookup 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: Rollup Type: rollupfield |
|
|
| Name: Files & Images Type: filefield |
|
Valid file types:
|
| Name: Signature Type: signaturefield |
|
|
| Name: Record ID Type: recordidfield |
|
|
| Name: First Created Type: firstcreatedfield |
|
|
| Name: Last Updated Type: lastupdatedfield |
|
|
| Name: Open Comments Type: commentscountfield |
|
|
| Name: Linked Record Type: linkedrecordfield |
|
|
| Name: Assigned To Type: userfield |
|
|
| Name: Auto Number Type: autonumberfield |
|
|
| Name: Sub-Items Type: subitemsfield |
|
|
Date Modes and Values
The following date modes and corresponding values are supported:
| Date Mode | Values |
|---|---|
| is |
|
| is_not |
|
| is_before |
|
| is_on_or_before |
|
| is_on_or_after |
|
| is_empty | null |
| is_not_empty | null |