Employees API — CRUD, Search, Filtering, and Bulk Import

The Employees API is the core people-management surface of La Oficina Nítida. Every employee record is scoped to the authenticated tenant; cross-tenant access is structurally impossible. The API supports full CRUD operations, free-text search across names and document numbers, filtering by EmpleadoEstado, and a dedicated bulk-import flow that accepts a pre-formatted .xlsx spreadsheet and returns a row-level import report. Soft-delete is used throughout — deleted employees are never purged and remain accessible in contract history. All endpoints require a valid JWT issued by the auth service.

Authorization: Bearer {accessToken}

Roles referenced below: ADMIN (full access), OPERADOR (read + write, no delete), and VIEWER (read-only).

List employees

page

number

Page number, minimum 1. Defaults to 1.

limit

number

Records per page, minimum 1. Defaults to 10.

string

Free-text search applied across first name, last names, and document number.

estado

string

Filter by employment status. One of ACTIVO, INACTIVO, SUSPENDIDO, RETIRADO.

data

Empleado[]

Array of employee objects matching the query.

meta.total

number

Total records across all pages.

meta.page

number

Current page number.

meta.limit

number

Page size used for this response.

meta.totalPages

number

Total number of pages.

GET /employees
Roles: ADMIN, OPERADOR, VIEWER

Create employee

POST /employees
Roles: ADMIN, OPERADOR

cedula

string

required

Document number (cédula). Must be unique within the tenant.

tipoDocumento

string

required

Document type. One of CC, CE, TI, PA, NIT, PEP, PPT.

primerNombre

string

required

Employee’s first given name.

primerApellido

string

required

Employee’s first family name.

segundoNombre

string

Employee’s second given name.

segundoApellido

string

Employee’s second family name.

string

Work email address. Must be a valid RFC 5321 address. An empty string is coerced to undefined.

telefono

string

Phone number.

cargo

string

required

Job title or position (e.g. "Analista de Datos").

salario

number

required

Base monthly salary. Must be ≥ 0. Coerced to a number if sent as a string.

tipoContrato

string

required

Contract type. One of TERMINO_FIJO, TERMINO_INDEFINIDO, OBRA_LABOR, APRENDIZAJE, PRESTACION_SERVICIOS.

fechaIngreso

string

required

Start date in ISO 8601 format (e.g. "2024-03-01").

estado

string

Initial employment status. One of ACTIVO, INACTIVO, SUSPENDIDO, RETIRADO. Defaults to ACTIVO.

municipioExpedicionDocId

string

DANE municipality code for the document’s issuing location.

salarioIntegral

boolean

Whether the salary is an integral salary (salario integral). Defaults to false. Accepts true/"true".

jornadaLaboral

string

Work schedule type. One of COMPLETA, MEDIA, POR_HORAS.

fechaRetiro

string

Separation date in ISO 8601 format. Required when estado is RETIRADO.

motivoRetiro

string

Reason for separation. One of RENUNCIA, TERMINACION_CONTRATO, MUTUO_ACUERDO, JUSTA_CAUSA, FALLECIMIENTO, OTRO.

sedeId

string (UUID)

UUID of the branch office (sede) to assign this employee to. Pass null to unassign.

string (UUID)

Newly created employee identifier.

createdAt

string (ISO 8601)

Timestamp of record creation.

tenantId

string (UUID)

Owning tenant identifier.

curl -X POST https://api.oficinaclear.com/employees \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cedula": "1012345678",
    "tipoDocumento": "CC",
    "primerNombre": "Laura",
    "primerApellido": "Gómez",
    "cargo": "Desarrolladora Backend",
    "salario": 5800000,
    "tipoContrato": "TERMINO_INDEFINIDO",
    "fechaIngreso": "2024-03-01",
    "email": "laura.gomez@empresa.co",
    "sedeId": "a3f2c1d0-1234-4abc-8def-000000000001"
  }'

Get employee

GET /employees/:id
Roles: ADMIN, OPERADOR, VIEWER

string (UUID)

required

Employee identifier.

