---
title: "Update an existing role"
method: PUT
path: "/os/v1/roles/external/{externalCode}"
tags: ["Role", "Role"]
---

# Update an existing role

`PUT /os/v1/roles/external/{externalCode}`

Updates a role identified by `externalCode` in the URL.

**Business rules:**
- `name`, `similarity`, and `externalCode` are required and must not be empty.
- `jobLevel` and `description` must be sent on every request; use `null` or `""` to clear optional values in EO.
- `externalCode` in the body must be unique within the company (cannot match another role's code).

**Errors (HTTP):**
- `404` when no role matches the URL `externalCode` for the company.
- `409` when the new `externalCode` is already used by another role.
- `400` for validation failures (invalid enums, missing keys, empty required strings).

## Path parameters

- `externalCode` string, required

## Request body

- UpdateRolePublicRequestDto
  - `name` string, required — role name
  - `similarity` 'AUXILIARY' | 'CONSULTANT' | 'SUPERVISOR' | 'DEVELOPER' | 'DIRECTOR' | 'INTERNSHIP' | 'SPECIALIST' | 'MANAGER' | 'OPERATOR' | 'TECHNICAL' | 'TRAINEE' | 'COORDINATOR' | 'ANALYST' | 'APPRENTICE' | 'COORDINATOR_OR_SUPERVISOR' | 'ANALYST_OR_AUXILIARY' | 'EXECUTIVE', required — role similarity
  - `jobLevel` 'INTERN' | 'ASSISTANT' | 'JUNIOR' | 'MID_LEVEL' | 'SENIOR' | 'SPECIALIST' | 'EXECUTIVE', nullable, required — role job level; send null or empty string to clear the value in EO
  - `externalCode` string, required — role external code
  - `description` string, nullable, required — role description; send null or empty string to clear the value in EO

## Response `200`

The role has been successfully updated.

## Other responses

- `400` — Bad Request - Validation errors
- `401` — Unauthorized - Invalid or missing token
- `404` — Not Found - role does not exist for the company
- `409` — Conflict - external code already used by another role
- `500` — Internal Server Error - Unexpected failure

---

[API](https://skmtc.net/gupy/apis/gupy-public-api.md) · [All operations](https://skmtc.net/gupy/apis/gupy-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gupy/gupy-public-api/versions/3f26defa2a42/schema)