PATCH /api/v2/conversations/voice/{conversationId} transfer action returning 422 for queue target

NICE CXone API & Integrations
1

Background script needs to push active voice calls into a secondary queue. Standard softphone controls don’t fit the current workflow, so we’re hitting the PATCH endpoint directly. Documentation points to conversation modifications, but the payload keeps failing validation. Request structure looks like this:

PATCH /api/v2/conversations/voice/{conversationId}

{
 "actions": [
 {
 "type": "transfer",
 "to": {
 "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
 "type": "routing/queue"
 }
 }
 ]
}

Server throws a 422 Unprocessable Entity. Response body just returns {"errorCode":"validation.error","message":"Invalid action payload"}. Queue ID matches the internal UUID from the routing configuration. Tried swapping routing/queue to just queue. Didn’t work. Wrapped the whole action in a transferTo object based on some older forum threads, but that triggers a 400 now.

Auth token holds conversation:read and conversation:write scopes. Expiry timestamps look fine. Permissions are clean. Queue shows as active in the admin dashboard and actually accepts calls manually. Capacity isn’t the problem. Node script uses axios. Headers set to Accept: application/json and Content-Type: application/json.

Schema might have shifted recently. Docs show transfer as the correct type, but the nested to object probably expects a different shape when targeting a queue instead of a direct agent. Validation error keeps pointing to that nested structure. We’re hitting a wall on the exact syntax.

2

You’re probably passing the queue ID directly in the to object. The transfer action expects a routing target structure, not just a raw ID string. If you don’t wrap it in a routingTarget object with the correct type, the API throws a 422 because it doesn’t know how to interpret the destination.

Try this payload structure instead:

{
 "actions": [
 {
 "type": "transfer",
 "to": {
 "routingTarget": {
 "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
 "type": "queue"
 }
 },
 "type": "blind"
 }
 ]
}

Also check your OAuth scopes. You need conversation:write and routing:write. If the user running the script isn’t an agent or supervisor with access to that specific queue, the validation might pass but the execution will fail silently or return a different error. Make sure the queue ID is actually active and not archived.