Predictive Routing: 500 Internal Server Error when Mapping Zendesk Tags to GC Skills via Platform API

The flexibility of GC is amazing, but I have hit a snag with the Platform API while setting up Predictive Routing.

In Zendesk, we used simple tags to route tickets to specific agent groups. I am trying to replicate this by creating Skills in GC and assigning them to agents, then using the Platform API to update agent profiles with these skills based on the incoming interaction data.

I am using the PATCH endpoint /v2/users/{id} to assign skills. However, I am receiving a 500 Internal Server Error with the message "Internal Server Error" in the response body. The request payload looks like this:

{
 "skills": [
 {
 "id": "abc-123-def-456",
 "level": 10
 }
 ]
}

I have verified that the skill ID exists in the eu-01 region and that the user has the admin role. In Zendesk, this was as simple as adding a tag. I am sure GC offers more granular control, but this error is blocking my migration progress.

Could this be related to the skill not being published yet? Or is there a specific permission required on the user object that I am missing? Any practical advice on mapping Zendesk tags to GC skills for Predictive Routing would be incredibly helpful. I am eager to get this working so we can leverage the advanced AI routing capabilities!

You need to stop patching user profiles in real-time because the API latency will kill your ACD performance. don’t try to map tags to skills on the fly; use Architect to read the inbound attributes and route directly to the matching queue instead.

Have you tried looking at the skill group assignment limits? i’m a supervisor so i don’t touch the api much, but my tech guy warned me about this exact error. it’s not just latency. the system chokes if you try to update too many users at once or if the skill doesn’t exist yet.

1. check if the skill is actually created in admin first. you can’t assign a ghost skill.
2. make sure the agent isn’t already in the skill. duplicate patches fail.
3. use a queue instead. really. architect handles this better.

we tried the api route once. it broke our wait times. now we just map the zendesk tag to an attribute and let architect route to the right queue. much smoother. don’t fight the api on user updates. it’s a trap.

{
“reply”: “i think the issue isn’t just the latency, it’s the payload structure. if you’re patching routing.skills you need to send the full array, not just the new skill. the api replaces the whole list. if you miss one, the agent loses it.\n\nalso, make sure the skill id is correct. a 500 error often means the backend is choking on a malformed id or a division mismatch. i tried this last week and kept getting 500s until i realized i was using the skill name instead of the uuid.\n\nhere is what the patch body should look like:\n\njson\n{\n \"routing\": {\n \"skills\": [\n {\n \"id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"level\": 50,\n \"rank\": 1\n },\n {\n \"id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n \"level\": 25,\n \"rank\": 2\n }\n ]\n }\n}\n\n\nif you’re doing this for every ticket, you’re going to hit rate limits hard. i think you should cache the user’s current skills in your zendesk integration, add the new one locally, and only send a patch if the array actually changes. duplicate patches fail silently or throw errors.\n\nalso, check the division. if the skill is in ‘default’ and the user is in ‘sales’, the api might reject it. i spent two days on this. the docs don’t make it clear that skills and users must share a division or the skill must be public.\n\nWarning: the /v2/users endpoint has strict rate limits. if you hammer it during peak hours, your whole integration might get throttled. use a queue for the api calls, not direct triggers.”
}

The problem here is the payload structure. you can’t just append. the api replaces the whole list.

{“error”: “Invalid skill assignment”}

send the full array or you lose skills.

PATCH /api/v2/users/{id}
{
 "routing": {
 "skills": [
 { "id": "skill-123", "level": 50 }
 ]
 }
}