> ## 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 employee skill proficiency rating
> Assign a skill to an employee with an optional proficiency rating, attributed to the provider configured in the settings. Re-sending the same skill and source overwrites the existing rating.
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.
This endpoint requires the permission **Manage employee skill proficiency ratings** to be enabled in [your scope config](/scopes).
### Example Request Body
```json theme={null}
{
"employee_id": "26vafvWSRmbhNcxJYqjCzuJg",
"skill_id": "28KMdr68N8kG9EzLwjsN9aoz",
"rating": {
"rating_source": "EXTERNAL",
"proficiency": 4
}
}
```
## OpenAPI
````yaml POST /hris/skill-proficiency-ratings
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/skill-proficiency-ratings:
post:
tags:
- Unified HRIS API
summary: Upsert employee skill proficiency rating
description: >-
Assign a skill to an employee with an optional proficiency rating,
attributed to the provider configured in the settings. Re-sending the
same skill and source overwrites the existing rating.
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.
This endpoint requires the permission **Manage employee skill proficiency ratings** to be enabled in [your scope config](/scopes).
### Example Request Body
```json
{
"employee_id": "26vafvWSRmbhNcxJYqjCzuJg",
"skill_id": "28KMdr68N8kG9EzLwjsN9aoz",
"rating": {
"rating_source": "EXTERNAL",
"proficiency": 4
}
}
```
operationId: PostHrisSkillProficiencyRatings
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/skill-proficiency-ratings Request body
content:
application/json:
schema:
$ref: '#/components/schemas/PostHrisSkillProficiencyRatingsRequestBody'
examples:
example1:
value:
employee_id: 26vafvWSRmbhNcxJYqjCzuJg
skill_id: 28KMdr68N8kG9EzLwjsN9aoz
rating:
rating_source: EXTERNAL
proficiency: 4
responses:
'200':
description: POST /hris/skill-proficiency-ratings Positive response
content:
application/json:
schema:
$ref: >-
#/components/schemas/PostHrisSkillProficiencyRatingsPositiveResponse
examples:
example1:
value:
status: success
data:
id: 8AvRLpxwY5J6pGxfY6fUD81Z
remote_id: 238476582-99123
employee_id: 26vafvWSRmbhNcxJYqjCzuJg
skill_id: 28KMdr68N8kG9EzLwjsN9aoz
proficiency:
selected_option_id: 3aKMdr68N8kG9EzLwjsN4
type: SINGLE_SELECT
rating_source: EXTERNAL
rating_provider_id: 7xPdr68N8kG9EzLwjsN9xyz
changed_at: '2022-08-07T14:01:29.196Z'
remote_deleted_at: null
remote_data: null
custom_fields: null
integration_fields: []
warnings:
- message: This is an example warning!
default:
$ref: '#/components/responses/ErrorResponseHRIS'
components:
schemas:
PostHrisSkillProficiencyRatingsRequestBody:
type: object
properties:
employee_id:
type: string
description: The Kombo ID of the employee.
skill_id:
type: string
description: The Kombo ID of the skill.
rating:
discriminator:
propertyName: rating_source
oneOf:
- type: object
properties:
rating_source:
type: string
const: EXTERNAL
description: >-
Marks this as an externally-produced rating (e.g. from an
assessment, labor-market enrichment, or inference engine).
It is attributed to the provider configured in the settings.
proficiency:
oneOf:
- type: number
format: double
- type: string
- type: 'null'
description: >-
The proficiency to record. For a `NUMERIC` skill, submit the
numeric value (within the scale's `min`–`max` range). For a
`SINGLE_SELECT` skill, submit the ID of the proficiency
option. Omit to assign the skill without a rating.
required:
- rating_source
required:
- employee_id
- skill_id
- rating
PostHrisSkillProficiencyRatingsPositiveResponse:
type: object
properties:
status:
type: string
const: success
data:
type: object
properties:
id:
type: string
description: >-
The globally unique ID of this object generated by Kombo. We
recommend using this as a stable primary key for syncing.
remote_id:
type: string
description: >-
The raw ID of the object in the remote system. We don't
recommend using this as a primary key on your side as it might
sometimes be compromised of multiple identifiers if a system
doesn't provide a clear primary key.
employee_id:
type: string
description: >-
The Kombo ID of the employee. Can be used to retrieve the
employee from the `get employees` endpoint.
skill_id:
type: string
description: >-
The Kombo ID of the skill. Can be used to retrieve the skill
from the `get skills` endpoint.
proficiency:
discriminator:
propertyName: type
anyOf:
- type: object
properties:
type:
type: string
const: NUMERIC
value:
type: number
format: double
description: The numeric proficiency value on the scale.
required:
- type
- value
- type: object
properties:
type:
type: string
const: SINGLE_SELECT
selected_option_id:
type: string
description: >-
The Kombo ID of the selected option on the scale
(`proficiency_scale.ordered_options[].id`).
required:
- type
- selected_option_id
- type: 'null'
description: >-
The selected value on the scale. `null` when the skill is
assigned to the employee but not rated. The scale itself lives
on the skill.
rating_source:
type:
- string
- 'null'
enum:
- SELF
- MANAGER
- EXPECTED
- EXTERNAL
description: >-
Who produced this rating. `SELF` – self-assessed by the
employee; `MANAGER` – assessed by their manager; `EXPECTED` –
the level expected for the employee; `EXTERNAL` – written by an
external provider system (e.g. an assessment, labor-market
enrichment, or inference engine). `null` when unknown.
rating_provider_id:
type:
- string
- 'null'
description: >-
The external provider that produced the rating. Only set on
`EXTERNAL` ratings, `null` otherwise.
changed_at:
description: >-
The timestamp when this specific record was last modified. This
field only updates when properties directly on this record
change, NOT when related or nested models change. For filtering
that considers nested data changes, use the `updated_after`
parameter which will return records when either the record
itself OR its related models have been updated.
type: string
format: date-time
externalDocs:
url: >-
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString
remote_deleted_at:
description: >-
The date and time the object was deleted in the remote system.
Objects are automatically marked as deleted when Kombo can't
retrieve them from the remote system anymore. Kombo will also
anonymize entries 14 days after they disappear.
type:
- string
- 'null'
format: date-time
externalDocs:
url: >-
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString
remote_data:
type:
- object
- 'null'
additionalProperties: true
description: >-
Includes the data fetched from the remote system.
Please be aware that including this in you scope config might
violate other
scopes that are set.
Remote data always has the endpoint path that we got the data
from as the
top level key. For example, it could look like: `{ "/companies":
{ ... }}`
This is not available on all plans. Reach out to Kombo if you
need it.
custom_fields:
type:
- object
- 'null'
additionalProperties: true
description: >-
A key-value store of fields not covered by the schema. [Read
more](/custom-fields)
integration_fields:
type: array
items:
type: object
properties:
id:
type: string
description: The globally unique ID of this object.
key:
type: string
description: The key of the field in the remote system.
type:
type: string
enum:
- DEFAULT
- CUSTOM
description: |-
- `DEFAULT`: static fields in the remote system.
- `CUSTOM`: fields that are created/editable by the user.
value:
type: 'null'
description: The field's value.
label:
type:
- string
- 'null'
description: The label of the field. (not always available)
required:
- id
- key
- type
- label
description: >-
An array of selected passthrough integration fields. [Read
more](/integration-fields)
examples:
- - id: 5NVFhMpB9Ah6by44tzNjZLyE
key: firstName
type: DEFAULT
value: Frank
label: First Name
- id: 8nuajYpoRd5GnxEQaaWKUDYQ
key: customTshirtSize
type: CUSTOM
value: XL
label: T-Shirt Size
required:
- id
- remote_id
- employee_id
- skill_id
- rating_source
- rating_provider_id
- changed_at
- remote_deleted_at
- remote_data
- custom_fields
- integration_fields
examples:
- id: 8AvRLpxwY5J6pGxfY6fUD81Z
remote_id: 238476582-99123
employee_id: 26vafvWSRmbhNcxJYqjCzuJg
skill_id: 28KMdr68N8kG9EzLwjsN9aoz
proficiency:
selected_option_id: 3aKMdr68N8kG9EzLwjsN4
type: SINGLE_SELECT
rating_source: EXTERNAL
rating_provider_id: 7xPdr68N8kG9EzLwjsN9xyz
changed_at: '2022-08-07T14:01:29.196Z'
remote_deleted_at: null
remote_data: null
custom_fields: null
integration_fields: []
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.
````
