CXone Admin API 400 error on bulk skill update

NICE CXone API & Integrations
1

Does anyone know why my POST to /api/v2/users/{userId}/proficiencies returns a 400 Bad Request? I am trying to update skills in bulk as per the CXone Admin API docs.

The documentation states “The request body must contain an array of proficiency objects.” I copy-pasted the structure exactly but the server rejects it immediately.

Here is the payload I am sending: { "proficiencies": [ { "skillId": "123", "proficiency": "A" } ] }. Why is this failing?

2

Ah, this is a recognized issue…

The CXone API documentation for PUT /api/v2/users/{userId}/proficiencies often omits the strict typing requirements for the proficiency field. The server expects the proficiency value to be a specific enum string (e.g., “A”, “B”, “C”, “D”, “E”) but also requires the skillId to be a valid UUID, not just a numeric string like “123”.

Here is the corrected Python SDK approach using PureCloudPlatformClientV2:

from purecloudplatformclientv2 import ApiClient, Configuration, UsersApi, Proficiency

config = Configuration()
api_client = ApiClient(configuration=config)
users_api = UsersApi(api_client)

# Ensure skill_id is a valid UUID
skill_id = "12345678-1234-1234-1234-123456789abc"

proficiency_obj = Proficiency(
 skill_id=skill_id,
 proficiency="A" # Must be valid enum
)

try:
 users_api.put_users_user_proficiencies(user_id="target-user-uuid", body=[proficiency_obj])
 print("Update successful")
except Exception as e:
 print(f"Error: {e}")

Verify your skillId is a full UUID. If it remains a 400, check the errors array in the response body for specific field violations.

3

Generally… stop wrestling with validation, fix the input data first. I push these bulk updates through a Workflow that maps skill IDs to the internal CXone UUIDs and validates the proficiency level before the API call. This avoids most 400s.

{
 "proficiencies": [
 {
 "skillId": "mapped UUID here",
 "proficiency": "validated level"
 }
 ]
}

Look into using a Workflow to pre-process the data and ensure the skillId is the correct format and proficiency is a valid enum value. Check the CXone documentation for accepted proficiency levels.

3 Likes