Skip to main content
POST
/
v0
/
employee
Create Employee
curl --request POST \
  --url https://public-api.salu.com.vc/dev/routes/v0/employee/ \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "gov_id": "<string>",
  "is_disabled": true,
  "status": "Ativo",
  "sex": "M",
  "admission_date": "2023-12-25",
  "organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "branch_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "position_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sector_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "address": "<string>",
  "address_number": "<string>",
  "address_detail": "<string>",
  "zip_code": "<string>",
  "neighborhood": "<string>",
  "state": "<string>",
  "city": "<string>",
  "social_name": "<string>",
  "birth_date": "2023-12-25",
  "gender": "Cis",
  "mother_name": "<string>",
  "marital_status": "Não informado",
  "place_of_birth": "<string>",
  "educational_stage": "Indefinida",
  "human_skin_tone": "Indefinido",
  "phone": "<string>",
  "cell_phone": "<string>",
  "email": "<string>",
  "personal_email": "<string>",
  "hr_code": "<string>",
  "e_social": "<string>",
  "employee_registration_number": "<string>",
  "e_social_category": "<string>",
  "contract_type": "CLT",
  "work_shift": "<string>",
  "client_integration_code": "<string>",
  "create_exam": true,
  "send_email": false,
  "send_date": "2023-11-07T05:31:56Z"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "is_disabled": true,
  "status": "<string>",
  "sex": "<string>",
  "admission_date": "2023-12-25",
  "is_active": true,
  "organization": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>"
  },
  "branch": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>"
  },
  "position": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>"
  },
  "sector": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>"
  },
  "social_name": "<string>",
  "gov_id": "<string>",
  "birth_date": "2023-12-25",
  "gender": "<string>",
  "mother_name": "<string>",
  "marital_status": "<string>",
  "place_of_birth": "<string>",
  "educational_stage": "<string>",
  "human_skin_tone": "<string>",
  "phone": "<string>",
  "cell_phone": "<string>",
  "email": "<string>",
  "personal_email": "<string>",
  "dismissal_date": "2023-12-25",
  "hr_code": "<string>",
  "employee_registration_number": "<string>",
  "work_shift": "<string>",
  "client_integration_code": "<string>",
  "address": {
    "address": "<string>",
    "address_number": "<string>",
    "address_detail": "<string>",
    "zip_code": "<string>",
    "neighborhood": "<string>",
    "state": "<string>",
    "city": "<string>"
  }
}
Creates a new employee in your organization.
  • 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.
  • 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

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

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

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)
statusAtivoActive
InativoInactive
AfastadoOn leave
FériasVacation
PendentePending

​
sex

Field (request)Allowed values (API enum)Meaning (EN)
sexMMale
FFemale

​
gender

Field (request)Allowed values (API enum)Meaning (EN)
genderCisCisgender
TransTransgender

​
marital_status

Field (request)Allowed values (API enum)Meaning (EN)
marital_statusNão informadoNot informed
SolteiroSingle
CasadoMarried
SeparadoSeparated
DesquitadoLegally separated
ViúvoWidowed
OutrosOther
DivorciadoDivorced
União EstávelCommon-law union

​
educational_stage

Field (request)Allowed values (API enum)Meaning (EN)
educational_stageIndefinidaUndefined
Ensino Fundamental IncompletoIncomplete Elementary School
Ensino Fundamental CompletoComplete Elementary School
Ensino Medio IncompletoIncomplete High School
Ensino Medio CompletoComplete High School
Ensino Superior IncompletoIncomplete Undergraduate
Ensino Superior CompletoComplete Undergraduate
ProfissionalizanteVocational/Professional
Técnico IncompletoIncomplete Technical Course
Técnico CompletoComplete Technical Course
Tecnólogo IncompletoIncomplete Technologist Degree
Tecnólogo CompletoComplete Technologist Degree
Pós-graduação IncompletaIncomplete Postgraduate
Pós-graduação CompletoComplete Postgraduate
Mestrado IncompletoIncomplete Master’s
Mestrado CompletoComplete Master’s
Doutorado IncompletoIncomplete Doctorate
Doutorado CompletoComplete Doctorate
PHD IncompletoIncomplete PhD
PHD CompletoComplete PhD
Não InformadoNot informed
AnalfabetoIlliterate

