Trigger a Twilio Studio Flow Execution via the REST API – Twilio Support

To trigger a Studio Flow via the REST API, your application needs to make an HTTP POST request to the Flow's Resource. There are three required pieces of information for your request; The flow's SID, the recipient and the sender.

Flow SID: The unique identifier for your each Studio flow. Find this by visiting the Console Studio Dashboard.
Recipient: The To parameter consisting of the destination phone number (using E.164 formatting).
Sender: The From parameter consisting of a valid Twilio phone number (using E.164 formatting), or a verified outgoing caller ID.

Important: In order to successfully execute flows via the REST API, your flow's Trigger widget must have a transition from the REST API lead to a valid widget.

API Request Example

Here’s an example cURL script:

curl -X POST https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions \
--data-urlencode "To=+13105555555" \
--data-urlencode "From=+12125551234" \
-u "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token"

This example will contact the destination (310) 555-5555 from the sender (212) 555-1234, and execute the REST API trigger on flow FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX. To make this script work for you, make the following updates, and then paste it into a terminal window:

Line 1 update with a valid Flow SID
Line 2 update with a valid destination
Line 3 update with a valid sender number
Line 4 update with your Account SID and Auth Token.

Custom Parameters

The Studio API also accepts custom parameters in your request that are visible to your widgets as variables. These parameters need to be included in your API request as JSON values in the form of Parameters={"parameter_name":"value"}. When a request is received with custom parameters, they can be accessed in your widget with via a variable. This is helpful when using Studio for contact templates, passing custom parameters for someone's name, dates, times, amount due, and more.

Here’s an example cURL script:

curl -X POST https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions \
--data-urlencode "To=+13105555555" \
--data-urlencode "From=+12125551234" \
--data-urlencode "Parameters={\"patient\":\"Jon\",\"time\":\"8AM\"}" \
-u "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token"

This example will contact the destination (310) 555-5555 from the sender (212) 555-1234, and execute the REST API trigger on flow FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX. In this execution, the parameters patient:Jon and time:8AM will also be passed to your flow. To make this script work for you, make the following updates, and then paste it into a terminal window:

Line 1 update with a valid Flow SID
Line 2 update with a valid destination
Line 3 update with a valid sender number
Line 4 update with the desired parameters
Line 5 update with your Account SID and Auth Token.

In your flow, the passed parameters will be available via a variable in the form of {{flow.data.parameter_name}}. Any time we see this, we'll automatically replace it with the parameter's value.

For example, if we were to send the above API request to a flow with a Send Message widget with the following Message Body:

Reminder from the Doctor's office: Patient {{flow.data.patient}} has an appointment tomorrow at {{flow.data.time}}.

The recipient would receive the following message:

Reminder from the Doctor's office: Patient Jon has an appointment tomorrow at 8AM.

Postman Examples

Below screenshot explains about the correct way of using the Parameters .

Developers might misconstrue as like below format, which WILL NOT work.

Additional Resources

For full details, please see our Twilio Studio REST API documentation.