Employees

Operation	Permission
Query employees and job titles	`hr.employees`
Create and update employees	`hr.employees.write`

This permission exposes personal data and salaries. Protect the API Key and limit access to trusted systems.

List employees

GET /hr/employees

Parameter	Type	Description
`is_active`	boolean	Filters active (`1`) or inactive (`0`). Without the parameter it returns both.
`search`	string	Searches by first name, last name or email.
`document_number`	string	Filters by exact document number.
`per_page`	integer	Results per page (1–200, default 50).
`page`	integer	Page.

{
  "status": true,
  "data": {
    "data": [
      {
        "id": "uuid",
        "first_name": "María",
        "last_name": "López",
        "document_type": "DUI",
        "document_number": "01234567-8",
        "tax_number": "0614-010190-101-1",
        "email": "maria@empresa.com",
        "phone": "7000-0000",
        "type": "permanent",
        "job_title": "Contadora",
        "hire_date": "2024-02-01",
        "salary": 850.00,
        "employment_relationship": "labor",
        "pay_type": "salaried",
        "hourly_rate": null,
        "is_active": true
      }
    ],
    "pagination": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 }
  }
}

Field	Description
`type`	Contract type: `permanent`, `temporary` or `project_based`.
`salary`	Monthly salary.
`hire_date`	Hire date.
`employment_relationship`	Relationship: `labor` (employment) or `services` (professional services).
`pay_type`	Pay type: `salaried` (monthly salary), `hourly` (per hour) or `fee` (fees).
`hourly_rate`	Hourly rate, or `null`.

Get employee

GET /hr/employees/{id}

Returns the same employee object. Deleted employees respond 404.

Job titles

GET /hr/job-titles

Returns the job title catalog (id, name, description, parent_id) so you can get the job_title_id. Requires hr.employees.

Create employee

POST /hr/employees

Required permission: hr.employees.write

{
  "first_name": "María",
  "last_name": "López",
  "document_type": "DUI",
  "document_number": "01234567-8",
  "tax_number": "0614-010190-101-1",
  "email": "maria@empresa.com",
  "phone": "7000-0000",
  "type": "permanent",
  "job_title_id": "uuid",
  "manager_id": "uuid",
  "hire_date": "2026-10-01",
  "salary": 850.00,
  "bank_name": "Banco Agrícola",
  "bank_account_type": "Ahorro",
  "bank_account_number": "3000123456"
}

Field	Required	Description
`first_name`, `last_name`	Yes	First and last names.
`type`	Yes	`permanent`, `temporary` or `project_based`.
`hire_date`	Yes	Hire date (`YYYY-MM-DD`). Used for seniority, Christmas bonus (aguinaldo), vacation and final settlement (finiquito).
`salary`	Yes	Monthly salary.
`document_type`, `document_number`	No	Identity document. The number must be unique in the business: it is used to identify clock-ins and leave requests.
`tax_number`	No	NIT.
`email`, `phone`, `address`	No	Contact.
`birth_date`	No	Date of birth.
`job_title_id`	No	Job title (`GET /hr/job-titles`).
`manager_id`	No	Direct manager (ID of another employee).
`emergency_contact_name`, `emergency_contact_phone`	No	Emergency contact.
`bank_name`, `bank_account_type`, `bank_account_number`	No	Account for payroll payment.
`employment_relationship`	No	`labor` (default) or `services`. With `services`, legal surcharges are not applied to hours.
`pay_type`	No	`salaried` (default), `hourly` or `fee`. Defines how hours are valued in the attendance results.
`hourly_rate`	Conditional	Hourly rate (≥ 0). Required if `pay_type` is `hourly`.
`is_active`	No	Defaults to `true`.

201 response: the created employee (same format as the query).

Code	Cause
`409`	An employee with that document number already exists. The response includes their `employee_id`.
`422`	Validation: required fields, job title or manager not found in the business, or `pay_type: hourly` without `hourly_rate`.

Update employee

PUT /hr/employees/{id}

Required permission: hr.employees.write Send only the fields that change; the others are kept. Accepts the same fields as creation.

{ "salary": 950.00, "job_title_id": "uuid" }

To switch an employee to hourly pay:

{ "pay_type": "hourly", "hourly_rate": 3.25 }

To deactivate an employee, send { "is_active": false }. The API does not delete employees: this keeps their payroll history. Their settlement is calculated with the final settlement (finiquito) in FileXpress.

Getting Started

API v2

Billing

Human Resources

Accounting

Inventory

Projects

Receivables & Payables

Pricing & Promotions

Cash

Interactive reference

List employees

Get employee

Job titles

Create employee

Update employee

​List employees

​Get employee

​Job titles

​Create employee

​Update employee

List employees

Get employee

Job titles

Create employee

Update employee