Skip to main content

​
Introduction

The Employees API provides endpoints to manage and retrieve employee information within the Integra system. This API allows you to query employee records, access supervisor lists, and retrieve detailed employee information including organizational relationships and contact details. All endpoints in this API require authentication via Bearer token.

​
Base URL

All employee endpoints are prefixed with: 
/empleados

​
Employee Model

The Empleado model represents an employee in the system with the following structure:
​
id
integer
required
Unique identifier for the employee
​
codigo
string
required
Employee code (unique identifier, max 20 characters)
​
nombre
string
required
Employee’s first name (max 50 characters)
​
apellidoPaterno
string
required
Employee’s paternal surname (max 50 characters)
​
apellidoMaterno
string
Employee’s maternal surname (max 50 characters)
​
nombreCompleto
string
Full name (automatically generated, max 152 characters)
​
puesto
object
Employee’s position information
​
departamento
object
Employee’s department information
​
unidad
object
Business unit information
​
contacto
object
Employee contact information
​
fechaAlta
string
Hire date (ISO 8601 format: YYYY-MM-DD)
​
fechaBaja
string
Termination date (ISO 8601 format: YYYY-MM-DD)
​
fechaReingreso
string
Rehire date if applicable (ISO 8601 format: YYYY-MM-DD)
​
estatus
string
Employee status (default: “A” for Active)
​
sexo
string
Gender
​
gestores
array
List of managers/supervisors for this employee

​
Response Wrapper

All successful API responses are wrapped in a standard ResponseData object: 
{
  "success": true,
  "data": {
    // Response payload here (single object or array)
  },
  "message": "Descripción de la operación",
  "meta": {
    // Optional metadata (pagination info, etc.)
  }
}
​
success
boolean
Indicates whether the request was successful
​
data
object | array
The actual response data (employee object or array of employees)
​
message
string
Descriptive message about the operation
​
meta
object
Optional metadata (e.g., pagination information)

​
Common Use Cases

​
1. List All Employees

Retrieve a list of all employees in the system, with optional filtering by department, position, unit, supervisor, or status.

​
2. Get Employee Details

Fetch comprehensive information about a specific employee, including their organizational relationships, contact information, and assigned managers.

​
3. Get Supervisors

Retrieve a list of employees who have supervisor roles, optionally filtered by active status.

​
4. Filter Employees

Query employees using various filter criteria:
  • By supervisor ID
  • By position ID
  • By department
  • By business unit
  • By zone
  • By employee code
  • By status (active/inactive)

​
Authentication

All endpoints require authentication using a Bearer token in the Authorization header: 
Authorization: Bearer {your_token_here}
Requests without valid authentication will receive a 401 Unauthorized response.

​
Error Handling

Error responses follow this structure: 
{
  "success": false,
  "message": "Error description",
  "data": null
}
Common HTTP status codes:
  • 200 OK - Request successful
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Missing or invalid authentication
  • 404 Not Found - Employee not found
  • 500 Internal Server Error - Server error

​
Next Steps

Employee Management

Learn about all CRUD operations and filtering options

Authentication

Set up authentication for API access

Build docs developers (and LLMs) love

Get started for freeTalk to us