Genesys Cloud Recording API: 400 Bad Request when trying to start recording programmatically

I’m trying to build a small script that starts and stops call recordings based on specific IVR menu selections. The goal is to avoid recording the entire call if the user just wants to check their balance. I’ve got the OAuth token working fine for other endpoints, but the recording control is giving me grief.

I’m using the POST /api/v2/recordings/control/recordings endpoint. Here is the JSON payload I’m sending:

{
 "conversationId": "123e4567-e89b-12d3-a456-426614174000",
 "action": "start",
 "reasonCode": "compliance_review"
}

The response is a 400 Bad Request. The error body says "errors": [{"code":"bad_request","message":"Invalid action for current recording state"}]. I’ve double-checked the conversation ID and it’s definitely an active voice call. The documentation implies that start is valid, but maybe I’m missing a prerequisite step? Is there a specific header I need to include, or is this endpoint only for stopping recordings that were started automatically? I’ve tried changing the reasonCode but that didn’t help. Any pointers on what state the recording needs to be in before I can trigger this?

Cause: Missing required fields in the payload. The endpoint needs conversationId and recordingType at minimum, plus the correct OAuth scope recordings:write.

Solution: Send this minimal payload instead:

{
 "conversationId": "your-conv-id-here",
 "recordingType": "agent"
}