Employee Skills

Assign, renew, update, and remove skills on individual employees, and upload supporting documents.

🚧

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.

What are Employee Skills?

Employee Skills endpoints manage the skills assigned to individual employees, including issued and expiration dates, certification and training details, cost, notes, and supporting documents.

Each assignment has an employeeSkillKey. Use it to get, update, or delete that assignment.

Before you begin

📘

You need the Employee ID and skillKey

Employee Skills endpoints require a Paylocity Company ID and Employee ID.

  • Employees who already have skills: Call List Company Employee Skills. Each record's assignments array includes the person's Company ID and Employee ID.
  • Employees with no skills yet (for example, assigning someone's first skill): Use the Employee Demographics v2 API to get the Employee ID.
  • skillKey: Get it from List Company Skills. See the Company Skills Overview.

Company set behavior

📘

Employee skills are stored per person, not per Employee ID

Employee skills map to the person (personId). A person can have multiple Employee IDs across different Company IDs in the same company set.

    • GET (single employee): Calling an Employee ID returns all skills for that person, including skills added through their other Employee IDs in other Company IDs within the set. On List Employee Skills and Get Employee Skill, the assignments array contains the Company ID and Employee ID from your request.
    • List Company Employee Skills: Returns assignments for every employee in the company set, once per person. The assignments array lists all of that person's Company ID and Employee ID combinations in the set.
    • Add, update, or delete: Changes apply to the person, so they're visible on all of that person's Employee IDs in the set.

Endpoints

EndpointWhat it does
List Company Employee SkillsGET /companies/{companyId}/employeeSkillsReturns skill assignments for all employees in the company set. Paginated.
List Employee SkillsGET /companies/{companyId}/employees/{employeeId}/skillsReturns skills for one employee, with expiration status. Paginated.
Add Or Renew Employee SkillPOST /companies/{companyId}/employees/{employeeId}/skillsAssigns a skill, or renews it if the employee already has it.
Get Employee SkillGET /companies/{companyId}/employees/{employeeId}/skills/{employeeSkillKey}Returns full details, including document download links.
Update Employee Skill (Partial)PATCH /companies/{companyId}/employees/{employeeId}/skills/{employeeSkillKey}Updates specific fields with JSON Patch.
Delete Employee SkillDELETE /companies/{companyId}/employees/{employeeId}/skills/{employeeSkillKey}Permanently deletes the skill assignment.
Create Employee Skill Document UploadsPOST /companies/{companyId}/employees/{employeeId}/skillDocumentsReserves a document upload and returns a documentKey and upload URL.

How to use each endpoint

List Company Employee Skills

Returns a lightweight summary of every skill assignment in the company set. Filtering and sorting are not supported.

Use cases

  • Pull every employee's skills in one feed to sync a compliance or workforce system.
  • Build a company-wide expiration report using expirationDate and expirationStatus.
  • Find which employees hold a specific skill by matching skillKey.

List Employee Skills

Returns the skills assigned to one employee. Filtering and sorting are not supported.

Use cases

  • Show an employee's skills and certifications in your application.
  • Check whether an employee holds a required skill and whether it's Active, Up for Renewal, or Expired.
  • Get the employeeSkillKey before updating, renewing, or deleting an assignment.

Add Or Renew Employee Skill

Assigns a skill to an employee. Only skillKey is required; include the other fields the skill definition tracks.

  • New skill: Creates a new assignment.
  • Existing skill: Renews the assignment instead of creating a duplicate. The prior values are kept as renewal history, and the employeeSkillKey stays the same.

Use cases

  • Record a certification when an employee passes a course.
  • Renew a license with new issued and expiration dates after recertification.
  • Attach a certificate copy with documentKeys.
🚧

Renewals replace all fields

When renewing, send every value you want the assignment to keep. Any field you leave out is cleared on the renewed assignment.

Get Employee Skill

Returns the full assignment, including certification, training, cost, notes, attached documents, and audit details.

Use cases

  • Show the full certification or license record, such as license number and issuing organization.
  • Download attached documents with each document's downloadUrl.
  • Confirm an update or renewal was applied.
📘

Downloading documents

downloadUrl is short-lived and is null until processingComplete is true. Don't include the Paylocity bearer token when calling it. If the URL expires, call Get Employee Skill again to get a new one.

Update Employee Skill (Partial)

Updates only the fields you reference, using JSON Patch. Returns 204 No Content; call Get Employee Skill to see the result.

Use this to correct or add details. To record a recertification, use Add Or Renew Employee Skill instead.

Use cases

  • Correct a license number or issuing organization.
  • Add notes or training details that weren't available at assignment.
  • Fix an incorrect expiration date.

Example

[
  { "op": "replace", "path": "/certIdNumber", "value": "FL-204858" },
  { "op": "replace", "path": "/notes", "value": "License number corrected." }
]

Delete Employee Skill

Permanently deletes the assignment, including its renewal history and attached documents, for all of the person's Employee IDs in the company set. This can't be undone. The skill definition in the catalog is not affected.

Use cases

  • Remove a skill assigned to the wrong employee.
  • Remove a skill the employee no longer holds when your system is the source of truth.

Create Employee Skill Document Uploads

Reserves a document for each file you want to attach and returns a documentKey and a short-lived upload URL. No file content is sent to this endpoint.

Use cases

  • Attach a scanned certificate or license to a certification record.
  • Upload proof of training completion from a learning platform.

How document upload works

  1. Call this endpoint with each file's fileName, fileSizeBytes, and mimeType.
  2. Save the documentKey returned for each file. You'll need it later to attach the document to the skill.
  3. Upload the file bytes to uploadUrl with uploadHttpMethod. Set Content-Type to the same mimeType, make sure the file size matches fileSizeBytes exactly, and don't include the Paylocity bearer token. Upload right away, because the URL expires shortly after it's issued.
  4. Call Add Or Renew Employee Skill and pass the saved values in documentKeys.
🚧

Documents must be allowed on the skill

The skill definition must have allowDocuments = true. If not, the request is rejected with 400 Bad Request.

Expiration status

StatusMeaning
ActiveThe skill is valid. Skills that don't expire are always Active.
Up for RenewalToday is within the skill's renewalNotification window before the expiration date.
ExpiredThe expiration date has been reached. daysUntilExpiration is 0.

A skill with no renewalNotification goes straight from Active to Expired.

Good to know

  • Inactive skills can't be assigned.
  • Certification fields apply when the skill has includeCertificationFields = true. Training fields apply when it has includeTrainingFields = true. Proficiency applies when it has includeProficiency = true.
  • hasHistory = true means the assignment has been renewed before.
  • Rate limit: 3 requests per second.