POST /api/v2/flows/executions returning 400 with valid JSON payload

NICE CXone API & Integrations
1

The flow execution endpoint is rejecting my request with a 400 Bad Gateway, even though the JSON looks perfect. I’m trying to trigger a specific Architect flow from an external Node.js service. The documentation says executionConfig is optional, but omitting it doesn’t help. Here’s the payload I’m sending:

{
 "flowId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
 "executionConfig": {
 "queueName": "Support Queue"
 },
 "inputs": {
 "callerNumber": "+2348000000000"
 }
}

The response is just:
{"errorCode":"invalid.request","message":"Failed to parse request body."}

I’ve validated the JSON structure multiple times. It’s valid. The flow ID exists and is active. I’m using the standard Genesys Cloud JS SDK for the auth token generation, so that’s not the issue. The headers are set to application/json. I’ve tried removing the executionConfig block entirely, but get the same error. Is there a hidden schema requirement for the inputs object that isn’t documented? Or is this a known bug with the v2 flows endpoint?

2

Cause: You left inputs empty. The API expects valid JSON objects, not trailing commas or undefined fields.
Solution: Remove the empty object or provide actual key-value pairs.

{
 "flowId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
 "executionConfig": {
 "queueName": "Support Queue"
 }
}
1 Like
3

The point about JSON syntax being critical is valid, but that’s infrequently the root cause of a 400 error with this endpoint in production. The more common issue is typically the executionConfig structure or missing required inputs for the specific flow you’re targeting.

If your flow expects inputs, omitting the inputs object entirely or providing an empty object will likely cause execution to fail validation before routing logic is reached. You need to map the inputs exactly as defined in the flow’s input schema. Review the flow’s input parameters in the Genesys Cloud UI to ensure your payload matches.

Here’s a representative example demonstrating a flow execution with inputs. Note the strict JSON formatting and explicit input mapping:

{
 "flowId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
 "executionConfig": {
 "queueName": "Support Queue"
 },
 "inputs": {
 "customer_id": "12345",
 "issue_type": "billing"
 }
}

Also, verify your OAuth token scopes. The token requires the flow:execute permission. If you’re using a user token, ensure the user has the appropriate role with permissions to execute flows. Application tokens are also viable, but require the correct scope to be granted during application configuration.

Another area to investigate is the flow ID itself. Sometimes, the ID is inadvertently copied from the browser URL instead of the actual resource ID. While visually similar, the API requires the UUID, not the UI’s hash representation. This is an easy oversight, especially when fatigued.

Examine the response body within the 400 error. It should provide details on which field failed validation, offering a crucial clue for troubleshooting. The error message may indicate a missing required input or an invalid data type. Finally, consult the Genesys Cloud developer documentation for the most up-to-date specifications for the executionConfig and inputs objects to confirm compliance.

2 Likes