The SmartSuite REST API gives you the ability to list all of your Solutions, Tables (formerly called Apps), Fields, Members and their properties.
The metadata calls can be accessed with your existing SmartSuite API Key and account id. No additional credentials are required.
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 the standard portions of the REST API, SmartSuite uses token-based authentication for metadata 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…
Pagination
Most endpoints that return multiple results can be instructed to return results in pages to reduce the size of individual responses. By default each endpoint will return all entities requested, but you can explicitly set the page size by appending a "limit" parameter to the request URL, like this:
https://app.smartsuite.com/api/v1/applications/[ID]/records/list/?limit=100
This will have the effect of returning the first 100 items. You can retrieve subsequent pages by specifying an offset value:
https://app.smartsuite.com/api/v1/applications/[ID]/records/list/?limit=100&offset=100
This will tell the API to ignore the first 100 items and send the next 100.
The total number of results is contained in the total property:
{
"total": 5000,
"offset": 0,
"limit": 0,
"items": [
...
]
}
Metadata Request Endpoints
The following metadata endpoints are available in the v1 REST API.
List Solutions
GET https://app.smartsuite.com/api/v1/solutions/
Returns a list of all solutions present in the Workspace. Results can optionally be paginated.
Return Specific Solution
GET https://app.smartsuite.com/api/v1/solutions/[Solution_Id]/
Returns a specific solution.
Create a Solution
POST https://app.smartsuite.com/api/v1/solutions/
Creates a new Solution. The following parameters should be included in the body of the request:
{
"name": "My New Solution"
"logo_icon":"overline", <-- Material Design icon name
"logo_color":"#3A86FF" <-- Hex color for the icon (see list below)
}
Valid Hex Colors:
Primary Blue = "#3A86FF"
Primary Light Blue = "#4ECCFD"
Primary Green = "#3EAC40"
Primary Red = "#FF5757"
Primary Orange = "#FF9210"
Primary Yellow = "#FFB938"
Primary Purple = "#883CD0"
Primary Pink = "#EC506E"
Primary Teal = "#17C4C4"
Primary Grey = "#6A849B"
Dark Primary Blue = "#0C41F3"
Dark Primary Light Blue = "#00B3FA"
Dark Primary Green = "#199A27"
Dark Primary Red = "#F1273F"
Dark Primary Orange = "#FF702E"
Dark Primary Yellow = "#FDA80D"
Dark Primary Purple = "#673DB6"
Dark Primary Pink = "#CD286A"
Dark Primary Teal = "#00B2A8"
Dark Primary Grey = "#50515B"
Duplicate a Solution
POST https://app.smartsuite.com/api/v1/solutions/duplicate/
Duplicates a Solution. Note that you can duplicate a Solution into another Workspace where you have Admin or Creator role access! The following parameters should be included in the body of the request:
{
"solution_id": "solution_id_to_duplicate",
"name": "My Solution Copy",
"from_workspace": "from_workspace_id",
"to_workspace": "to_workspace_id",
"copy_records": true, <-- true to duplicate records
"copy_comments": true <-- true to duplicate comments
}
List All Tables (Apps)
GET https://app.smartsuite.com/api/v1/applications/
Returns a list of all Tables. Results can optionally be paginated.
Return Specific Table (App)
GET https://app.smartsuite.com/api/v1/applications/[App_id]/
Returns a specific Table.
Create a Table (App)
POST https://app.smartsuite.com/api/v1/applications/
Creates a new Table. Note that all new Tables will contain default fields.
Include the following JSON body to specify name and solution properties:
{
"name": "[App Name]",
"solution": "[App Id]",
"structure": []
}
Add a Field to a Table (App)
POST https://app.smartsuite.com/api/v1/applications/[App_Id]/add_field/
Adds a field of the specified type to a Table.
Include the following JSON body to specify field parameters:
{
"field": {
"slug": "[Random 10 digit alphanumeric value]",
"label": "[Field Name]",
"field_type": "[Field Type]",
"params": {
[Field-Specific Parameters]
},
"is_new": true
},
"Field_Position": {
"prev_sibling_slug": "[Previous Field Slug (or null)]"
},
"auto_fill_structure_layout": true
}
Bulk Add Fields to a Table (App)
POST https://app.smartsuite.com/api/v1/applications/[App_Id]/bulk-add-fields/
Adds a field of the specified type to a Table.
Include the following JSON body to specify field parameters:
{
"fields": [
{
"field_type": {field_type},
"label": {label},
"slug: {slug}, # not required
"params": {params}, # can be empty {}
},
...
],
"set_as_visible_fields_in_reports": [{report_id}] # can be empty []
At this time a limited number of field types are supported by the bulk endpoint. The following list of field types are NOT supported:
NOT_SUPPORTED_FIELD_TYPES = (
FieldTypes.RecordId,
FieldTypes.AutoNumber,
FieldTypes.SubItems,
FieldTypes.Checklist,
FieldTypes.Formula,
FieldTypes.Count,
FieldTypes.Rollup,
FieldTypes.Lookup,
FieldTypes.Vote,
FieldTypes.Signature,
FieldTypes.FirstCreated,
FieldTypes.LastUpdated,
FieldTypes.CommentsCount,
FieldTypes.File,
FieldTypes.TimeTracking,
FieldTypes.ButtonField,
FieldTypes.HiddenText,
FieldTypes.TextNested,
FieldTypes.Any,
FieldTypes.RecordTitle,
FieldTypes.SocialNetwork
)
List Workspace Members
POST https://app.smartsuite.com/api/v1/applications/members/records/list/
Returns a list of workspace Members and their profiles. Results can optionally be paginated.
Update Member Profile
PATCH https://app.smartsuite.com/api/v1/applications/members/records/[Id]/
Updates a member's profile by their unique id.
Get Tag Field values for a Solution
GET https://app.smartsuite.com/api/v1/tags/?solution=[Solution_Id]/
Gets a list of Tag Field values for the specified solution. Note that this request does not support pagination.
List Record Comments
GET https://app.smartsuite.com/api/v1/comments/?record=[Record_Id]
Gets a record's comments. Returns an array of comment objects.
Add Comment to Record
POST https://app.smartsuite.com/api/v1/comments/
Adds a comment to a record. Pass the following JSON structure in the body of the POST:
{
"assigned_to": [Member Id or null],
"message": {
"data": {
"type": "doc",
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "[Comment Text]"
}
]
}
]
}
},
"parent_comment": "[Parent Comment Id if applicable]",
"application": "[App_Id]",
"record": "[Record_Id]"
}
You can optionally send HTML to the endpoint as well, and SmartSuite will translate the HTML to markup for you:
{
"assigned_to": [Member Id or null],
"message": {
"html": "<b>A test</b>"
},
"application": "[App_Id]",
"record": "[Record_Id]"
}