Working with API Data Transformation in Workflows

Overview

Core Concepts

Variables and Data Flow

• Variables are the key to passing data between workflow steps
• Data from GET requests can be stored as variables and referenced throughout your workflow
• Use the {{variable_name}} syntax to reference variables in subsequent steps

The "Analyze case" Step

• Extract specific values from API responses
• Transform data structures
• Edit array items
• Parse complex JSON objects
• Create new variables from existing data

Step-by-Step Implementation

1. GET Request - Retrieve Data

• Configure your GET endpoint
• Map the response to output variables

Note: If you want to capture the full response, use JSON path "." to return the entire payload as a single variable.

2. Analyze Case - Transform and Edit

• Variable Name: Something descriptive and meaningful
• Variable Type: Text
• Description: Clear, specific instructions for the transformation you want to perform

Example variable descriptions

Edit single array item:

Using the data from {{api_response}}, find the artist with id: 2 and update their role_ids to [1, 3, 5]. Keep all other artists unchanged. Return the complete updated artists array.

Transform keys + edit array:

Using {{api_response}}:
1. Rename 'role_ids' to 'assigned_roles' in all artist objects
2. Find the artist named "Artist A" and change their status to "featured" 
3. Add a new field 'updated_at' with {{todays_date}} to all artists
4. Return the complete transformed array

Multiple array operations:

Transform {{api_response}} by:
1. Remove any artists where status = "inactive"
2. For all remaining artists, add role_id 99 to their existing role_ids
3. Sort the array by artist name alphabetically
4. Return the final updated artists array

Conditional transformations:

Using {{api_response}}:
- If artist has role_ids [1,2], change to [1,2,3,4]
- If artist name contains "Senior", add role_id 99
- Otherwise, keep existing role_ids unchanged
Return the updated artists array

Data type conversions:

Transform {{api_response}} by:
1. Convert all id fields from strings to numbers
2. Change date fields from "YYYY-MM-DD" to "MM/DD/YYYY" format
3. Ensure role_ids is always an array (convert single values)
4. Return the converted data

Tips for array manipulation

• Be specific about which item to edit (use ID, name, or position)
• Provide an example of the expected output format
• You can edit multiple items in a single step
• Text variables can return complex JSON structures

3. POST Request - Submit Updated Data

Create another Custom API step for your POST request. In the body, reference your transformed variable, for example:

{
 "artists": "{{updated_artists}}"
}

Testing Your Transformations

Use the Preview button in the workflow toolbar and run the workflow with a previous case ID, test email, or test chat. This lets you check how data flows step by step:

1. Verify that {{api_response}} contains the expected data
2. Confirm that {{updated_data}} reflects the correct transformations
3. Validate the POST payload 

Common validation checks:

• Array structure is preserved
• Required fields aren't accidentally removed
• Data types match API expectations
• IDs and references remain valid

Best Practices

Writing clear instructions

• Be specific about what to modify
• Use examples of expected output
• Break complex changes into steps
• Call out required data types if the API is strict

Variable naming

• Use descriptive names (updated_artists not data)
• Match your API terminology
• Use multiple variables for more complex transformations

Error handling

• Add conditional branches after API calls
• Validate data exists before transforming
• Include fallbacks for missing/malformed data

Troubleshooting Common Issues

Variable not found

• Ensure variable names match exactly between steps
• Check that the GET request completed successfully

JSON format errors

• Be explicit about expected format in variable descriptions
• Use the preview feature to validate the outputted structure

Array reference issues

• Use unique identifiers (ID, email) rather than array positions
• Handle cases where target items might not exist

Getting Help