I’m working on a Python script to automate our QA assignment workflow. Currently, we use the POST /api/v2/quality/evaluations endpoint to create a blank evaluation form for specific high-value interactions.
However, the API only allows me to associate the form with the conversationId and the agentUserId. It creates the evaluation, but it just sits unassigned in the generic ‘Quality’ view. I need to automatically assign these created evaluations to specific QA supervisors (e.g., Jane grades Team A, Bob grades Team B). I don’t see an evaluatorUserId field in the POST payload for creation. How do I assign an evaluator immediately upon creation?
You are running into a platform security design. The POST endpoint creates the evaluation in a ‘Pending’ state, but assigning an evaluator is technically considered a state change or an assignment action, not a creation property.
You have to use a two-step API process. First, make your POST request to create the evaluation and grab the resulting evaluationId. Immediately after, make a PUT /api/v2/quality/conversations/{conversationId}/evaluations/{evaluationId} request. In the payload of the PUT request, you can set the evaluatorUserId to the specific supervisor’s ID. That will push it directly into their personal QA inbox.
As a campaign manager, we do a lot of automated QA.
Instead of writing a custom Python script to assign forms, have you considered using the native ‘Quality Policies’ engine? You can set up a policy to trigger on specific wrap-up codes or queues, and in the policy actions, you can explicitly define which evaluator or evaluator group should be assigned the form. It handles the assignment automatically without needing API calls.
I do workforce planning, and assigning specific interactions to specific QA folks can skew your sample size!
If you use the API to hand-pick calls, make sure you flag them. In the PUT payload As noted above, there’s a field for isCalibration or you can add custom notes. If you don’t flag them, these manually assigned evaluations will mix with the random samples and throw off your baseline quality metrics for long-term forecasting.
The two-step process mentioned above is technically correct for the API, but it’s a pain point I see constantly in my dashboards. When you automate this via API, you’re bypassing the standard sampling logic, which creates a massive reporting headache later.
If you are going to force-assign evaluators via API, you need to ensure the metadata is clean so it doesn’t break your aggregate reports in Power BI or Tableau. The biggest risk isn’t just the assignment; it’s the data fragmentation. When you mix API-created evaluations with policy-driven ones, the evaluationSource field can behave inconsistently depending on your org’s configuration.
Here is how I handle the payload to keep the analytics clean. You must explicitly set the evaluatorId and, crucially, the evaluationType to ensure it lands in the right bucket for your executive summaries.
evaluation_payload = {
"evaluationId": fetched_evaluation_id,
"evaluatorId": "specific-evaluator-id-here",
"evaluationType": "manual", # Critical for reporting separation
"status": "assigned"
}
# PUT /api/v2/quality/conversations/{conversationId}/evaluations/{evaluationId}
requests.put(url, json=evaluation_payload, headers=headers)
Do not skip the evaluationType field. If you leave it default, it often merges with random samples, skewing your quality scores. I’ve seen this cause entire quarters of data to be invalid because the manual overrides diluted the statistical significance of the random samples. Also, verify that the evaluator you are assigning actually has the quality-evaluator role permission; the API will return a 403 if they only have quality-viewer, and that error won’t always bubble up clearly in your Python logs.