Set a user’s skill multiplier

When to use this endpoint

Use after obtaining both a user ID and a skill ID. A smaller positive multiplier means less time than the average worker in the skills editor; zero removes the assignment.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Session requests use the dispatcher’s CSRF protection when configured; signed requests follow the API-key authentication flow.

Requires login and an owned tenant user. Ordinary self-profile edits are allowed; editing another user requires client administrator or explicit Users Edit permission. Protected membership fields require that permission even for self. Configured TeamAccess record scope and relationship checks remain in force.

The dispatcher applies configured TeamAccess user-record scope before the handler. An explicit target outside that scope returns an error; omitted targets use the current user for the scope check. Active/deleted filtering and additional target checks are described below.

Parameters

Parameter	Type	Required	Description
`id`	Integer string	Yes	Target user ID in the authenticated tenant. Parsed with intval; this is a single-record operation, with no pagination or sort controls.
`skill_id`	Integer string	Yes	Positive integer-converted tenant skill ID.
`val`	Numeric string	Yes	Finite numeric value from 0 through 10 inclusive, including fractions. Exactly numeric zero removes the assignment. Missing, blank, nonnumeric, nonfinite and out-of-range values are rejected without clearing an existing multiplier.

Example request

$result = FM_api('User_setSkill', [
	'id'=>'1042',
	'skill_id'=>'18',
	'val'=>'0.5',
]);

Example response

{
  "ok": 1
}

Errors and unusual responses

Response	Condition
`{"error":"not logged in"}`	No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
`{"error": "missing or invalid parameter: id"}`	id is omitted, null, or converts to an integer below 1.
`{"error": "missing or invalid parameter: skill_id"}`	skill_id converts below 1.
`{"error": "missing or invalid parameter: val"}`	val is omitted, blank, nonnumeric/nonfinite, nested or outside 0–10.
`{"error": "skill does not exist"}`	Skill lookup fails, checked before the user.
`{"error": "user does not exist"}`	User lookup fails.
`{"error": "user does not exist"}`	No target user belongs to the authenticated account.
`{"error": "only client admins or users with Users edit permission can edit other users"}`	Caller targets another user without explicit edit authority.
`{"error": "Unable to save user changes. Check the saved state before retrying."}`	A checked write/transaction failed; inspect saved state before retrying, especially for separate global identity storage.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

Requires an owned tenant user, an existing skill and the shared User self/editor policy. Skill/user active-state filtering is not added.
Explicit numeric zero removes the relation. A positive finite number replaces it with one multiplier row; duplicates for this user/skill are removed during replacement.
Replacement, user edit markers and skill history are committed together in a checked tenant transaction. An insertion or audit failure restores the previous multiplier; caller savepoints are preserved.

Side effects

Updates tenant skill relationships and user edit markers, records skill history, and invalidates users/employees caches. No global identity fields or notifications are changed.

See it in Fieldmotion

CRM1

Open User Skills in CRM1, select a skill and edit the multiplier. Filter User_setSkill; the UI clamps its numeric input to 0–10.

CRM2

CRM2 User Skills and the User skill widget call User_setSkill with id, skill_id and val after checking the same range in the browser.

Related endpoints

User_setAreas — Replace work-area relationships.
User_setDepartments — Replace department memberships.