---
updatedAt: 2026-08-06T09:40:58.000Z
---
Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further.
# Explore Bob Skills API
Understand the basic concepts of Skills in Bob and how to push, sync, and search skills with the Public API
# Overview
The Skills module in Bob helps you define and manage the capabilities your workforce needs to succeed. Skills provide a shared framework for defining the capabilities, behaviors, and proficiency levels that matter across the organization. The Skills catalog serves as a centralized source of truth in Bob, connecting skills to roles, levels, hiring, performance, and learning, so HR, managers, and employees can work from a shared understanding of what success looks like.
The **Bob Skills API** lets you manage your company’s skills framework from an external system. Use it to push skills into Bob, keep them in sync, search for API-origin skills to reconcile, and list the proficiency levels configured for your company.
With this API, you can:
* **List** the company’s **proficiency levels** before attaching level descriptions to skills
* **Bulk create** skills from an external taxonomy (for example, SharePoint or an LMS)
* **Bulk update** and **archive** skills you previously pushed via the API
* **Search** API-origin skills to verify sync outcomes and troubleshoot mismatches
The main integration pattern is **push-and-sync**: your system remains the source of truth for skills it owns, and Bob stores a mirrored copy identified by a stable external locator.
# Before you begin
* Create an **API service user** and generate credentials. To learn more, see [Getting started with the Public API](https://apidocs.hibob.com/docs/getting-started).
* Assign the service user the required **Skills** permissions (see [Required permissions](#required-permissions)).
* Decide on a stable `/skill/source` value for your integration (for example, `sharepoint` or your app name) and map each skill to a unique `/skill/externalId` in that system.
# Key concepts
A **skill** is an entry in the company skills framework in Bob. Each skill has a display name, optional description and category, a lifecycle status, and optional per-level proficiency descriptions.
Skills can be created in Bob’s UI or pushed via the Public API. The Skills API is designed for integrations that import or continuously sync skills from an external system.
**Public API behavior:** Create, update, and archive are always bulk operations (`items` array, 1–100 items). Payloads use the flattened `fieldId: value` contract (for example, `"/skill/name": "Stakeholder Management"`).
Every skill you push through the API **must** include both:
- `/skill/source` — identifies the external system that owns the skill (for example, `sharepoint`)
- `/skill/externalId` — the skill’s unique ID in that external system (for example, `SP-SKILL-001`)
Together, `/skill/source` + `/skill/externalId` form the **stable public identifier** for the skill. This pair must be unique per company.
Use the same identifier on every follow-up sync
> **Important:** Do not use Bob’s internal skill ID (`/skill/id`) to update or archive skills. Write operations resolve skills only by `source` + `externalId`.
Skills fall into two ownership groups:
| Origin | How they were created | Can the Skills API update or archive them? |
| :-------------- | :------------------------------------------- | :-------------------------------------------------------- |
| **API-origin** | Created via `POST /skills` | Yes — only by `/skill/source` + `/skill/externalId` |
| **Bob-created** | Created in Bob’s UI (or other non-API flows) | No — update and archive return not found for these skills |
**Rules to remember:**
- You can **only update and archive skills that were created via this Public API**.
- Skills created in Bob **cannot** be updated or archived through the Skills API, even if you know their Bob ID.
- Search returns **API-origin skills only** (skills that have a `/skill/source` and `/skill/externalId`).
- Skills created via the API appear in Bob as created by a **service user / robot**, not by an employee.
API-origin skills can still be viewed and edited in the Bob UI. If users change them in Bob, reconcile through search and a follow-up sync from your external system.
The company-level scale for skill depth (for example, Beginner, Intermediate, Advanced). These settings define the available levels, their names, and their order across Bob.
The company-level proficiency level settings are read-only in this API.
Use List proficiency levels to discover each level’s numeric `id`, `name`, and `order` before you send skill payloads. The `order` value reflects how levels are configured in Bob; use it for display and mapping, not as a write key.
Skill-specific descriptions explain what each configured proficiency level means for a particular skill. For example, “Advanced” may require different behaviors or knowledge for Leadership than for Data analysis.
Per-skill proficiency descriptions help clarify expectations for roles and career levels, and can support skills-based hiring, performance conversations, development planning, learning recommendations, and skills-gap analysis.
The Skills API can attach or replace the per-skill proficiency descriptions by referencing the company-level proficiency settings.
When you include `/skill/proficiencyLevels` on create or update:
- Proficiency levels for skills include a description for this specific instance of proficiency level
- Updating the array is a **full replacement** of that skill’s per-level descriptions
# Recommended workflow
1. List company proficiency levels and map them to your external scale.
2. Bulk create skills with `/skill/name`, `/skill/source`, and `/skill/externalId` (add category, status, and proficiency-level content as needed).
3. Keep the catalog in sync with bulk update and archive using the same `source` + `externalId` locator.
4. Handle per-item results on every write — a request can succeed overall while individual items fail.
5. Manage the skills catalog in Bob, link to job profiles, job openings and other entities in Bob and use on workflows. Then use reports to export the relevant data.
```mermaid
sequenceDiagram
participant External as External source system
participant Integration as Sync integration
participant Bob as Bob
participant Reports as Reports
External->>Integration: Provide skills taxonomy
Integration->>Bob: Create skills
loop Keep skills current
External->>Integration: Skill data changes
Integration->>Bob: Sync data
end
Bob->>Bob: Manage skills in Bob
Bob->>Reports: Export from Bob with reports
Reports-->>Integration: Share report data
```
# Required permissions
Before using the Skills API, make sure your integration has the required access.
Choose one of the following authentication methods and assign the relevant permissions or scopes:
* **Service user (Basic Auth):** Recommended for customer-built or internal integrations.
* View / search / proficiency levels: `Job catalog > Skills > View skills catalog`
* Create / update / archive: `Job catalog > Skills > Manage skills catalog`
* **OAuth (Bearer token):** Used for marketplace or partner apps only.
* Read: `job_catalog.skills:read`
* Write: `job_catalog.skills:write`
If the calling integration does not have the required permissions, the API returns an authorization error (for example, `403 Forbidden`).
# Skill fields
| Field ID | Description | Notes |
| :------------------------- | :----------------------------------- | :---------------------------------------------------------------------------------------------------------- |
| `/skill/id` | Bob skill ID | Read-only. Returned on create/update success and available in search. Not used as the write locator. |
| `/skill/name` | Skill display name | Required on create. Must be unique per company. |
| `/skill/source` | External system that owns the skill | **Required** on create, update, and archive. Part of the unique locator with `externalId`. |
| `/skill/externalId` | Skill ID in the external system | **Required** on create, update, and archive. Part of the unique locator with `source`. |
| `/skill/description` | Free-text description | Optional. Up to 1000 characters. |
| `/skill/categoryName` | Category display name | Optional. Created if missing on create; must already exist on update. |
| `/skill/status` | Lifecycle status | Optional on create/update. Values: `draft`, `active`, `inactive`. Archive sets `archived`. |
| `/skill/proficiencyLevels` | Per-level descriptions for the skill | Optional. Full replacement when supplied. Each entry needs `proficiencyLevelId` and optional `description`. |
| `/skill/createdAt` | Creation timestamp | Read-only. Available in search. |
# Skills API endpoints
| Use case | Public API endpoints | Comments |
| :-------------------------- | :------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| Discover proficiency levels | [List proficiency levels](/reference/get_skills-proficiency-levels) | Read-only. Use the returned numeric IDs in `/skill/proficiencyLevels` on create and update. |
| Search API-origin skills | [Search skills](/reference/post_skills-search) | Returns only API-origin skills. Filter by source, external ID, status, name, category, or Bob ID. Cursor pagination (`limit` 1–200, default 50). |
| Create skills | [Create skills](/reference/post_skills) | Bulk create (1–100 items). Required per item: `/skill/name`, `/skill/source`, `/skill/externalId`. |
| Update skills | [Update skills](/reference/patch_skills) | Bulk update by `source` + `externalId` only. Applies only to API-origin skills. At least one writable field required per item. |
| Archive skills | [Archive skills](/reference/patch_skills-archive) | Bulk soft-delete by `source` + `externalId` only. Applies only to API-origin skills. Bob-created skills cannot be archived via the API. |
To learn more about request and response schemas, rate limits, and examples, see the [Skills API reference](/reference/skills).
# Bulk writes and item-level results
Create, update, and archive always accept an `items` array and return a `results` array with one outcome per item (matched by `index`).
* The HTTP response is typically **200** even when some items fail.
* Each result includes `status` (`succeeded` or `failed`), an `httpStatus` for that item, and either a `resource` or an `errors` array.
* Always inspect `results` — do not assume every item succeeded because the top-level call returned 200.
Common per-item failures include duplicate `source` + `externalId`, duplicate skill name, missing required fields, unknown proficiency level ID, and locator not found (including when the locator points to a Bob-created skill).
# Exporting skills with Reports
If you need to export skills for an external LMS or analytics tool, Bob also provides skills report templates under **Reports**, including:
* **Skills Catalog** — mirrors the Skills Catalog in Bob
* **Skills assigned to job profiles** — useful when Bob is the source of truth for skill-to-job mapping and another system needs the assignment data
Save the report to a **company folder** so it is available through the Reports Public API. Then retrieve the report ID and download it (for example, as CSV). To learn more, see [Explore Reports API](/docs/explore-reports).
# Related resources
* [Skills API reference](/reference/skills)
* [Explore Job catalog API](/docs/explore-job-catalog-api)
* [Explore Reports API](/docs/explore-reports)
* [Getting started with the Public API](https://apidocs.hibob.com/docs/getting-started)