SmartSuite's REST API allows you to request "hydrated" records, returning human-readable labels alongside their underlying values. This reduces the number of API calls required to retrieve complete data, simplifying your workflows.
Plan Availability | All plans |
Permissions | Admin: API Access Required |
Related Reading |
Overview
Hydrated records include both:
Labels: Human-readable descriptions.
Values: Raw data or identifiers.
This feature is especially useful for fields like "Single Select" or "Assigned To," where labels improve clarity in application interfaces.
Enabling Hydration
For Single Records
Use the hydrated=true parameter in the GET request:
For Multiple Records
Include the hydrated parameter in the JSON body of a POST request:
{ "hydrated": true }Response Structure
A hydrated record includes label-value pairs for supported fields. Example response:
"sec059ca14": [ { "label": "Value A", "value": "48fefd4c-7cea-4f0e-8a36-f3af942e652c" }, { "label": "Value B", "value": "8a349f68-ecd7-4f70-85dd-e03ed08aca84" }, { "label": "Value C", "value": "53513512-630e-4976-a0a9-39e54206ca5c" } ]Supported Field Types
Hydration is available for the following field types:
Single Select
Multiple Select
Status
First Created
Last Updated
Assigned To
Tags
Vote
Time Tracking Log
Checklist
Lookup
Practical Use Cases
1. Streamlined UI Development
Scenario: Display user-friendly field labels in your application without additional API calls.
Solution: Use hydrated responses to retrieve both labels and values in one request.
2. Reducing API Call Volume
Scenario: Your application needs both raw values and human-readable labels for a dataset.
Solution: Enable hydration to minimize redundant API calls for label lookups.
3. Enhancing Data Reports
Scenario: Generate reports that include descriptive labels for fields like "Status" or "Tags."
Solution: Use hydrated responses to integrate label information directly into your reports.
By leveraging hydrated records, you can improve both the performance and usability of your applications. For further information, refer to the SmartSuite API Documentation.