---
title: "Replace position by employee identifier (CPF or Email)"
method: PUT
path: "/os/v1/positions/update-by-employee/{identifier}"
tags: ["Position", "Position"]
---

# Replace position by employee identifier (CPF or Email)

`PUT /os/v1/positions/update-by-employee/{identifier}`

Finds a position by the current occupant's CPF or email, then performs a COMPLETE replacement of that position. The identifier parameter automatically detects if the value is an email (contains @) or a CPF.

**Parent Position (Leader):**

• For ROOT positions: omit all three parent fields (externalCodeParent, parentEmail, parentTaxpayerRegistry)

• For NON-ROOT positions: you MUST provide ONE of:
  - `externalCodeParent`: External code of the parent position
  - `parentEmail`: Email of the leader (will find their active position)
  - `parentTaxpayerRegistry`: CPF of the leader (will find their active position)

**This is a PUT operation - all required fields must be provided.**

**Examples:**

• identifier: "maria@gupy.com.br" (email)

• identifier: "13306708792" (CPF)

• externalCodeParent: "POS-123" (traditional way)

• parentEmail: "leader@cliente.com" (sets the position leader by email)

• parentTaxpayerRegistry: "987.654.321-00" (sets the position leader by CPF)

**Business Rules:**

• The identifier (CPF or email) must match an existing employee

• The employee must have an active position

• For non-root positions, ONE parent identifier must be provided (externalCodeParent OR parentEmail OR parentTaxpayerRegistry)

• If `parentEmail`/`parentTaxpayerRegistry` is provided, the leader must exist and have an active position

• All required fields (name, externalCodeRole, externalCodeArea) must be provided

• This operation replaces all position data

• Set nullable fields to null to remove them

• Role and Area must exist

• New employee can only be assigned to one position at a time

• When `additionalParents` is provided, it completely replaces any existing additional leaders

• An empty array for `additionalParents` removes all additional leaders

• When `additionalParents` is not provided (undefined), existing additional leaders remain unchanged

• Maximum of 5 additional parents allowed

• Additional parents cannot include the position itself (self-reference)

• Additional parents cannot include the direct parent position

• All additional parent positions must exist

**Use Cases:**

• Complete position replacement

• Update all position fields at once including the leader

• Change the occupant with full position update

• Make a position vacant by setting employeeEmail to null

• Create or update root positions by omitting parent fields

## Path parameters

- `identifier` string, required

## Request body

- UpdatePositionByEmployeeInput
  - `name` string, required — Human-readable name for the position
  - `externalCode` string — External code identifier for the position. If not provided, keeps the current externalCode.
  - `description` string, nullable — Detailed description of the position. Set to null to remove description.
  - `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
  - `externalCodeParent` string — External code of the parent position in the organizational hierarchy. Required for non-root positions. Use this OR parentEmail OR parentTaxpayerRegistry (only one is needed). Omit all three to create a root position.
  - `externalCodeCostCenter` string, nullable — External code of the cost center to associate with this position. Set to null to remove cost center.
  - `externalCodeOperationUnit` string, nullable — External code of the operation unit to associate with this position. Set to null to remove operation unit.
  - `parentEmail` string, email — Email da nova líder (alternativo ao externalCodeParent). Required for non-root positions if externalCodeParent and parentTaxpayerRegistry are not provided. Será usado para localizar a posição ativa da líder.
  - `parentTaxpayerRegistry` string — CPF da nova líder (alternativo ao externalCodeParent). Required for non-root positions if externalCodeParent and parentEmail are not provided. Será usado para localizar a posição ativa da líder.
  - `employeeEmail` string, email, nullable — Email address of the new employee to assign to this position. Set to null to unassign employee.
  - `employeeTaxpayerRegistry` string, nullable — Tax payer registry (CPF) of the new employee to assign to this position. Set to null to unassign employee. Must be a valid CPF format.
  - `employeeInternalCompanyNumber` string, nullable — Internal company identification number of the new 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. If not provided (undefined), existing additional leaders will be kept unchanged. Maximum of 5 items allowed.

## Response `200`

Position successfully replaced

- object
  - `result` object, required — Result data
  - `path` string, required — Request path
  - `duration` string, required — Request duration
  - `method` 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH', required — HTTP method used
  - `data` PositionOutput
    - `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)

## Other responses

- `400` — Bad Request - Invalid input data
- `404` — Not Found - Referenced entity not found
- `409` — Conflict - Resource conflict
- `422` — Unprocessable Entity - Business rule validation failed

---

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