---
title: "Create skills"
method: POST
path: "/skills"
tags: ["Skills"]
---

# Create skills

`POST /skills`

## Request

- Base URL: `https://api.hibob.com/v1`
- URL: `https://api.hibob.com/v1/skills`
- Auth: one of:
  - HTTP basic
  - HTTP bearer

Bulk-create API-origin skills. Always a bulk operation: send an `items` array
(1–100 items). Each item is validated independently and reported per-item in
`results`; the request returns **200** even when some items fail.

Required fields per item: `/skill/name`, `/skill/source`, `/skill/externalId`.
The `/skill/source` + `/skill/externalId` pair must be unique per company, and
`/skill/name` must be unique per company (both within the request and against
existing skills). Unknown proficiency level IDs, duplicate locators, duplicate
skill names, and invalid status values are reported as per-item failures.

**Rate limit:** 10 requests/min per tenant.

**OAuth scope (app-user):** `job_catalog.skills:write`.

**IAM permission:** `Job catalog / Skills / Manage` (company-scoped).

## Request body

- CreateSkillsInput
  - `items` SkillCreateItem[], required: Skills to create (1–100 items).
    - `/skill/name` string, required: Skill display name. Required.
    - `/skill/source` string, required: External source system that owns this skill. Required; combined with `/skill/externalId` it must be unique per company.
    - `/skill/externalId` string, required: External ID of the skill in the source system. Required; combined with `/skill/source` it must be unique per company.
    - `/skill/description` string, nullable: Optional free-text description (up to 1000 characters).
    - `/skill/categoryName` string, nullable: Optional category display name. If the category does not exist it is created.
    - `/skill/status` 'draft' | 'active' | 'inactive': Lifecycle status of a skill.
    - `/skill/proficiencyLevels` ProficiencyLevelAssignment[], nullable: Optional per-skill proficiency-level content. When supplied it becomes the full proficiency-level set for the skill.
      - `proficiencyLevelId` integer, required: Numeric ID of an existing company proficiency level. Discover valid IDs with `GET /v1/skills/proficiency-levels`.
      - `description` string, nullable: Description of what this skill looks like at that proficiency level. Up to 1000 characters.

## Response `200`

Success

- CreateSkillsOutput
  - `results` SkillBulkItemResult[], required: Per-item outcomes, in request order.
    - `index` integer, required: Zero-based index of the item in the request `items` array.
    - `status` string, required: `succeeded` or `failed`.
    - `httpStatus` integer, required: Per-item HTTP-style status (for example `201` created, `200` updated, `404` not found, `409` conflict, `422` unprocessable).
    - `resource` SkillWriteResult: Locator + identity returned for a successfully written skill.
      - `/skill/id` integer, nullable: Bob skill ID of the created or updated skill.
      - `/skill/source` string, nullable: External source system that owns this skill (echoed from the request locator).
      - `/skill/externalId` string, nullable: External ID of the skill in the source system (echoed from the request locator).
    - `errors` SkillBulkItemError[], nullable: Errors describing why the item failed. Present when `status` is `failed`.
      - `code` string, required: Machine-readable error code (for example `VALIDATION_ERROR`, `DUPLICATE_EXTERNAL_LOCATOR`, `DUPLICATE_SKILL_NAME`, `SKILL_NOT_FOUND`).
      - `message` string, required: Human-readable explanation of the failure for this item.

## Other responses

- `400`: Bad request — malformed request, unsupported field or filter, or failed validation.
- `401`: Unauthorized — authentication credentials are missing or invalid.
- `403`: Forbidden — the caller lacks the required Skills permission or OAuth scope.
- `429`: Too many requests — per-tenant rate limit exceeded. Retry after the indicated delay.
- `500`: Internal server error — an unexpected error occurred on the server.

---

[API](https://skmtc.dev/hibob/apis/skills-api.md) - [All operations](https://skmtc.dev/hibob/apis/skills-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hibob/apis/skills-api/revisions/8609962c0add?raw)