POST /api/v2/flows/executions returns 422 with 'invalid parameter' on externalId

NICE CXone API & Integrations
1

Getting a 422 Unprocessable Entity when trying to kick off an Architect flow from our custom agent desktop wrapper. The endpoint is POST /api/v2/flows/executions.

Here is the payload I’m sending:

{
 "flowId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
 "externalId": "case-12345",
 "parameters": [
 {
 "name": "customerId",
 "value": "998877"
 }
 ]
}

The flow exists and I can trigger it manually in the UI without issues. The OAuth token has the flow:execute scope. I’ve checked the docs and externalId is supposed to be a string.

I’ve tried:

  • Removing the externalId field entirely. The call succeeds, but I lose the correlation link.
  • Changing externalId to an integer. Still 422.
  • Adding a dummy divisionId to the body. No change.

The error message is pretty vague: Invalid parameter: externalId. It doesn’t say what’s wrong with it. Is there a format constraint I’m missing? Maybe a regex pattern? Or is this endpoint broken for non-internal triggers?

Also noticed that if I use the JS SDK api.flowsApi.postFlowExecution, it wraps the call similarly but gives the same response. Feels like the validation logic on the server side is stricter than the schema suggests. Any ideas on what makes the ID “invalid” here?