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_HEREAccount-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
Endpoint:
GET https://app.smartsuite.com/api/v1/applications/[App Id]/records/[Record Id]/Sorting and Filtering: Not applicable.
List of Records Retrieval
Endpoint:
POST https://app.smartsuite.com/api/v1/applications/[App Id]/records/list/JSON Body: Contains sorting and filtering parameters.
Content-Type Header: Set to
application/json.
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 (ascordesc).
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 (andoror).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 |
|
|
Date |
|
|
Number |
|
|
Single Select |
|
|
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.