Sign in

v1

latestOpenAPI 3.0.02026-07-24161168406.5 KB
Position
Position

Update position by external code

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

put/os/v1/positions/{externalCode}

Path parameters

externalCodestring required

The external code of the position to be updated

Request body

namestring required

Human-readable name for the position

descriptionstring nullable required

Detailed description of the position. Set to null to remove description.

externalCodeRolestring required

External code of the role to associate with this position (required)

externalCodeAreastring required

External code of the area to associate with this position (required)

externalCodeCostCenterstring nullable required

External code of the cost center to associate with this position. Set to null to remove cost center.

externalCodeOperationUnitstring nullable required

External code of the operation unit to associate with this position. Set to null to remove operation unit.

externalCodeParentstring required

External code of the parent position in the organizational hierarchy (required)

employeeEmailstring email nullable required

Email address of the employee to assign to this position. Set to null to unassign employee.

employeeTaxpayerRegistrystring 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.

employeeInternalCompanyNumberstring nullable required

Internal company identification number of the employee to assign to this position. Set to null to unassign employee.

additionalParentsstring[] 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.

Example request

{
  "name": "Senior Software Engineer",
  "description": "Senior software engineer responsible for backend development and architecture decisions",
  "externalCodeRole": "SE_ROLE",
  "externalCodeArea": "TECH_AREA",
  "externalCodeCostCenter": "CC_TECH",
  "externalCodeOperationUnit": "OU_TECH",
  "externalCodeParent": "TECH_LEAD",
  "employeeEmail": "john.doe@company.com",
  "employeeTaxpayerRegistry": "123.456.789-00",
  "employeeInternalCompanyNumber": "EMP001",
  "additionalParents": [
    "LEADER_01",
    "LEADER_02"
  ]
}

Response

Position successfully updated

pathstring required

Request path

durationstring required

Request duration

method'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' required

HTTP method used

Example response

{
  "result": {
    "uuid": "cc2339c3-bf5a-406b-bafa-3bf8c0acbf23",
    "name": "Software Engineer",
    "externalCode": "SE123",
    "description": "Posição de desenvolvedor time ABC",
    "role": {
      "name": "Desenvolvedor",
      "similarity": "CONSULTANT",
      "externalCode": "RR-001"
    },
    "employee": {
      "uuid": "d20dc017-80c6-4706-bbfe-549c1cc4d2c1",
      "internalCompanyNumber": "132AT41"
    },
    "area": {
      "uuid": "cab41475-caa7-47a7-9b28-eecae80c1ae3",
      "name": "Produto",
      "similarity": "ACCOUNTING",
      "externalCode": "AA-001"
    },
    "costCenter": {
      "name": "CC-001",
      "externalCode": "CC-001"
    },
    "operationUnit": {
      "name": "Operation Unit 1",
      "externalCode": "OU-001"
    },
    "parent": {
      "uuid": "0372fc1b-35e0-42c5-bbe7-98dc7c218da1",
      "name": "Software Engineer",
      "externalCode": "SE123",
      "employee": {
        "uuid": "d20dc017-80c6-4706-bbfe-549c1cc4d2c1",
        "internalCompanyNumber": "132AT41"
      }
    },
    "additionalParents": [
      {
        "uuid": "0372fc1b-35e0-42c5-bbe7-98dc7c218da1",
        "name": "Software Engineer",
        "externalCode": "SE123",
        "employee": {
          "uuid": "d20dc017-80c6-4706-bbfe-549c1cc4d2c1",
          "internalCompanyNumber": "132AT41"
        }
      }
    ],
    "status": "OPEN"
  }
}