You are here:
Start a Flow from REST API
Use a REST call to run an autolaunched flow by using the invocable action endpoint and setting the path to flow. For example, you can run a flow from a non-Salesforce application or piece of code. The flow retrieves data from Salesforce and returns it as an output variable in your REST call.
Flows that start from REST API can contain complex business logic and enhanced error handling so that they integrate with external systems more effectively. This approach promotes reusability by encapsulating logic within flows that can be called as needed. It also provides greater control over execution context and order of operations. The combination of REST API and flow helps you create more powerful and flexible apps that are easier to maintain.
Salesforce Object Query Language (SOQL) and Data Manipulation Language (DML) limits apply during flow execution. See Per-Transaction Flow Limits in Salesforce Help.
Note: Only autolaunched flows can be started by a REST API call. The REST API call runs the active version of the flow.
Getting Flow Metadata
Before running a flow, use a REST call to get a description of the flow and see the possible inputs available for the flow. This approach helps you understand what input variables the flow expects and their data types.
To get the flow description and inputs for a flow, use a GET request:
GET /services/data/v65.0/actions/custom/flow/FLOW_API_NAMEReplace FLOW_API_NAME with the API name of your flow. The response includes metadata about the flow's input and output variables.
Running a Flow Using a REST API Call
To run a flow by using a REST API call, make a POST request to the invocable action endpoint with the flow's API name. You must authenticate your request using OAuth 2.0 or a session ID.
Use this endpoint format:
POST /services/data/v65.0/actions/custom/flow/FLOW_API_NAMEReplace FLOW_API_NAME with the API name of your flow. Replace v65.0 with your Salesforce API version.
Required headers:
Authorization: Your OAuth 2.0 access token or session IDContent-Type:application/json
Request body: Include an inputs array containing objects with your flow's input variable names and values.
Example: Running a Flow with Input Variables
This example runs the active version of the flow "Escalate_to_Case" and sets values for two input variables:
CommentCount and FeedItemId. When it runs, the flow
checks whether:
- A feed item has more than five comments
- A best comment hasn't been selected yet
Endpoint:
POST /services/data/v65.0/actions/custom/flow/Escalate_to_CaseRequest headers:
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/jsonRequest body:
{
"inputs": [
{
"CommentCount": 6,
"FeedItemId": "0D5D0000000cfMY"
}
]
}Example using curl:
curl -X POST \
https://yourinstance.salesforce.com/services/data/v65.0/actions/custom/flow/Escalate_to_Case \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"inputs": [
{
"CommentCount": 6,
"FeedItemId":
"0D5D0000000cfMY"
}
]}'Handling Responses and Output Variables
When a flow completes
successfully, the REST API response includes the flow's output variables. The response
structure includes an outputValues object containing the output variable
names and their values, with the resulting Flow Interview’s unique GUID and final
status.
Example success response:
{
"actionName": "Escalate_to_Case",
"errors": null,
"invocationId": null,
"isSuccess": true,
"outcome": null,
"outputValues": {
"CaseId": "500D0000003abcX",
"Status": "Escalated",
"Flow__InterviewGuid": xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxxa",
"Flow_InterviewStatus": "Finished"
},
"sortOrder": -1,
"version": 1
}Example error response:
If the flow execution fails, the response provides a false value for the
isSuccess attribute and includes error information in an
error object. For actions that are Flows, and the Flow successfully
initialized before the error, the outputValues provides the unique GUID for
that FlowInterview:
[
{
"actionName": "Escalate_to_Case",
"errors": [
{
"statusCode": "FLOW_ELEMENT_ERROR",
"message": "An error occurred at element MyDecision (Decision).",
"fields": []
}
]
"invocationId": null,
"isSuccess": false,
"outcome": null,
"outputValues": {
"Flow__InterviewGuid": xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxxa",
"Flow__InterviewStatus": "Error"
},
"sortOrder": -1,
"version": 1,
}
]Running Multiple Flow Instances
You can run multiple instances of the same flow in a single REST API call by including
multiple objects in the inputs array. Each object in the array represents a
separate flow execution with its own set of input values. These Flow Interviews run together
in a single transaction. If the flow includes any bulkifiable elements, those elements run
as a bulkified operation together for more efficient use of DML and SOQL limits during
execution.
Example request body with multiple inputs:
{
"inputs": [
{
"CommentCount": 6,
"FeedItemId": "0D5D0000000cfMY"
},
{
"CommentCount": 8,
"FeedItemId": "0D5D0000000cfMZ"
}
]
}The response includes results for each flow execution, with each Flow Interview unique GUID and status:
[
{
"actionName": "Escalate_to_Case",
"errors": null,
"invocationId": null,
"isSuccess": true,
"outcome": null,
"outputValues": {
"CaseId": "500D0000003abcX",
"Status": "Escalated",
"Flow__InterviewGuid": xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxxa",
"Flow_InterviewStatus": "Finished"
},
"sortOrder": -1,
"version": 1
},
{
"actionName": "Escalate_to_Case",
"errors": null,
"invocationId": null,
"isSuccess": true,
"outcome": null,
"outputValues": {
"CaseId": "500D0000003abcY",
"Status": "Escalated",
"Flow__InterviewGuid": xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxxb",
"Flow_InterviewStatus": "Finished"
},
"sortOrder": -1,
"version": 1
}
]Error Handling
When running flows via REST API, handle potential errors:
- Authentication errors: Make sure that your access token is valid and has the necessary permissions to run flows.
- Flow execution errors: Check the
isSuccessfield in the response. Iffalse, review theerrorsarray for details. - Invalid input variables: Verify that input variable names match the flow's API names and that data types match the flow's variable definitions.
- Flow not found: Make sure that the flow API name is correct and the flow is active.
For more information about REST API authentication, see OAuth 2.0 Web Server Flow for Web App Integration in Salesforce Help.
