Sign in

v1

latestOpenAPI 3.0.02026-07-24161168406.5 KB
Role
Role

Create a new role

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.
post/os/v1/roles

Request body

namestring 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

externalCodestring required

role external code

descriptionstring

role description

Example request

{
  "name": "Analista de Negócios",
  "similarity": "CONSULTANT",
  "jobLevel": "ASSISTANT",
  "externalCode": "RL-F98",
  "description": "Software Architect"
}

Response

The role has been successfully created.

uuidstring uuid required

role UUID

namestring 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

externalCodestring required

role external code

descriptionstring nullable required

role description

positionsnumber[]

internal position IDs linked to the role (when expand=positions)

Example response

{
  "name": "Analista de Negócios",
  "similarity": "CONSULTANT",
  "jobLevel": "ASSISTANT",
  "externalCode": "RL-F98",
  "description": "Software Architect",
  "company": {
    "id": "1",
    "name": "Gupy"
  },
  "positions": [
    1,
    2
  ]
}