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 setSkills 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
| Endpoint | What it does |
|---|---|
List Company Skills GET /companies/{companyId}/skills | Returns the skill catalog for the company set. Paginated. |
Create Skill POST /companies/{companyId}/skills | Adds 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}/skillRemovalRequests | Removes 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
skillKeybefore 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
activeto true will only return active skills, it's the default. Setting it to false will return both active and inactive skills.
- Setting
skillCodeskillDisplayName
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.
TipCall List Company Skills first to avoid creating duplicates. Set
allowDocuments = trueif 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 removedIf 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.
requireDocumentcan only betruewhenallowDocumentsistrue, and the API does not enforce it. An employee assignment without a document is still accepted.expirationInfoandrenewalNotificationusedurationValue + durationUnit(Days or Years).documentConfidentialityvalues:None,Employee,Company,EmployeeandCompany.- Rate limit: 3 requests per second.