Company Skills

🚧

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 Company Skills?

Company Skills endpoints manage the company's skill catalog: every skill, certification, and license the company tracks. Each skill definition controls how the skill behaves when it's assigned to employees, including:

  • Whether it expires and how long it stays valid (setExpiration, expirationInfo)
  • How far ahead it's flagged for renewal (renewalNotification)
  • Which extra details are tracked: proficiency, certification fields, training fields
  • Whether documents can be attached, and who can see them (allowDocuments, documentCategory, documentConfidentiality)

Every skill has a skillKey. You will need to use this key to assign the skill to employees.

Company set behavior

📘

Skills apply to the entire company set

Skills are stored at the company set level, not by Company ID. A skill added in one Company ID applies to every Company ID in the set. You can't designate a skill for one Company ID only.

  • GET: When you call with a Company ID, the response includes all skills in the company set, not only skills created under that Company ID. Calling any Company IDs in the same set will return the same catalog.
  • Create: A skill created through one Company ID is visible to every Company ID in the set.
  • Update: Changes apply to the skill for every Company ID in the set and to employees who have the skill.
  • Remove: Removing a skill removes it for every Company ID in the set.

Endpoints

EndpointWhat it does
List Company Skills GET /companies/{companyId}/skillsReturns the skill catalog for the company set. Paginated.
Create Skill POST /companies/{companyId}/skillsAdds a new skill to the catalog. skillCode and skillDisplayName are required.
Get Skill GET /companies/{companyId}/skills/{skillKey}Returns one skill definition and its settings.
Update Skill (Partial) PATCH /companies/{companyId}/skills/{skillKey}Updates specific fields with JSON Patch.
Request Skill Removal POST /companies/{companyId}/skillRemovalRequestsRemoves one or more skills and reports the result for each.

How to use each endpoint

List Company Skills

Use this as your starting point. It returns the full catalog with each skill's settings.

Use cases

  • Sync a client's full catalog during setup, then periodically to pick up changes.
  • Look up a skillKey before assigning a skill, for example ?skillCode=FORKLIFT.
  • Show users only skills they can assign with ?active=true.

Filters (partial, case-insensitive matches; can be combined):

  • active (true/false)
    • Setting active to true will only return active skills, it's the default. Setting it to false will return both active and inactive skills.
  • skillCode
  • skillDisplayName

Sorting is not supported.

Create Skill

Adds a new skill, certification, or license to the catalog. skillCode must be unique among active skills in the company set.

Use cases

  • A training platform adds a new certification when the client launches a new course.
  • A compliance tool creates a license type, such as a Registered Nurse License with a 2-year expiration and a 60-day renewal window.
  • Set up a client's catalog during onboarding.
📘

Tip

Call List Company Skills first to avoid creating duplicates. Set allowDocuments = true if you plan to attach certificates or licenses to employee assignments.

Get Skill

Returns one skill definition.

Use cases

  • Check a skill's settings before assigning it, such as whether it expires or allows documents.
  • Confirm that an update was applied.

Update Skill (Partial)

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

Use cases

  • Deactivate a skill (/active = false) so it can't be assigned, without removing existing employee records.
  • Change how long a skill stays valid or how far ahead renewal is flagged.

Example

[
  { "op": "replace", "path": "/active", "value": false },
  { "op": "replace", "path": "/renewalNotification", "value {"durationValue":90} }
]

Request Skill Removal

Removes one or more skills from the catalog. The response reports a result for each skillKey: Deleted, NotFound, or Failed.

Use cases

  • Clean up skills that are no longer used, such as a retired certification.
  • Remove skills created in error during setup.
📘

Skills assigned to employees can't be removed

If a skill is still assigned to any employee in the company set, the result is Failed. Delete the employee assignments first, or set active to false with Update Skill (Partial) to stop new assignments and keep history.

Good to know

  • Inactive skills can't be assigned to employees.
  • requireDocument can only be true when allowDocuments is true, and the API does not enforce it. An employee assignment without a document is still accepted.
  • expirationInfo and renewalNotification use durationValue + durationUnit (Days or Years).
  • documentConfidentiality values: None, Employee, Company, Employee and Company.
  • Rate limit: 3 requests per second.