---
title: "Update position by external code"
method: PUT
path: "/os/v1/positions/{externalCode}"
tags: ["Position", "Position"]
---

# Update position by external code

`PUT /os/v1/positions/{externalCode}`

Performs a full update (replacement) of a position. All fields in the request body will replace the current values.

**Business Rules:**

• Role (externalCodeRole) is required and must exist

• Area (externalCodeArea) is required and must exist

• Parent position is optional - can be null for root position

• Employee assignment is optional (can be null to unassign)

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

• Operation Unit (externalCodeOperationUnit) is optional (can be null to unassign)

• Set nullable fields to null to remove them

**Additional Leaders (additionalParents):**

• When provided, completely replaces existing additional leaders

• An empty array removes all additional leaders

• If not provided, existing additional leaders are preserved

• Maximum of 5 additional leaders allowed

• All additional leader positions must exist

• Cannot reference itself or main parent as additional leader

• No duplicate codes allowed in the list

## Path parameters

- `externalCode` string, required

## Request body

- UpdatePositionInput
  - `name` string, required — Human-readable name for the position
  - `description` string, nullable, required — Detailed description of the position. Set to null to remove description.
  - `externalCodeRole` string, required — External code of the role to associate with this position (required)
  - `externalCodeArea` string, required — External code of the area to associate with this position (required)
  - `externalCodeCostCenter` string, nullable, required — External code of the cost center to associate with this position. Set to null to remove cost center.
  - `externalCodeOperationUnit` string, nullable, required — External code of the operation unit to associate with this position. Set to null to remove operation unit.
  - `externalCodeParent` string, required — External code of the parent position in the organizational hierarchy (required)
  - `employeeEmail` string, email, nullable, required — Email address of the employee to assign to this position. Set to null to unassign employee.
  - `employeeTaxpayerRegistry` string, nullable, required — Tax payer registry (CPF) of the employee to assign to this position. Set to null to unassign employee. Must be a valid CPF format.
  - `employeeInternalCompanyNumber` string, nullable, required — Internal company identification number of the employee to assign to this position. Set to null to unassign employee.
  - `additionalParents` string[], nullable — Optional list of external codes of additional parent positions (additional leaders) for this position. When provided, this list will completely replace any existing additional leaders. An empty array or null will remove all additional leaders. Maximum of 5 items allowed.

## Response `200`

Position successfully updated

- 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)