API Reference

Create a new Position

post
https://api.gupy.io/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

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Position creation data with required fields: externalCode, name, externalCodeRole, externalCodeArea. Optional fields include: externalCodeOperationUnit, externalCodeCostCenter, externalCodeParent, and employee identification fields.

string
length ≤ 50

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

string
required
length ≤ 255

Human-readable name for the position

string
required
length ≤ 50

External code of the role to associate with this position

string
required
length ≤ 50

External code of the area to associate with this position

string | null

Optional detailed description of the position responsibilities and requirements

string
length ≤ 50

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

string
length ≤ 50

Optional external code of the parent position in the organizational hierarchy

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.

string

Optional email address of the employee to assign to this position

string

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

string

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

string
length ≤ 50

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

additionalParents
array of strings
length ≤ 5
Defaults to []

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

additionalParents
Responses

Updated 2 months ago

Did this page help you?
Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 2 months ago

Did this page help you?