---
title: "Create a new role"
method: POST
path: "/os/v1/roles"
tags: ["Role", "Role"]
---

# Create a new role

`POST /os/v1/roles`

Creates a new role (cargo) for the company resolved from the API token.

**Business rules:**
- `name`, `externalCode`, and `similarity` are required.
- `externalCode` must be unique among active roles for the same company.
- `jobLevel` is optional: omit the field, send `null`, or send an empty string (`""`)—empty string is normalized to `null` before persistence.
- `description` is optional: omit the field, send `null`, or send an empty string.

**Validation:**
- Invalid enum values for `similarity` or `jobLevel`, or other constraint violations return 400 with validation details.

## Request body

- CreateRolePublicRequestDto
  - `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 — role job level; empty string is accepted and normalized to null
  - `externalCode` string, required — role external code
  - `description` string — role description

## Response `201`

The role has been successfully created.

- RoleResponseDto
  - `uuid` string, uuid, required — role UUID
  - `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
  - `externalCode` string, required — role external code
  - `description` string, nullable, required — role description
  - `company` CompanyDto
    - `id` string — Internal company ID
    - `uuid` string, uuid — company UUID
    - `centralCompanyId` string, uuid — central company UUID
    - `name` string — company name
  - `positions` number[] — internal position IDs linked to the role (when expand=positions)

## Other responses

- `400` — Bad Request - Validation errors
- `401` — Unauthorized - Invalid or missing token
- `409` — Conflict - A role with the same external code already exists for the company
- `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/revisions/3f26defa2a42/schema)