Create 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 Create Skill endpoint adds a new skill, certification, or license to the company's skill catalog. You define the skill's code and name, whether it expires, how far ahead renewal is flagged, and which extra details (proficiency, certification, training, documents) are tracked when it is assigned to employees. The skill code must be unique among active skills.

Use Cases

  • A training platform adds a new certification to the client's catalog when the client launches a new course.
  • A compliance tool creates license types (for example, Registered Nurse License) with a 2-year expiration and a 60-day renewal window.
  • Set up a client's full skill catalog during onboarding.

Company Set Behavior

A skill created using one Company ID is visible to every Company ID in the company set. You cannot create a skill for only one Company ID.

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.

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 definition to create.

A skill definition to create.

string
required
length between 1 and 50

A short, unique code for the skill (for example, FORKLIFT). Must be unique among active skills in the company set. Maximum length: 50 characters.

string
required
length between 1 and 100

The name of the skill as it should appear in Paylocity (for example, Forklift Operator Certification). Maximum length: 100 characters.

string | null

A longer description of the skill, such as what it covers or what is required to earn it. Maximum length: 1000 characters.

boolean

Whether the skill is active and can be assigned to employees. true = active; false = inactive.

boolean

Indicates whether the skill expires. When true, employee assignments of this skill track an expiration date, and expirationInfo defines how long the skill stays valid.

expirationInfo
object

How long an employee's skill stays valid after it is issued, before it expires. Should be provided when setExpiration is true. Made up of durationValue and durationUnit (for example, 2 Years).

renewalNotification
object

How far ahead of the expiration date the skill is flagged for renewal, giving admins and employees time to renew it before it expires. Made up of durationValue and durationUnit (for example, 30 Days).

boolean

When true, a proficiency level can be recorded (in the proficiency field) when this skill is assigned to an employee.

boolean

When true, certification details can be recorded when this skill is assigned to an employee: issuingOrganization, issuingState, and certIdNumber.

boolean

When true, training details can be recorded when this skill is assigned to an employee: trainingCourseName, trainingInstructor, trainingHours, trainingScore, and trainingDate.

boolean

When true, documents (such as a copy of a certificate or license) can be attached to employee assignments of this skill. Must be true for documentKeys to be accepted on Add Or Renew Employee Skill.

boolean

Indicates that a document should be attached when this skill is assigned to an employee. Can only be true when allowDocuments is true. This setting is not enforced by the API: an assignment without a document is accepted.

documentCategory
object

The document category that documents attached to this skill are filed under in Paylocity.

string | null

Controls who can view documents attached to this skill. Allowable values: None, Employee, Company, Employee and Company.

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 Company ID 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