> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salu.com.vc/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Employee
Creates a new employee in your organization.
Business rules
* create\_exam (boolean): when true, a pre-employment (hiring) medical exam will be created for the employee right after creation.
* send\_email (boolean): when true, the employee will receive an email notification about the exam.
* send\_date (date-time, optional): the date/time when the notification should be sent. If send\_email=true and send\_date is empty or null, the current date/time will be used to trigger the notification.
Date format
* Field: send\_date
* Accepted format: ISO 8601 (UTC when applicable)
* Valid examples:
* 2025-01-31T00:00:00Z
* 2025-01-31 00:00:00
## Overview
### Fields
| Field | Description |
| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gov_id` (CPF) | **Person / Employee identifier**
In Brazil, every individual has a CPF (Cadastro de Pessoa Física), which is the national taxpayer ID for a person. It’s unique per person and typically does not change. In our API we expose it as `gov_id`. In practice, it plays a role similar to SSN (US) or a national personal tax ID in other countries.
**Key point:** `gov_id` identifies the human being, not the employment relationship. |
| `hr_code` | **“Matrícula RH” (internal company HR ID) — optional**
`hr_code` corresponds to Matrícula RH, which is an internal employee code created by the company for HR/payroll/admin systems. Optional (not required by law). Used for internal controls and integrations with the company’s HRIS/payroll tools. Can vary by company and can change if the company migrates systems. Think of it as a typical Employee ID inside an organization. |
| `employee_registration_number` | **“Matrícula eSocial” (government employment link ID) — required (when applicable)**
`employee_registration_number` corresponds to Matrícula eSocial, which is an official identifier tied to the formal employment relationship under Brazilian labor law (CLT). Mandatory by law for formal employment reporting (eSocial). It is unique per employment relationship (per “job link”), not necessarily per person for life. It may not be available at onboarding, because it’s usually assigned/confirmed only after payroll/accounting formally registers the employee, including the CTPS registration.
**Important nuance:** A person (`gov_id`) can exist in the system before the Matrícula eSocial is known. Once the employment is formalized, `employee_registration_number` becomes the official “government-side” reference for that employment link. |
* **Method:** `POST`
* **Path:** `/v0/employee/`
* **OperationId:** `public_create_employee_v0_employee__post`
* **Authentication:** header `x-api-key` (`APIKeyHeader` in OpenAPI)
### Examples focused on `create_exam` and `send_email`
#### 1) Create exam and send email immediately (no send\_date)
```bash theme={null}
curl -X POST "https://public-api.salu.com.vc/dev/routes/v0/employee/" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "x-api-key: $SALU_PUBLIC_API_KEY" \
--data '{
"name": "Jane Doe",
"gov_id": "12345678900",
"is_disabled": false,
"status": "Ativo",
"sex": "F",
"admission_date": "2025-01-31",
"organization_id": "00000000-0000-0000-0000-000000000001",
"branch_id": "00000000-0000-0000-0000-000000000002",
"position_id": "00000000-0000-0000-0000-000000000003",
"sector_id": "00000000-0000-0000-0000-000000000004",
"create_exam": true,
"send_email": true,
"send_date": null
}'
```
In this scenario, a hiring exam will be created and the email will be sent now (current date/time), because send\_email=true and send\_date was not provided.
#### 2) Schedule the email for a specific date/time
```bash theme={null}
curl -X POST "https://public-api.salu.com.vc/dev/routes/v0/employee/" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "x-api-key: $SALU_PUBLIC_API_KEY" \
--data '{
"name": "Jane Doe",
"gov_id": "12345678900",
"is_disabled": false,
"status": "Ativo",
"sex": "F",
"admission_date": "2025-01-31",
"organization_id": "00000000-0000-0000-0000-000000000001",
"branch_id": "00000000-0000-0000-0000-000000000002",
"position_id": "00000000-0000-0000-0000-000000000003",
"sector_id": "00000000-0000-0000-0000-000000000004",
"create_exam": true,
"send_email": true,
"send_date": "2025-02-01T09:30:00Z"
}'
```
Here, the hiring exam will be created and the email will be sent on the send\_date provided (ISO 8601).
### Enum fields and translations
Use exactly the enum values as defined by the API (Portuguese strings). Do not send the English translations below — they are provided only to clarify the meaning.
#### status
| Field (request) | Allowed values (API enum) | Meaning (EN) |
| --------------- | ------------------------- | ------------ |
| `status` | `Ativo` | Active |
| | `Inativo` | Inactive |
| | `Afastado` | On leave |
| | `Férias` | Vacation |
| | `Pendente` | Pending |
#### sex
| Field (request) | Allowed values (API enum) | Meaning (EN) |
| --------------- | ------------------------- | ------------ |
| `sex` | `M` | Male |
| | `F` | Female |
#### gender
| Field (request) | Allowed values (API enum) | Meaning (EN) |
| --------------- | ------------------------- | ------------ |
| `gender` | `Cis` | Cisgender |
| | `Trans` | Transgender |
#### marital\_status
| Field (request) | Allowed values (API enum) | Meaning (EN) |
| ---------------- | ------------------------- | ----------------- |
| `marital_status` | `Não informado` | Not informed |
| | `Solteiro` | Single |
| | `Casado` | Married |
| | `Separado` | Separated |
| | `Desquitado` | Legally separated |
| | `Viúvo` | Widowed |
| | `Outros` | Other |
| | `Divorciado` | Divorced |
| | `União Estável` | Common-law union |
#### educational\_stage
| Field (request) | Allowed values (API enum) | Meaning (EN) |
| ------------------- | ------------------------------- | ------------------------------ |
| `educational_stage` | `Indefinida` | Undefined |
| | `Ensino Fundamental Incompleto` | Incomplete Elementary School |
| | `Ensino Fundamental Completo` | Complete Elementary School |
| | `Ensino Medio Incompleto` | Incomplete High School |
| | `Ensino Medio Completo` | Complete High School |
| | `Ensino Superior Incompleto` | Incomplete Undergraduate |
| | `Ensino Superior Completo` | Complete Undergraduate |
| | `Profissionalizante` | Vocational/Professional |
| | `Técnico Incompleto` | Incomplete Technical Course |
| | `Técnico Completo` | Complete Technical Course |
| | `Tecnólogo Incompleto` | Incomplete Technologist Degree |
| | `Tecnólogo Completo` | Complete Technologist Degree |
| | `Pós-graduação Incompleta` | Incomplete Postgraduate |
| | `Pós-graduação Completo` | Complete Postgraduate |
| | `Mestrado Incompleto` | Incomplete Master's |
| | `Mestrado Completo` | Complete Master's |
| | `Doutorado Incompleto` | Incomplete Doctorate |
| | `Doutorado Completo` | Complete Doctorate |
| | `PHD Incompleto` | Incomplete PhD |
| | `PHD Completo` | Complete PhD |
| | `Não Informado` | Not informed |
| | `Analfabeto` | Illiterate |
#### human\_skin\_tone
| Field (request) | Allowed values (API enum) | Meaning (EN) |
| ----------------- | ------------------------- | ------------ |
| `human_skin_tone` | `Indefinido` | Undefined |
| | `Branca` | White |
| | `Preta` | Black |
| | `Parda` | Brown/mixed |
| | `Amarela` | Yellow |
| | `Indígena` | Indigenous |
| | `Mulato` | Mulatto |
#### contract\_type
| Field (request) | Allowed values (API enum) | Meaning (EN) |
| --------------- | ---------------------------------------------- | ------------------------------------------------------- |
| `contract_type` | `CLT` | CLT (Brazilian labor law employment) |
| | `COOPERADO` | Cooperative member |
| | `TERCERIZADO` | Outsourced/third-party worker |
| | `AUTONOMO` | Self-employed contractor |
| | `TEMPORARIO` | Temporary |
| | `PESSOA_JURIDICA` | Legal entity (company contractor) |
| | `ESTAGIARIO` | Intern |
| | `MENOR_APRENDIZ` | Young apprentice |
| | `ESTATUTARIO` | Statutory public servant |
| | `COMISSIONADO_INTERNO` | Internal commissioned |
| | `COMISSIONADO_EXTERNO` | External commissioned |
| | `APOSENTADO` | Retired |
| | `APOSENTADO_INATIVO_PREFEITURA` | Retired inactive (municipality) |
| | `PENSIONISTA` | Pensioner |
| | `SERVIDOR_PUBLICO_EFETIVO` | Tenured public servant |
| | `EXTRANUMERARIO` | Supernumerary employee |
| | `AUTARQUICO` | Autarchic public servant |
| | `INATIVO` | Inactive |
| | `TITULO_PRECARIO` | Provisional title (precarious) |
| | `SERVIDOR_ADM_CENTRALIZADA_OU_DESCENTRALIZADA` | Centralized/Decentralized administration public servant |
### Example request
```bash theme={null}
curl -X POST "https://public-api.salu.com.vc/dev/routes/v0/employee/" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "x-api-key: $SALU_PUBLIC_API_KEY" \
--data '{
"employee_name": "Jane Doe",
"employee_registration_number": "12345",
"employee_is_disabled": false
}'
```
## OpenAPI
````yaml POST /v0/employee/
openapi: 3.1.0
info:
title: Public API v0
description: API publica da Salu para integracoes de SST.
version: 0.1.0
servers:
- url: https://public-api.salu.com.vc/dev/routes
description: Development
- url: https://public-api.salu.com.vc/prd/routes
description: Production
security: []
paths:
/v0/employee/:
post:
tags:
- Employee
- Employee
summary: Public Create Employee
operationId: public_create_employee_v0_employee__post
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiCreateEmployeeRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiCreateEmployeeResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
components:
schemas:
PublicApiCreateEmployeeRequest:
properties:
address:
anyOf:
- type: string
- type: 'null'
title: Address
address_number:
anyOf:
- type: string
- type: 'null'
title: Address Number
address_detail:
anyOf:
- type: string
- type: 'null'
title: Address Detail
zip_code:
anyOf:
- type: string
- type: 'null'
title: Zip Code
neighborhood:
anyOf:
- type: string
- type: 'null'
title: Neighborhood
state:
anyOf:
- type: string
- type: 'null'
title: State
city:
anyOf:
- type: string
- type: 'null'
title: City
name:
type: string
title: Name
social_name:
anyOf:
- type: string
- type: 'null'
title: Social Name
gov_id:
type: string
title: Gov Id
birth_date:
anyOf:
- type: string
format: date
- type: 'null'
title: Birth Date
is_disabled:
type: boolean
title: Is Disabled
status:
$ref: '#/components/schemas/PublicApiStatusEnum'
sex:
$ref: '#/components/schemas/PublicApiSexEnum'
gender:
anyOf:
- $ref: '#/components/schemas/PublicApiGenderIdentityEnum'
- type: 'null'
mother_name:
anyOf:
- type: string
- type: 'null'
title: Mother Name
marital_status:
anyOf:
- $ref: '#/components/schemas/PublicApiMaritalStatusEnum'
- type: 'null'
place_of_birth:
anyOf:
- type: string
- type: 'null'
title: Place Of Birth
educational_stage:
anyOf:
- $ref: '#/components/schemas/PublicApiEducationalStageEnum'
- type: 'null'
human_skin_tone:
anyOf:
- $ref: '#/components/schemas/PublicApiHumanSkinToneEnum'
- type: 'null'
phone:
anyOf:
- type: string
- type: 'null'
title: Phone
cell_phone:
anyOf:
- type: string
- type: 'null'
title: Cell Phone
email:
anyOf:
- type: string
- type: 'null'
title: Email
personal_email:
anyOf:
- type: string
- type: 'null'
title: Personal Email
admission_date:
type: string
format: date
title: Admission Date
hr_code:
anyOf:
- type: string
- type: 'null'
title: Hr Code
e_social:
anyOf:
- type: string
- type: 'null'
title: E Social
employee_registration_number:
anyOf:
- type: string
- type: 'null'
title: Employee Registration Number
e_social_category:
anyOf:
- type: string
- type: 'null'
title: E Social Category
contract_type:
anyOf:
- $ref: '#/components/schemas/EmployeeContractTypeEnum'
- type: 'null'
work_shift:
anyOf:
- type: string
- type: 'null'
title: Work Shift
organization_id:
type: string
format: uuid
title: Organization Id
branch_id:
type: string
format: uuid
title: Branch Id
position_id:
type: string
format: uuid
title: Position Id
sector_id:
type: string
format: uuid
title: Sector Id
client_integration_code:
anyOf:
- type: string
- type: 'null'
title: Client Integration Code
create_exam:
type: boolean
title: Create Exam
default: true
send_email:
anyOf:
- type: boolean
- type: 'null'
title: Send Email
default: false
send_date:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Send Date
disability_analysis_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: ID da Análise PCD
description: >-
ID da análise PCD aprovada vinculada ao colaborador. Obrigatório
quando is_disabled=true e o customer exige pré-análise.
type: object
required:
- name
- gov_id
- is_disabled
- status
- sex
- admission_date
- organization_id
- branch_id
- position_id
- sector_id
title: PublicApiCreateEmployeeRequest
PublicApiCreateEmployeeResponse:
properties:
id:
type: string
format: uuid
title: Id
name:
type: string
title: Name
social_name:
anyOf:
- type: string
- type: 'null'
title: Social Name
gov_id:
anyOf:
- type: string
- type: 'null'
title: Gov Id
birth_date:
anyOf:
- type: string
format: date
- type: 'null'
title: Birth Date
is_disabled:
type: boolean
title: Is Disabled
status:
type: string
title: Status
sex:
type: string
title: Sex
gender:
anyOf:
- type: string
- type: 'null'
title: Gender
mother_name:
anyOf:
- type: string
- type: 'null'
title: Mother Name
marital_status:
anyOf:
- type: string
- type: 'null'
title: Marital Status
place_of_birth:
anyOf:
- type: string
- type: 'null'
title: Place Of Birth
educational_stage:
anyOf:
- type: string
- type: 'null'
title: Educational Stage
human_skin_tone:
anyOf:
- type: string
- type: 'null'
title: Human Skin Tone
phone:
anyOf:
- type: string
- type: 'null'
title: Phone
cell_phone:
anyOf:
- type: string
- type: 'null'
title: Cell Phone
email:
anyOf:
- type: string
- type: 'null'
title: Email
personal_email:
anyOf:
- type: string
- type: 'null'
title: Personal Email
admission_date:
type: string
format: date
title: Admission Date
dismissal_date:
anyOf:
- type: string
format: date
- type: 'null'
title: Dismissal Date
hr_code:
anyOf:
- type: string
- type: 'null'
title: Hr Code
employee_registration_number:
anyOf:
- type: string
- type: 'null'
title: Employee Registration Number
work_shift:
anyOf:
- type: string
- type: 'null'
title: Work Shift
is_active:
type: boolean
title: Is Active
client_integration_code:
anyOf:
- type: string
- type: 'null'
title: Client Integration Code
organization:
$ref: '#/components/schemas/SimpleEntity'
branch:
$ref: '#/components/schemas/SimpleEntity'
position:
$ref: '#/components/schemas/SimpleEntity'
sector:
$ref: '#/components/schemas/SimpleEntity'
address:
anyOf:
- $ref: '#/components/schemas/Address'
- type: 'null'
type: object
required:
- id
- name
- is_disabled
- status
- sex
- admission_date
- is_active
- organization
- branch
- position
- sector
title: PublicApiCreateEmployeeResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
PublicApiStatusEnum:
type: string
enum:
- Ativo
- Inativo
- Afastado
- Férias
- Pendente
title: PublicApiStatusEnum
PublicApiSexEnum:
type: string
enum:
- M
- F
title: PublicApiSexEnum
PublicApiGenderIdentityEnum:
type: string
enum:
- Cis
- Trans
title: PublicApiGenderIdentityEnum
PublicApiMaritalStatusEnum:
type: string
enum:
- Não informado
- Solteiro
- Casado
- Separado
- Desquitado
- Viúvo
- Outros
- Divorciado
- União Estável
title: PublicApiMaritalStatusEnum
PublicApiEducationalStageEnum:
type: string
enum:
- Indefinida
- Ensino Fundamental Incompleto
- Ensino Fundamental Completo
- Ensino Medio Incompleto
- Ensino Medio Completo
- Ensino Superior Incompleto
- Ensino Superior Completo
- Profissionalizante
- Técnico Incompleto
- Técnico Completo
- Tecnólogo Incompleto
- Tecnólogo Completo
- Pós-graduação Incompleta
- Pós-graduação Completo
- Mestrado Incompleto
- Mestrado Completo
- Doutorado Incompleto
- Doutorado Completo
- PHD Incompleto
- PHD Completo
- Não Informado
- Analfabeto
title: PublicApiEducationalStageEnum
PublicApiHumanSkinToneEnum:
type: string
enum:
- Indefinido
- Branca
- Preta
- Parda
- Amarela
- Indígena
- Mulato
title: PublicApiHumanSkinToneEnum
EmployeeContractTypeEnum:
type: string
enum:
- CLT
- COOPERADO
- TERCERIZADO
- AUTONOMO
- TEMPORARIO
- PESSOA_JURIDICA
- ESTAGIARIO
- MENOR_APRENDIZ
- ESTATUTARIO
- COMISSIONADO_INTERNO
- COMISSIONADO_EXTERNO
- APOSENTADO
- APOSENTADO_INATIVO_PREFEITURA
- PENSIONISTA
- SERVIDOR_PUBLICO_EFETIVO
- EXTRANUMERARIO
- AUTARQUICO
- INATIVO
- TITULO_PRECARIO
- SERVIDOR_ADM_CENTRALIZADA_OU_DESCENTRALIZADA
title: EmployeeContractTypeEnum
SimpleEntity:
properties:
id:
type: string
format: uuid
title: Id
name:
type: string
title: Name
type: object
required:
- id
- name
title: SimpleEntity
Address:
properties:
address:
anyOf:
- type: string
- type: 'null'
title: Address
address_number:
anyOf:
- type: string
- type: 'null'
title: Address Number
address_detail:
anyOf:
- type: string
- type: 'null'
title: Address Detail
zip_code:
anyOf:
- type: string
- type: 'null'
title: Zip Code
neighborhood:
anyOf:
- type: string
- type: 'null'
title: Neighborhood
state:
anyOf:
- type: string
- type: 'null'
title: State
city:
anyOf:
- type: string
- type: 'null'
title: City
type: object
title: Address
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: x-api-key
````