Add Or Renew Employee Skill

🚧

Early Access (EA)

This API is currently in Early Access and available only to approved EA participants. Do not rely on this version for production workloads unless explicitly authorized. If you have any feedback, please share with your designated Early Adoption program representative.

Summary Description

The Add Or Renew Employee Skill endpoint assigns a skill to an employee. If the employee already has this skill, the existing assignment is renewed instead of creating a duplicate: the previous values are kept as renewal history, and the assignment keeps the same employeeSkillKey. Include the details the skill tracks, such as issued and expiration dates, certification details, training details, and any documents to attach.

Renewals replace all fields. When renewing, send every value you want the assignment to keep. Any field you omit is cleared on the renewed assignment.

Use Cases

  • A training platform records a certification on the employee's profile when they pass a course.
  • A compliance tool renews a license with a new issued date and expiration date after the employee recertifies.
  • Attach a certificate copy by including documentKeys from Create Employee Skill Document Uploads.

Company Set Behavior

Employee skills are stored per person (personId). The skill is assigned to the person behind this Employee ID, so it is visible on all of that person's Employee IDs within the company set.

Path Params
string
required
length ≤ 9

The Paylocity Company ID. This is the unique value provided by Paylocity to each specific payroll entity. Skills are shared across the company set, so this Company ID determines which company set is used.

string
required
length ≤ 10

The Paylocity Employee ID. This is a unique value per Paylocity Company ID. The skill is assigned to the person behind this Employee ID and is visible on all of their Employee IDs in the company set.

Query Params
boolean
Defaults to false

When true, returns sample (mocked) responses without reading or changing any real data, and without validating the request body. Authentication and company access are still checked. Use for integration testing only. Must be true or false. Default: false.

Body Params

The skill assignment to add or renew. Only skillKey is required; send the other fields that apply to the skill definition.

A skill assignment to add or renew. Only skillKey is required; send the other fields that apply to the skill definition.

uuid
required

The unique identifier (UUID) of the skill definition to assign. Get this value from List Company Skills. If the employee already has this skill, the existing assignment is renewed instead of a new one being created.

date-time | null

The date the employee earned or was issued the skill, certification, or license. ISO 8601 date-time format (for example, 2026-01-15T00:00:00Z).

date-time | null

The date the employee's skill, certification, or license expires. ISO 8601 date-time format. Leave null if the skill does not expire.

string | null

The employee's proficiency level for this skill. Applies when the skill definition has includeProficiency = true.

string | null

The organization that issued the certification or license (for example, American Red Cross). Applies when the skill definition has includeCertificationFields = true. Maximum length: 100 characters.

string | null

The state or region that issued the certification or license (for example, CO). Applies when the skill definition has includeCertificationFields = true. Maximum length: 100 characters.

string | null

The certification or license identification number. Applies when the skill definition has includeCertificationFields = true. Maximum length: 20 characters.

string | null

The name of the training course the employee completed. Applies when the skill definition has includeTrainingFields = true. Maximum length: 100 characters.

string | null

The name of the instructor who delivered the training. Applies when the skill definition has includeTrainingFields = true. Maximum length: 100 characters.

date-time | null

The date the employee completed the training. ISO 8601 date-time format. Applies when the skill definition has includeTrainingFields = true.

double | null

The number of training hours completed. Decimals are allowed (for example, 7.5). Applies when the skill definition has includeTrainingFields = true.

string | null

The score the employee achieved on the training assessment, sent as text (for example, 92 or Pass). Applies when the skill definition has includeTrainingFields = true. Maximum length: 100 characters.

double | null

The cost incurred for the employee to obtain the certification or training (for example, 150.00).

string | null

Free-form notes about this skill assignment. Maximum length: 1000 characters.

documentKeys
array of uuids | null

A list of documentKey values (UUIDs) to attach to this assignment. Get each documentKey from Create Employee Skill Document Uploads, and upload the file bytes to its uploadUrl before calling this endpoint. Only accepted when the skill definition has allowDocuments = true; otherwise the request is rejected with 400 Bad Request.

documentKeys
Responses

401

Unauthorized. The bearer token is missing, invalid, or expired. Request a new access token and try again.

403

Forbidden. The token is valid, but the API client is not authorized to access this API or this company.

404

Not Found. The Employee ID or skillKey was not found.

429

Too Many Requests. The API client exceeded the rate limit of 3 requests per second. Wait briefly, then retry using a backoff strategy.

Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json