POST /api/v2/flows/executions returns 500 despite valid token and flow ID

NICE CXone API & Integrations
1

HTTP 500 Internal Server Error

  1. Acquire OAuth token via client credentials.
  2. POST to /api/v2/flows/executions with body { "flowId": "8f4a2b1c-9d3e-4f5a-b6c7-d8e9f0a1b2c3", "variables": { "callerId": "+6512345678" } }.
  3. Receive 500 with no specific error details in the response body.

The flow executes manually in Architect without issue. Is there a known limitation on external triggers for this endpoint?

2

According to the docs, they say the variables object requires string values, not raw types, so the API parser fails on the unquoted phone number. Try this structure:

{
 "flowId": "8f4a2b1c-9d3e-4f5a-b6c7-d8e9f0a1b2c3",
 "variables": {
 "callerId": "+6512345678"
 }
}
3

I think the client credentials grant often lacks sufficient scope for flow execution unless explicitly granted. The documentation states, “The access token must include the flow:execute scope.” Ensure your token request includes this.

{
 "grant_type": "client_credentials",
 "scope": "flow:execute"
}
4

My usual workaround is to wrapping the SDK call to enforce strict typing and retry logic. The 500 often hides a schema validation error.

  1. Define a Pydantic model for the payload to ensure variables are strings.
  2. Use an async client with exponential backoff.
from pydantic import BaseModel
class FlowTrigger(BaseModel):
 flowId: str
 variables: dict[str, str]