POST /api/v2/flows/executions returning 400 BAD REQUEST

NICE CXone API & Integrations
1

Why does this config cause a failure when launching a flow? I am sending a POST request to /api/v2/flows/executions with a valid OAuth token.

The payload includes the flowId and triggerData, but the API returns a 400 BAD REQUEST immediately. No specific error message is provided in the response body.

Here is the minimal JSON payload:

{
 "flowId": "abc-123-def",
 "triggerData": {
 "userId": "user-001"
 }
}
2

If I remember correctly…

  • The endpoint requires triggerData to match the flow’s defined input schema exactly, or it defaults to expecting an empty object.
  • Use the Python SDK to validate the payload against the FlowExecutionRequest model before sending.
from purecloudplatformclientv2.models import FlowExecutionRequest
req = FlowExecutionRequest(flow_id="abc-123-def", trigger_data={})
client.flows_api.post_flows_executions(body=req)
3

To fix this easily, this is to ensure triggerData is an empty object {} if the flow has no inputs. The API rejects undefined or null values for this property.

const body = { flowId: 'abc-123-def', triggerData: {} };
await platformClient.FlowsApi.postFlowsExecutions(body);

Validate against FlowExecutionRequest in the SDK.

4

If I recall correctly, the 400 error often stems from OAuth token scope mismatches rather than payload structure. The documentation states, “The access token must include the flow:execute scope for programmatic flow execution.” Many developers retrieve tokens via client credentials but forget to explicitly request this scope during the grant. Without it, the API rejects the request before validating the triggerData. Ensure your token endpoint request includes scope=flow:execute.

Use this curl command to verify your token has the correct permissions before retrying the flow execution:

If the token is valid, the issue might be the triggerData schema mismatch mentioned above. However, check the token first. I see many cases where the token lacks flow:execute or integration:read. The suggestion above regarding empty objects is correct for flows with no inputs, but if the flow expects specific key-value pairs in triggerData, sending an empty object will still cause a 400 error. Validate the flow’s input schema in Architect. If the flow expects a customerId string, your payload must be {"triggerData": {"customerId": "123"}}. Do not send null or omit required keys. This is a common pitfall in integration development. Check the flow’s configuration in the Genesys Cloud UI to confirm expected inputs.

curl -X POST "https://api.mypurecloud.com/oauth/token" \
 -H "Authorization: Basic <base64_encoded_client_id_and_secret>" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d "grant_type=client_credentials&scope=flow:execute"
5 
var config = new Configuration("https://api.mypurecloud.com", "client_id", "client_secret");
config.AddDefaultScope("flow:execute");

That scope was missing. I added it to the .NET SDK config. The 400 error stopped. The empty triggerData was fine, but the token needed flow:execute. Thanks for the tip on scopes.