POST /api/v2/interactions/{id}/wrapup returns 400 Bad Request

NICE CXone API & Integrations
1

Trying to set a wrap-up code programmatically right after a conversation ends. I have the interaction ID from the webhook event. The docs say I should POST to /api/v2/interactions/{id}/wrapup. I’m sending this JSON payload:

{
 "wrapUpCode": "WU-001",
 "notes": "Call completed"
}

I get a 400 Bad Request every time. The error message just says “Invalid request body” but doesn’t specify what’s wrong. I’ve double-checked that WU-001 exists in the queue settings. I’m using the Python SDK v2.8.0. Here’s the snippet:

response = api_client.interactions_api.post_interactions_wrapup(interaction_id, body=wrapup_data)

Is the endpoint expecting a different structure? Or do I need to include the participant ID in the path? The documentation is pretty vague on the exact payload requirements for the interactions endpoint versus the conversations endpoint. I tried swapping to the conversations API but that seems deprecated for this use case. Stuck on this.

2

The payload structure you’re sending is missing the required participantId. The API needs to know exactly which participant in the conversation you are assigning the wrap-up code to. You can’t just send the code and notes alone.

Here’s how you need to structure the request body:

{
 "participantId": "your-participant-uuid-here",
 "wrapUpCode": "WU-001",
 "notes": "Call completed"
}

Make sure participantId matches the UUID of the agent involved in that specific interaction. If you’re pulling this from a webhook, look for the participantId field in the conversation event payload. Also, double-check that the wrap-up code ID actually exists in your Genesys Cloud instance and is assigned to the correct queue or routing setting. If the code isn’t available to that agent or queue, you’ll still get errors, but the 400 usually points directly to the missing participant reference.

3

The participantId fix is correct, but there’s a silent gotcha with the interaction lifecycle. You can’t just grab the ID from the webhook and fire off the POST immediately. The interaction state needs to be closed or at least post-closed. If the conversation is still technically active in the system, the API rejects the wrapup attempt with that generic 400.

Check the state field in the webhook payload first. If it’s active, wait for the conversation:updated event where state changes to closed.

Also, verify your OAuth scope. The token you’re using needs interaction:write. A lot of people use a token scoped for analytics:read or routing:read for their webhook handlers, which will fail silently or throw 400s when trying to mutate state.

Here’s a quick check using curl to see if the interaction is even ready for wrapup:

curl -X GET "https://api.mypurecloud.com/api/v2/interactions/{interactionId}" \
 -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
 -H "Content-Type: application/json" | jq '.state'

If it returns "active", your timing is off. If it returns "closed", then the payload structure from the previous post should work. Don’t forget to include the participantId in the POST body, not just the code.

One more thing. The wrapUpCode value has to match the ID of a wrap-up code defined in your routing configuration. “WU-001” is likely not the system ID. It’s usually a UUID. Check your routing settings to get the actual ID.