> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kombo.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Upsert managed skill
> Create or update a skill in the catalog managed by your system.
This feature is currently available for the following integrations:
You'd like to see this feature for another integration? Please reach out!
We're always happy to discuss extending our coverage.
Stores the skill in Kombo immediately and only sends it to the HRIS during subsequent syncs. This lets you submit thousands of skills without worrying about the rate limits of the remote system.
This endpoint requires the permission **Manage skill catalog** to be enabled in [your scope config](/scopes).
### Example Request Body
```json theme={null}
{
"origin_id": "skill-1",
"name": "TypeScript Programming",
"status": "ACTIVE"
}
```
## OpenAPI
````yaml POST /hris/skills
openapi: 3.1.0
info:
title: Kombo API
version: 1.0.0
servers:
- url: https://api.kombo.dev/v1
description: Kombo EU API
- url: https://api.us.kombo.dev/v1
description: Kombo US API
security:
- ApiKey: []
tags:
- name: General
- name: Kombo Connect
description: >-
Endpoints for Kombo Connect, our end-user-facing flow for setting up new
integrations.
- name: Unified HRIS API
description: Unified endpoints to access all the HR concepts you might need.
- name: Unified ATS API
description: Unified endpoints to access all the ATS concepts you might need.
- name: Unified ATS (Assessment & Background Check) API
description: >-
Unified endpoints to operate Assessments and Background Checks for many
applicant tracking systems.
- name: Unified LMS API
description: Unified endpoints to access all the LMS concepts you might need.
- name: AI Apply
description: Endpoints for AI-powered job application features.
- name: Custom Endpoints
description: Custom integration-specific endpoints.
paths:
/hris/skills:
post:
tags:
- Unified HRIS API
summary: Upsert managed skill
description: >-
Create or update a skill in the catalog managed by your system.
This feature is currently available for the following integrations:
You'd like to see this feature for another integration? Please reach
out!
We're always happy to discuss extending our coverage.
Stores the skill in Kombo immediately and only sends it to the HRIS
during subsequent syncs. This lets you submit thousands of skills
without worrying about the rate limits of the remote system.
This endpoint requires the permission **Manage skill catalog** to be enabled in [your scope config](/scopes).
### Example Request Body
```json
{
"origin_id": "skill-1",
"name": "TypeScript Programming",
"status": "ACTIVE"
}
```
operationId: PostHrisSkills
parameters:
- in: header
name: X-Integration-Id
schema:
type: string
description: ID of the integration you want to interact with.
example: bamboohr:HWUTwvyx2wLoSUHphiWVrp28
required: true
requestBody:
description: POST /hris/skills Request body
content:
application/json:
schema:
$ref: '#/components/schemas/PostHrisSkillsRequestBody'
examples:
example1:
value:
origin_id: skill-1
name: TypeScript Programming
status: ACTIVE
responses:
'200':
description: POST /hris/skills Positive response
content:
application/json:
schema:
$ref: '#/components/schemas/PostHrisSkillsPositiveResponse'
examples:
example1:
value:
status: success
data:
origin_id: skill-1
name: TypeScript Programming
deactivated_at: null
warnings:
- message: This is an example warning!
default:
$ref: '#/components/responses/ErrorResponseHRIS'
components:
schemas:
PostHrisSkillsRequestBody:
type: object
properties:
origin_id:
type: string
description: >-
A stable identifier for this skill in your system. Re-sending the
same `origin_id` updates the skill.
name:
type: string
minLength: 1
description: The name of the skill.
status:
type: string
enum:
- ACTIVE
- INACTIVE
default: ACTIVE
description: >-
The desired status of the skill in the remote HRIS. `INACTIVE`
requests deactivation or archival where supported.
required:
- origin_id
- name
PostHrisSkillsPositiveResponse:
type: object
properties:
status:
type: string
const: success
data:
type: object
properties:
origin_id:
type: string
description: >-
A stable identifier for this skill in your system. Re-sending
the same `origin_id` updates the skill.
name:
type: string
minLength: 1
description: The name of the skill.
deactivated_at:
description: When the skill was deactivated, or `null` if it is active.
type:
- string
- 'null'
format: date-time
externalDocs:
url: >-
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString
required:
- origin_id
- name
- deactivated_at
examples:
- origin_id: skill-1
name: TypeScript Programming
deactivated_at: null
warnings:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
description: >-
These are the interaction warnings that are shown in the dashboard.
They are meant to provide debug information to you. We recommend
logging them to the console.
required:
- status
- data
- warnings
responses:
ErrorResponseHRIS:
description: The standard error response with the error codes for the HRIS use case.
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
error:
type: object
properties:
code:
type:
- string
- 'null'
enum:
- PLATFORM.RATE_LIMIT_EXCEEDED
- PLATFORM.CONCURRENCY_LIMIT_EXCEEDED
- PLATFORM.INTEGRATION_NOT_FOUND
- PLATFORM.INPUT_INVALID
- PLATFORM.UNKNOWN_ERROR
- PLATFORM.IP_NOT_WHITELISTED
- PLATFORM.AUTHENTICATION_INVALID
- PLATFORM.TASK_TIMED_OUT
- INTEGRATION.PERMISSION_MISSING
- INTEGRATION.AUTHENTICATION_INVALID
- INTEGRATION.QA_FAILED
- INTEGRATION.SETUP_SYNC_PENDING
- INTEGRATION.SETUP_INCOMPLETE
- INTEGRATION.INACTIVE
- INTEGRATION.MODEL_NOT_AVAILABLE
- INTEGRATION.MODEL_DISABLED
- INTEGRATION.ACTION_NOT_AVAILABLE
- INTEGRATION.ACTION_DISABLED
- REMOTE.SERVICE_UNAVAILABLE
- REMOTE.RATE_LIMIT_EXCEEDED
- REMOTE.INPUT_INVALID
- REMOTE.UNKNOWN_HTTP_ERROR
- HRIS.STAFFING_ENTITY_CLOSED
- HRIS.EMPLOYEE_ALREADY_EXISTS
example: HRIS.EMPLOYEE_ALREADY_EXISTS
description: >-
Some errors include an error code that can be used to
identify their cause. See the [Error Handling
Docs](https://docs.kombo.dev/guides/errors) for more
information. For your error handling logic please use the
error `code` instead of other properties (e.g. message,
http status code, ...).
title:
type:
- string
- 'null'
description: A static, human-readable label.
message:
type: string
description: >-
A dynamic, detailed description of what went wrong in this
specific instance.
log_url:
type:
- string
- 'null'
format: uri
description: >-
The log page in the Kombo UI lists every interaction with
full details. If you need assistance, share that link with
our support team.
required:
- code
- title
- message
- log_url
description: Error details with structured code for programmatic handling.
required:
- status
- error
examples:
Error Response:
description: >-
When building error handling logic, always use the `code` field
to identify specific error types programmatically. See the
complete list of error codes in the
[docs](https://docs.kombo.dev/guides/errors).
value:
status: error
error:
code: INTEGRATION.MODEL_NOT_AVAILABLE
title: >-
This data model isn't supported for the selected
integration.
message: >-
The "employees" model is not yet available for Greenhouse.
Please reach out to Kombo if you need this functionality.
log_url: https://app.kombo.dev/my-prod/logs?interactionId=123456
Minimal Error Response:
description: >-
The "message" is always required while other fields can also be
`null`. See the [docs](https://docs.kombo.dev/guides/errors) for
more information.
value:
status: error
error:
code: null
title: null
message: The message is always in the response.
log_url: null
securitySchemes:
ApiKey:
type: http
scheme: bearer
description: >-
Create an API key on the [Secrets](https://app.kombo.dev/secrets) page
in the Kombo dashboard.
````
