Call a REST API within a workflow
Last Update: Sep 2024 • Est. Read Time: 3 MINWorkflows 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
- Create a new workflow
- JSON vs. generic REST API action
- Configure the action
- Use the REST API response
- FAQ
Access workflows
Users with admin permissions can access the Workflows settings by going to Settings > 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:
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
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 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
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:
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, the input represents the exact call that was made, and can be checked against the Kustomer API Reference 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, 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.