​
human_skin_tone

Field (request)Allowed values (API enum)Meaning (EN)
human_skin_toneIndefinidoUndefined
BrancaWhite
PretaBlack
PardaBrown/mixed
AmarelaYellow
IndígenaIndigenous
MulatoMulatto

​
contract_type

Field (request)Allowed values (API enum)Meaning (EN)
contract_typeCLTCLT (Brazilian labor law employment)
COOPERADOCooperative member
TERCERIZADOOutsourced/third-party worker
AUTONOMOSelf-employed contractor
TEMPORARIOTemporary
PESSOA_JURIDICALegal entity (company contractor)
ESTAGIARIOIntern
MENOR_APRENDIZYoung apprentice
ESTATUTARIOStatutory public servant
COMISSIONADO_INTERNOInternal commissioned
COMISSIONADO_EXTERNOExternal commissioned
APOSENTADORetired
APOSENTADO_INATIVO_PREFEITURARetired inactive (municipality)
PENSIONISTAPensioner
SERVIDOR_PUBLICO_EFETIVOTenured public servant
EXTRANUMERARIOSupernumerary employee
AUTARQUICOAutarchic public servant
INATIVOInactive
TITULO_PRECARIOProvisional title (precarious)
SERVIDOR_ADM_CENTRALIZADA_OU_DESCENTRALIZADACentralized/Decentralized administration public servant

​
Example request

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

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
name
string
required
​
gov_id
string
required
​
is_disabled
boolean
required
​
status
enum<string>
required
Available options:
Ativo,
Inativo,
Afastado,
Férias,
Pendente
​
sex
enum<string>
required
Available options:
M,
F
​
admission_date
string<date>
required
​
organization_id
string<uuid>
required
​
branch_id
string<uuid>
required
​
position_id
string<uuid>
required
​
sector_id
string<uuid>
required
​
address
string | null
​
address_number
string | null
​
address_detail
string | null
​
zip_code
string | null
​
neighborhood
string | null
​
state
string | null
​
city
string | null
​
social_name
string | null
​
birth_date
string<date> | null
​
gender
enum<string> | null
Available options:
Cis,
Trans
​
mother_name
string | null
​
marital_status
enum<string> | null
Available options:
Não informado,
Solteiro,
Casado,
Separado,
Desquitado,
Viúvo,
Outros,
Divorciado,
União Estável
​
place_of_birth
string | null
​
educational_stage
enum<string> | null
Available options:
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
​
human_skin_tone
enum<string> | null
Available options:
Indefinido,
Branca,
Preta,
Parda,
Amarela,
Indígena,
Mulato
​
phone
string | null
​
cell_phone
string | null
​
email
string | null
​
personal_email
string | null
​
hr_code
string | null
​
e_social
string | null
​
employee_registration_number
string | null
​
e_social_category
string | null
​
contract_type
enum<string> | null
Available options:
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
​
work_shift
string | null
​
client_integration_code
string | null
​
create_exam
boolean
default:true
​
send_email
boolean | null
default:false
​
send_date
string<date-time> | null

Response

Successful Response

​
id
string<uuid>
required
​
name
string
required
​
is_disabled
boolean
required
​
status
string
required
​
sex
string
required
​
admission_date
string<date>
required
​
is_active
boolean
required
​
organization
SimpleEntity · object
required
​
branch
SimpleEntity · object
required
​
position
SimpleEntity · object
required
​
sector
SimpleEntity · object
required
​
social_name
string | null
​
gov_id
string | null
​
birth_date
string<date> | null
​
gender
string | null
​
mother_name
string | null
​
marital_status
string | null
​
place_of_birth
string | null
​
educational_stage
string | null
​
human_skin_tone
string | null
​
phone
string | null
​
cell_phone
string | null
​
email
string | null
​
personal_email
string | null
​
dismissal_date
string<date> | null
​
hr_code
string | null
​
employee_registration_number
string | null
​
work_shift
string | null
​
client_integration_code
string | null
​
address
Address · object