All Collections
API
Sorting and Filtering Records in the REST API
Sorting and Filtering Records in the REST API

Instruct the SmartSuite API to return sorted and filtered record sets to retrieve the exact data you need

Peter Novosel avatar
Written by Peter Novosel
Updated over a week ago

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_HERE

  • Account-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:

  • [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:

  • archive

  • image

  • music

  • pdf

  • powerpoint

  • spreadsheet

  • video

  • word

  • other

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

Did this answer your question?