# Call a REST API within a workflow

> Workflows allow you access Rest APIs in a flexible way to connect to other systems.

Source: https://help.kustomer.com/en_us/call-rest-api-within-workflow-rk3GGm3Gf

Last updated: 2026-06-22T13:25:13.565Z

Workflows allow you to access Rest APIs in a flexible way to connect to other systems. For example, when a customer’s contact information is updated within Kustomer, you may want to sync that data with your organization’s internal admin tool. Alternatively, when a message comes into Kustomer, you may want to send the text to a system that can detect your customer’s intent and tag the conversation to ensure the correct user or team handles it. If Kustomer does not yet have a direct integration with the tools you use, REST API calls in Workflows are a great way to customize Kustomer to suit your needs.

**Who can access this feature?**

**User types**

Admins can access workflows and API pages.

  

### In this article

*   [Access workflows](#access)
*   [Create a new workflow](#create)
*   [JSON vs. generic REST API action](#json-generic)
*   [Configure the action](#configure)
*   [Use the REST API response](#rest-api)
*   [FAQ](#faq)

### Access workflows

Users with admin permissions can access the Workflows settings by going to **Settings![](https://cdn.kustomerhostedcontent.com/media/570fad9d9001bc1000163b28/6b3c4c64f224ea25915e6beff3da8050.png)** **\> Platform > Workflows**.

### Create a new workflow

Create a new workflow or edit an existing one in the Workflows settings.

Making REST API calls from Workflow starts in the Workflow editor:

![](https://cdn.kustomerhostedcontent.com/media/570fad9d9001bc1000163b28/8a5ca3955b9fe192aed28e66ae1799aa.png)

After defining when the workflow should run and adding the workflow’s trigger and conditions, create a new action. Select **Kustomer** from the **Action App** drop-down menu in the right panel.

### JSON vs. generic REST API action

From here, you have two options in the **Action Event** menu that can be used to make REST API calls:

*   **REST API: JSON****—**This is the most common request when making an API call to a server that accepts JSON-formatted requests.
*   **REST API: Generic -** If the server receiving your request requires a different format, this action allows you to customize the request body as a text string.

### Configure the action

The following fields are available in both actions:

**URI**

The request's full address should be sent to includes the protocol and path. 

Example: [https://api.kustomerapp.com/v1/customers](https://api.kustomerapp.com/v1/customers)

**Method**

The HTTP method of the request.

Example: `POST`, `GET`, `PUT`, `PATCH`, or  `DELETE`

**Data**

The value of this field will vary depending on the action selected. 

**REST API: JSON:** This will be a JSON object. Kustomer workflow syntax can be used in the nested values of the JSON to insert dynamic values into the payload.

Example: `{ "customerId": "/#steps.1.id" }`

**REST API: Generic:** This will be a string. Handlebars can be used to insert dynamic values into the payload.

Example: `{ "customerId": "{{steps.1.id}}" }`

**Headers**

A JSON object with key-value pairs of the HTTP headers that should be sent with the request.

Example: `{ "content-type": "application/json" }`

**JSON**

if this field is set to `true`, Kustomer will attempt to parse the response as JSON.

### Use the REST API response

After using either of the REST API Actions, you may want to access the response from those calls in the rest of your workflow. Kustomer exposes two properties that you can use:

**Response**

The response contains metadata about the response to your API request. It will include the status code, content type, content length, and other details.

**Body** 

The body of the response, if you specified that the body should be parsed as JSON, then you can also select specific elements that are returned in the response. To understand the response format, use the [Workflow Logger](https://help.kustomer.com/test-and-debug-workflows-r1yhy7hfM) to see the exact data available for use in further steps.

For example, for a JSON response that looks like `{ "externalId": "1234" }`, you can access the data using the following syntax:

`/#steps.[step-id].body.externalId`

### **Update an email draft using a workflow**

Kustomer does not have a native "Draft: Update" workflow action. The ****Message: Update**** action applies to sent messages only, not drafts. To modify a draft (for example, to add CC recipients), use the ****REST API: JSON**** action to call the drafts endpoint directly.

To update a draft in a workflow:

1.  Set the ****Trigger Event**** to `kustomer.draft.create`
2.  Add your condition and lookup steps as needed (for example, look up the customer's company or assigned representative).
3.  Add an action step. Set the ****Action App**** to ****Kustomer**** and the ****Action Event**** to ****REST API: JSON****.
4.  Set the ****Method**** to PUT
5.  Set the ****Endpoint**** to `/v1/drafts/{{steps.trigger.id}}`, where `{{steps.trigger.id}}` references the draft ID from the trigger payload.
6.  In the ****Body****, include the fields you want to update. For example, to add a CC recipient:`               {    "cc": ["representative@example.com"]  }     `

7.  In the ****Authentication****section, use an API key with the following roles:
    *   `org.permission.draft.update`
    *   `org.permission.draft.create`
    *   `org.user.draft.read`
    *   `org.user.draft.write`

### 

****Important:**** Create a non-expiring API key for this workflow. Navigate to ****Settings**** > ****Security**** > ****API Keys**** to generate one.

**REST API step timeout**

The timeout for a REST API step in a workflow is ****60 seconds****. This is a hard limit and is not configurable. If the external endpoint does not return a response within 60 seconds, the workflow stops with an `ESOCKETTIMEDOUT` error.

To troubleshoot `ESOCKETTIMEDOUT` errors:

*   Review the processing time of the external endpoint. If the endpoint performs heavy processing (ML inference, database lookups, external calls), that time counts toward the 60-second window.
*   Optimize the endpoint to respond faster, or return an asynchronous acknowledgment immediately and process in the background.
*   Check server logs on the external endpoint for incoming requests from Kustomer's outbound IPs at the times the error occurred.
*   Verify that all of Kustomer's outbound IP addresses are allowed by the endpoint's IP restrictions. A blocked request does not return a response and triggers this error. For the list of outbound IP addresses, see [System requirements](https://help.kustomer.com/system-requirements-Hk0fbZTG7).

### FAQ

**Q: I want to include the raw data output from the trigger or from one of the workflow's steps in my API request. How do I do this without re-building the data structure one field at a time?**

A: There's no need to rebuild the entire JSON structure in the API request body. You can use a step's output by referencing the step's ID. Here's an example for using the trigger step's data in a request body:

![](https://support.kustomer.com/images/rest_api_raw_data.png)

**Q: I'm seeing errors in the REST API step while debugging my workflow. What do these errors mean?**

Errors within a workflow’s Rest API step are indicative that the API call made as a result of a workflow action step failed. [When debugging](https://www.kustomer.com/blog/debug-workflow-errors/), the input represents the exact call that was made, and can be checked against the [Kustomer API Reference](https://developer.kustomer.com/kustomer-api-docs/reference/introduction) guide to ensure the call is structured correctly. The output will show the response of the call, and a `statusCode` will be present in that data. More information on each status code can be found in [Kustomer API Reference: Errors](https://developer.kustomer.com/kustomer-api-docs/reference/errors), which can assist with troubleshooting common issues.

**Q: My REST API workflow step ran as expected, but my data did not update correctly. What happened?**

After a REST API call runs, the status code might show a 200 response if the data does not update as expected. This indicates that while nothing was wrong with the call itself, there was an issue with something the call was trying to do. Review the workflow debug logs to see the input on how the API call ran, and check to ensure all of the expected data was present when that step ran.