string (UUID)

Employee identifier.

primerNombre

string

First given name.

primerApellido

string

First family name.

cedula

string

Document number.

tipoDocumento

string

Document type enum value.

cargo

string

Current job title.

salario

number

Current base salary.

estado

string

Employment status enum value.

sedeRef

object | null

Branch office object { id, nombre } if assigned, otherwise null.

Update employee

PATCH /employees/:id
Roles: ADMIN, OPERADOR

All body fields are optional. Supply only the fields you wish to change. The same field definitions as POST /employees apply; all are optional.

string (UUID)

required

Employee identifier.

cargo

string

Updated job title.

salario

number

Updated base salary (≥ 0).

estado

string

New employment status. One of ACTIVO, INACTIVO, SUSPENDIDO, RETIRADO.

sedeId

string (UUID) | null

Reassign or unassign from a branch office.

curl -X PATCH https://api.oficinaclear.com/employees/a1b2c3d4-0000-0000-0000-000000000001 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"estado": "RETIRADO", "motivoRetiro": "RENUNCIA", "fechaRetiro": "2024-12-31"}'

Delete employee

DELETE /employees/:id
Roles: ADMIN

Performs a soft delete by setting deletedAt. The employee record is never physically removed; all associated contract history, expediente documents, and payroll runs remain intact.

string (UUID)

required

Employee identifier.

string (UUID)

Identifier of the deleted employee.

deletedAt

string (ISO 8601)

Timestamp at which the soft delete was applied.

DELETE /employees/:id requires the ADMIN role. OPERADOR users receive a 403 Forbidden response.

Get employee expediente

GET /employees/:id/expediente
Roles: ADMIN, OPERADOR, VIEWER

Returns all ExpedienteDoc records belonging to this employee together with a category-level statistics summary.

string (UUID)

required

Employee identifier.

docs

ExpedienteDoc[]

Full list of document records, ordered by createdAt descending. Each record includes an inline generatedDocument object ({ id, nombre, tipo }) when the document originated from the document-generation pipeline.

stats.total

number

Total number of documents in this employee’s expediente.

stats.byCategory

object

Map of ExpedienteCategoria → count (e.g. { "CONTRATO": 3, "CERTIFICADO": 1 }).

stats.ultimoDocumento

string | null

ISO 8601 timestamp of the most recently added document, or null if the expediente is empty.

Download import template

GET /employees/import/template
Roles: ADMIN, OPERADOR

Returns a pre-formatted .xlsx file (plantilla_empleados.xlsx) with the correct column headers and an example row. Download this file, fill in your employee data, and upload it to POST /employees/import.

curl -OJ https://api.oficinaclear.com/employees/import/template \
  -H "Authorization: Bearer $TOKEN"

Bulk import employees

POST /employees/import
Roles: ADMIN
Content-Type: multipart/form-data

Uploads an .xlsx file (max 5 MB, up to 500 rows) and creates employee records for every valid row. Rows with validation errors are skipped and reported individually; the rest are committed.

file

required

The .xlsx spreadsheet. Only application/vnd.openxmlformats-officedocument.spreadsheetml.sheet MIME type is accepted. Sending any other format returns 400 Bad Request.

createdCount

number

Number of employees successfully created.

errorRows

object[]

Array of row-level error objects. Each entry contains the row index and a human-readable description of the validation failure.

curl -X POST https://api.oficinaclear.com/employees/import \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@plantilla_empleados.xlsx"

Authentication

People & Contracts

Operations

Employees API — CRUD, Search, Filtering, and Bulk Import

List employees

Create employee

Get employee

Update employee

Delete employee

Get employee expediente

Download import template

Bulk import employees

Build docs developers (and LLMs) love

Authentication

People & Contracts

Operations

Documentation Index

​List employees

​Create employee

​Get employee

​Update employee

​Delete employee

​Get employee expediente

​Download import template

​Bulk import employees

Build docs developers (and LLMs) love

List employees

Create employee

Get employee

Update employee

Delete employee

Get employee expediente

Download import template

Bulk import employees