Skip to main content
All CollectionsAPI
Sorting and Filtering Records in the REST API

Sorting and Filtering Records in the REST API

Learn how to use the SmartSuite API to return sorted and filtered record sets, ensuring you get exactly the data you need.

Peter Novosel avatar
Written by Peter Novosel
Updated over 2 months ago

Plan Availability

All plan types

Permissions

Solution Creators: Can generate API calls to manage data and retrieve records.

Related Reading


Overview

The /records/list/ endpoint in the SmartSuite REST API enables you to retrieve and manipulate record data efficiently. It uses a POST request with a JSON body to define sort and filter instructions.

Note: SmartSuite may add keys to response objects without warning, but existing keys will not be removed without a deprecation notice.


Authorization

Authentication for the SmartSuite API relies on your API key, which conveys the same privileges as the generating user account. Treat your API key as securely as a password.

Headers for Authentication:

  • Authorization: Token API_KEY_HERE

  • Account-Id: WORKSPACE_ID_HERE

To find your Workspace ID, refer to the 8-character string in your SmartSuite URL: https://app.smartsuite.com/{Workspace ID}/


Retrieving Records

Single Record Retrieval

List of Records Retrieval


Specifying Sort and Filter Parameters

Example JSON Body

Here’s how to combine sorting and filtering in a single request:

{     "filter": {         "operator": "and",         "fields": [             {                 "field": "title",                 "comparison": "is_not_empty",                 "value": ""             }         ]     },     "sort": [         {             "field": "title",             "direction": "asc"         }     ] }

Sorting Syntax

  • Define a "sort" array with objects specifying:

    • field: Field ID or slug to sort by.

    • direction: Sorting order (asc or desc).

Examples:

  • Single Field Sort:

    "sort": [     {         "field": "title",         "direction": "desc"     } ]

  • Multiple Fields Sort:

    "sort": [     {         "field": "title",         "direction": "asc"     },     {         "field": "s228acd4ea",         "direction": "desc"     } ]

Filter Syntax

  • Define a "filter" object with:

    • operator: Logical operator (and or or).

    • fields: Array of filter objects, each with:

      • field: Field slug.

      • comparison: Operator (e.g., is, is_not).

      • value: Value to compare.

Example:

"filter": {     "operator": "and",     "fields": [         {             "field": "status",             "comparison": "is_not",             "value": "Complete"         },         {             "field": "s251d4318b",             "comparison": "is_equal_to",             "value": 0         }     ] }


Field Types and Operators

The table below summarizes valid sort and filter options for key field types:

Field Type

Sort Options

Filter Options

Text

asc, desc

is, is_not, contains, is_empty

Date

asc, desc

is, is_before, is_empty

Number

asc, desc

is_equal_to, is_greater_than, is_empty

Single Select

asc, desc

is, is_any_of, is_empty

Note: For more detailed field-specific options, refer to the SmartSuite API Documentation.


Practical Scenarios and Use Cases

1. Retrieving Active Projects

Scenario: The operations team wants a list of projects that are not marked as complete.

Solution: Use a filter with field: "status", comparison: "is_not", value: "Complete".

2. Sorting by Due Dates

Scenario: A manager needs to view upcoming tasks in chronological order.

Solution: Apply a sort directive: field: "due_date", direction: "asc".

3. Filtering by Priority

Scenario: A product team focuses on tasks marked as high priority.

Solution: Use a filter with field: "priority", comparison: "is", value: "High".


Tips for Success

  • Combine Sort and Filter: Maximize efficiency by defining both in a single request.

  • Use Minimal Permissions: Generate API keys with the least privileges required.

  • Validate JSON: Ensure your JSON syntax is correct to avoid errors.

For further information, explore the SmartSuite API Documentation.

Did this answer your question?