API data transformation in workflows

Plans and permissions:

• Add-on: AI agents, billed separately
• Build a workflow that transforms API data: Admin, Manager, or Team Lead role, or a custom role with Workflows set to Can create, edit, and delete workflows

Use this pattern when a workflow needs to change data from your systems before sending it back, such as updating one person’s roles in a list, renaming fields, or converting date formats. The workflow gets the data with a GET request, changes it in an Analyze case step, and submits the result with a POST request.

You build it in the workflow builder, in AI support > Workflows. The requests use custom API endpoints, so set those up first.

How data transformation works

• Variables carry data from one step to the next. Refer to a variable in later steps as {{variable_name}}.
• A Custom API tool step can save a whole response as one variable, with the path ..
• An Analyze case step with a Text variable can change data according to the variable’s description. It can pick out values, edit items in a list, rename or add fields, remove or sort items, and convert values from one type or format to another.
• A Text variable can hold a full JSON structure, so the result can go straight into the next request.

Transform API data

Get the data

Add a Custom API tool step for your GET endpoint, with Type set to Lookup (Read). Under the output variables, map the path . to a variable such as api_response to save the whole response.

Transform the data

Add an Analyze case step and add a variable:

1. Enter a Variable name that says what it holds, such as updated_artists.
2. Set Variable type to Text.
3. In Variable description, write exactly how to change the data, and say what to return. For examples, see Example variable descriptions.
4. Select Update step.

Send the updated data

Add another Custom API tool step for your POST endpoint, with Type set to Action (Write). In the Request body, refer to the transformed variable. To send it as a JSON list rather than as text, add the array type:

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

For a JSON object, use the object type instead.

Example variable descriptions

Edit one item in a list:

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.

Rename fields and edit an item:

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

Several changes to a list:

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 changes:

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

Type and format 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

Test the transformation

1. In the workflow builder, select Test.
2. Test with a previous Case ID, a test Email, or a test Chat.
3. Select Test, then open each step in the results.
4. Check that api_response holds the data you expected, that the transformed variable shows the right changes, and that the POST request body is correct.

When you test a workflow, the Action (Write) request isn’t sent, so you can check the request body without changing your data. Look for these problems:

• The structure of the list or object has changed.
• Required fields are missing.
• Values have the wrong type for your API.
• IDs and references no longer match.

For more on testing, see Building workflows.

Best practices

• Be specific about what to change. Identify the item to edit by an ID, name, or other unique value, and you can edit several items in one step.
• Show the result you want. Include an example of the expected output, and call out data types if your API is strict.
• Break big changes into steps. Number them in the description, or use more than one variable.
• Name variables clearly. Use updated_artists, not data, and match your API’s terms.
• Plan for errors. Add branches after each API step, check that the data exists before changing it, and give the workflow a fallback, such as a handoff, for missing or malformed data.

Common issues

• Variable not found: Check that the variable’s name matches exactly in every step, and that the GET request succeeded.
• The JSON is malformed: Check that the description says exactly what format to return, then test the workflow to see the output.
• The wrong item was changed: Check that the description identifies items by a unique value, such as an ID or email, rather than by position, and says what to do if the item doesn’t exist.