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 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.
• Assign the service user the required Skills permissions (see 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

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.

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

Skills API endpoints

To learn more about request and response schemas, rate limits, and examples, see the Skills API reference.

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.

Related resources

• Skills API reference
• Explore Job catalog API
• Explore Reports API
• Getting started with the Public API