Skill Ratings API


The Skill Ratings API is for retrieving skill ratings for a given entity.


Endpoint

/1.0/skillratings


Objects used by this API

Skill Stats object

Represents a skill with aggregated stats based on the average levels of multiple people. Returned for Teams, Roles and Locations

Name Data type Read only Description
skill_id integer Yes The unique identifier, used to identify the skill.
skill_name string Yes Skill name
type string Yes The type of ratings provided in this object. One of "average" (default), "self" or "supervisor", determined by the "type" parameter below.
skill_level decimal Yes The skill level, rounded to two decimal places.
interest_level decimal Yes The interest level, rounded to two decimal places.

Person-Skill object

Represents a skill associated with a specific person. Returned for People only

Name Data type Read only Description
skill_id integer Yes The unique identifier, used to identify the skill.
skill_name string Yes Skill name
type string No The type of ratings provided in this object. One of "average" (default), "self" or "supervisor".
skill_level decimal No The skill level, rounded to two decimal places.
interest_level decimal No The interest level, rounded to two decimal places.
target_level integer
Yes The target skill level (Available end-H2 2025)


Methods

GET /skillratings

Gets Skill Ratings for the Organization.


GET /skillratings/person/:id

Gets Skill Ratings for the specified Person.


GET /skillratings/team/:id

Gets Skill Ratings for the specified Team.


GET /skillratings/role/:id

Gets Skill Ratings for the specified Role.


GET /skillratings/location/:id

Gets Skill Ratings for the specified Location.


POST /skillratings/person/:id

Sets skill ratings for a person based on the provided skill rating values. The user attributed to conducting the assessment is defined in configuration settings and must be a valid account within the People Directory. 


Name

Data type

Description
skill_ratings

array (Skill Rating)

An array of Person-Skill objects as defined above. Note that the “skill_name” property is not required for this endpoint.

send_notifications boolean

"true" or "false" indicating whether to email a summary of changes to all impacted people as well as their supervisors. Email will only be sent where a rating has changed (ie: differs from previous rating). The default value is false. 

rejection_workflow boolean

"true" or "false" indicating whether supervisors will have the ability to reject specific changes, within the rejection window. The default value is false.



Query string parameters

GET methods within this endpoint accept the following additional optional parameters, passed via URL query string:

Parameter name Data type Accepted values Description
type string "self", "supervisor" Optional. If specified, will return only self-assessment or supervisor assessment ratings depending on the value provided. If this parameter is omitted averaged ratings will be returned by default.
detail string "summary", "person" Optional. When "summary" is specified,a collection of Skill Rating objects is returned, with summary (averaged) skill and interest levels calculated for all people holding that skill. When "person" is specified, a collection of people is returned, with each person containing a collection of their own skills.
This parameter is currently only supported for the team, location, and role endpoints and has no effect on the person endpoint (which always returns "summary" data).
modified_on_or_after date Any valid date in the format YYYY-MM-DD Returns only skill ratings modified on or after the specified date