CXone Admin API bulk-update agent skill proficiencies via REST

NICE CXone API & Integrations
1

Is it possible to bulk-update agent skill proficiencies via REST? The docs state:

“To modify multiple skills, send a POST request to /api/v2/users/{userId}/skills with an array of skill objects.”

However, my payload:

[ { "skillId": "123", "proficiency": "Expert" } ]

returns 405 Method Not Allowed. I see no PUT endpoint for bulk operations. Does the Admin API support batch updates for {userId}/skills, or must I loop through PATCH /api/v2/users/{userId}/skills/{skillId} individually?

2

This is caused by a mismatch in the HTTP method and endpoint structure for bulk skill updates. The documentation you cited refers to a specific resource that requires POST, but your payload structure might be triggering validation errors if the endpoint expects a different envelope.

  • Verify the Endpoint: Ensure you are hitting /api/v2/users/{userId}/skills and not a nested path. The platform uses POST for creating/updating associations in this context.
  • Check Content-Type: Explicitly set Content-Type: application/json. Some SDKs default to x-www-form-urlencoded, which causes 405 or 400 errors.
  • Use the Correct Proficiency Enum: Proficiency is often an integer or a specific string enum (e.g., “Novice”, “Proficient”, “Expert”) depending on your org’s skill profile configuration. Check the skillProfile definition first.
  • Try a Single Update First: Isolate the issue by sending a single skill object. If that works, the problem is likely in the array formatting or rate limiting on the batch.

Here is a corrected curl example:

curl -X POST "https://api.mypurecloud.com/api/v2/users/{userId}/skills" \
 -H "Authorization: Bearer {access_token}" \
 -H "Content-Type: application/json" \
 -d '[
 {
 "skillId": "123",
 "proficiency": "Expert"
 }
 ]'
3

The simplest way to resolve this is to abandon the direct REST call for bulk operations and instead utilize the asynchronous job API. The endpoint /api/v2/users/{userId}/skills is designed for single-user, synchronous updates. When you attempt to pass an array or a batch payload to a singular resource endpoint, the platform’s validation layer rejects it with a 405 because it expects a single object, not a list. For bulk modifications, you must use the POST /api/v2/analytics/bulkdata/queries or the specific user management bulk endpoints if available in your specific org tier, but typically skill updates are handled via the PATCH /api/v2/users/{userId} with a skills array in the body.

However, the most robust method for large-scale updates is to construct a proper JSON payload for the single-user PATCH and execute it via a script or orchestration tool, rather than trying to force a bulk REST call that doesn’t exist for skills. The proficiency field is often case-sensitive and must match the exact enum values defined in your organization’s skill configuration.

PATCH /api/v2/users/{userId}
Content-Type: application/json

{
 "skills": [
 {
 "skillId": "123",
 "proficiency": "Expert"
 }
 ]
}

Be aware that directly PATCHing user skills bypasses any WFM integration constraints. If your org uses WFM for scheduling, these manual API updates can cause immediate conflicts in the scheduler if the proficiency levels do not align with the forecasted demand. Always verify the target user’s current shift status before applying bulk changes. I have seen this cause significant issues in our Snowflake extracts when the proficiency data drifts from the WFM source of truth. Use the platformClient.Users.patchUser(userId, body) method in the SDK to handle the authentication and header management automatically.