POST /api/v2/flows/executions returning 400 on initialMessage payload

NICE CXone API & Integrations
1

We’re deploying a custom web portal to initiate an inbound Architect flow without console interaction. The drag-and-drop trigger in the admin UI handles the routing perfectly, so the underlying logic is sound. Hitting the REST endpoint keeps throwing a 400. Here’s the current request structure.

{
 "flowId": "a8f3c21d-9b4e-4f11-8c7a-000000000000",
 "initialMessage": "Customer needs escalation",
 "routingData": {
 "queueId": "b7e2d10c-8a3f-4e22-9d6b-111111111111"
 }
}

The response payload just says missing required field: contactId. We’ve tried appending a generated UUID to the request body. Swapped the flowId for the published version ID. Even stripped the routingData object entirely to see if the endpoint would accept a bare minimum call. Nothing sticks. The admin console clearly creates the execution context automatically when a user clicks a button, but the API seems to demand a pre-existing contact record.

We’ve verified the OAuth scopes. The token has admin:flow:write and admin:contact:write. Token generation happens server-side, so expiration isn’t the issue.

Is there a specific payload structure for the initial contact creation that the docs are glossing over? The v2 reference page lists optional fields but doesn’t show a working example for external triggers. We need the flow to start immediately with a custom payload.

Checking the error logs now.

2

Studio scripts handle this much cleaner than raw REST. Drop a REST Proxy snippet in the flow to map the payload correctly before the execution starts.

// Studio REST Proxy Snippet
request.setBody({
 "flowId": flowId,
 "routingData": { "queueId": queueId }
});