---
title: "Create a new Position"
method: POST
path: "/os/v1/positions"
tags: ["Position", "Position"]
---

# Create a new Position

`POST /os/v1/positions`

Creates a new position with the provided data.

**Business Rules:**

• Role (externalCodeRole) is required and must exist

• Area (externalCodeArea) is required and must exist

• External code must be unique within the company

• Parent position is optional - if not specified, creates a root position

• Only one root position allowed per company

• Employee can only be assigned to one position at a time

• Employee assignment is optional (position can be vacant)

• Operation Unit (externalCodeOperationUnit) is optional - if provided, must exist

## Request body

- CreatePositionInput
  - `externalCode` string — Unique external code to identify the position within the company. If not provided, it will be auto-generated.
  - `name` string, required — Human-readable name for the position
  - `externalCodeRole` string, required — External code of the role to associate with this position
  - `externalCodeArea` string, required — External code of the area to associate with this position
  - `description` string, nullable — Optional detailed description of the position responsibilities and requirements
  - `externalCodeCostCenter` string — Optional external code of the cost center to associate with this position
  - `externalCodeParent` string — Optional external code of the parent position in the organizational hierarchy
  - `parentIdentifier` string — Optional identifier (email or CPF) of the employee who occupies the parent position. Can be used alone to find the parent position, or together with externalCodeParent for validation.
  - `employeeEmail` string, email — Optional email address of the employee to assign to this position
  - `employeeTaxPayerRegistry` string — Optional tax payer registry (CPF) of the employee to assign to this position. Must be a valid CPF format.
  - `employeeInternalCompanyNumber` string — Optional internal company identification number of the employee to assign to this position
  - `externalCodeOperationUnit` string — Optional external code of the operation unit to associate with this position
  - `additionalParents` string[] — Optional list of external codes of additional parent positions (additional leaders) for this position. Maximum of 5 items allowed.

## Response `201`

Position successfully created

- object
  - `result` object, required — Result data
    - `uuid` string, uuid, required — Position UUID
    - `name` string, required — Position name
    - `externalCode` string, required — Position external code
    - `description` string, nullable — Position description
    - `role` PositionRoleOutput, required
      - `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
      - `externalCode` string, required — role external code
    - `employee` PositionEmployeeOutput
      - `uuid` string, required — employee UUID
      - `internalCompanyNumber` string, required — Internal company number (registration)
    - `area` PositionAreaOutput, required
      - `uuid` string, required — area UUID
      - `name` string, required — area name
      - `similarity` 'ADMINISTRATIVE' | 'FINANCIAL' | 'AGRONOMY' | 'ARCHITECTURE' | 'AUDITING' | 'QUALITY' | 'CUSTOMER_SERVICE' | 'COMMERCIAL' | 'PURCHASING' | 'COMMUNICATION' | 'DESIGN' | 'MARKETING' | 'ACCOUNTING' | 'CONTROLLING' | 'ENGINEERING' | 'MAINTENANCE' | 'TECHNICAL_SERVICES' | 'LEGAL' | 'INNOVATION' | 'PRODUCT' | 'LOGISTICS' | 'OPERATION' | 'PROJECTS' | 'PROCESSES' | 'HUMAN_RESOURCES' | 'SECURITY' | 'TECHNOLOGY', required — area similarity
      - `externalCode` string, required — area codigo externo
    - `costCenter` PositionCostCenterOutput
      - `uuid` string, uuid, required — cost center UUID
      - `name` string, required — cost center name
      - `externalCode` string, required — cost center external code
    - `operationUnit` PositionOperationUnitOutput
      - `uuid` string, uuid, required — operation unit UUID
      - `name` string, required — operation unit name
      - `externalCode` string, required — operation unit external code
    - `parent` ParentPositionOutput
      - `uuid` string, uuid, required — Position UUID
      - `name` string, required — Position name
      - `externalCode` string, required — Position external code
      - `employee` PositionEmployeeOutput
        - `uuid` string, required — employee UUID
        - `internalCompanyNumber` string, required — Internal company number (registration)
    - `additionalParents` ParentPositionOutput[] — Additional parent positions (additional leadership)
      - `uuid` string, uuid, required — Position UUID
      - `name` string, required — Position name
      - `externalCode` string, required — Position external code
      - `employee` PositionEmployeeOutput
        - `uuid` string, required — employee UUID
        - `internalCompanyNumber` string, required — Internal company number (registration)
    - `status` 'OPEN' | 'FILLED' | 'CLOSED' | 'FROZEN', required — Position status indicating current state (OPEN: available for assignment, FILLED: has assigned employee, CLOSED: no longer active, FROZEN: temporarily inactive)
  - `path` string, required — Request path
  - `duration` string, required — Request duration
  - `method` 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH', required — HTTP method used

## Other responses

- `400` — Bad Request - Invalid input data
- `401` — Unauthorized - Invalid or missing token
- `404` — Not Found - Referenced entity not found
- `409` — Conflict - Resource conflict
- `422` — Unprocessable Entity - Business rule validation failed
- `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)