Sign in

v1

latestOpenAPI 3.0.02026-07-24161168406.5 KB
Position
Position

Create a new Position

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

post/os/v1/positions

Request body

externalCodestring

Unique external code to identify the position within the company. If not provided, it will be auto-generated.

namestring required

Human-readable name for the position

externalCodeRolestring required

External code of the role to associate with this position

externalCodeAreastring required

External code of the area to associate with this position

descriptionstring nullable

Optional detailed description of the position responsibilities and requirements

externalCodeCostCenterstring

Optional external code of the cost center to associate with this position

externalCodeParentstring

Optional external code of the parent position in the organizational hierarchy

parentIdentifierstring

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.

employeeEmailstring email

Optional email address of the employee to assign to this position

employeeTaxPayerRegistrystring

Optional tax payer registry (CPF) of the employee to assign to this position. Must be a valid CPF format.

employeeInternalCompanyNumberstring

Optional internal company identification number of the employee to assign to this position

externalCodeOperationUnitstring

Optional external code of the operation unit to associate with this position

additionalParentsstring[]

Optional list of external codes of additional parent positions (additional leaders) for this position. Maximum of 5 items allowed.

Example request

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

Response

Position successfully created

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"
  }
}