# Listar (/docs/developers/api-reference/employees/list)

## Descripcion general [#descripcion-general]

Este endpoint permite obtener un listado paginado de los empleados pertenecientes a tu organización. Los resultados se devuelven en formato JSON e incluyen metadatos de paginación. Cada fila es un objeto **plano** con los datos personales del empleado **y** los de su empleo actual (razón social, estatus, fechas, asignaciones, compensación, calendario/contrato y unidades organizacionales). Los empleados eliminados se excluyen automáticamente. El tamaño de página es fijo en 20 resultados.

## Endpoint [#endpoint]

`GET https://app.integranom.com/api/v1/employees`

## Consulta multiples empleados [#consulta-multiples-empleados]

***

## Query params [#query-params]

| Parametro | Tipo        | Requerido | Default | Descripcion                                           |
| --------- | ----------- | --------- | ------- | ----------------------------------------------------- |
| `page`    | integer ≥ 1 | No        | 1       | Página solicitada. El tamaño de página es fijo en 20. |

**cURL**

```bash
curl -X GET "https://app.integranom.com/api/v1/employees" \
-H "Authorization: Bearer TU_API_KEY" \
-H "Content-Type: application/json"
```

**Respuesta**

```json
{
"count": 42,
"page": 1,
"page_size": 20,
"total_pages": 3,
"next": "https://app.integranom.com/api/v1/employees?page=2",
"previous": null,
"results": [
  {
    "employee_number": 1,
    "internal_number": null,
    "first_name": "María",
    "middle_name": null,
    "paternal_last_name": "González",
    "maternal_last_name": "Pérez",
    "gender": "female",
    "birth_date": "1990-01-01T00:00:00.000Z",
    "birth_country": "México",
    "birth_state": "CDMX",
    "birth_state_code": null,
    "birth_municipality_code": null,
    "birth_city": "Ciudad de México",
    "birth_place": "Ciudad de México",
    "nationality": "Mexicana",
    "phone_number": "+525512345678",
    "secondary_phone_number": null,
    "rfc": "GOPM900101AB1",
    "curp": "GOPM900101MDFNRR07",
    "postal_code": "06000",
    "work_center_state_code": "CMX",
    "home_street": null,
    "home_exterior_number": null,
    "home_interior_number": null,
    "home_neighborhood": null,
    "home_municipality_code": null,
    "home_city": null,
    "home_state_code": null,
    "home_postal_code": null,
    "fiscal_address_same_as_home": false,
    "domicile_state_code": null,
    "fiscal_street": null,
    "fiscal_exterior_number": null,
    "fiscal_interior_number": null,
    "fiscal_neighborhood": null,
    "fiscal_municipality_code": null,
    "fiscal_city": null,
    "bank": null,
    "clabe": null,
    "account_number": null,
    "card_number": null,
    "notes": null,
    "legal_entity_number": 1,
    "status": "active",
    "hire_date": "2026-01-15T00:00:00.000Z",
    "seniority_date": null,
    "termination_date": null,
    "job_position_code": "DEV",
    "branch_code": "CDMX",
    "department_code": "ING",
    "cost_center_code": "CC01",
    "employer_registration": "A1234567890",
    "imss_number": "12345678903",
    "contributes_to_imss": true,
    "worker_type": "subordinate",
    "minimum_wage_zone": "general",
    "imss_worker_type": "permanent",
    "imss_work_schedule": "full",
    "salary_type": "fixed",
    "is_unionized": false,
    "receives_annual_isr_adjustment": true,
    "opts_into_annual_isr_adjustment": false,
    "is_included_in_payroll_calculations": true,
    "daily_base_salary": "500.0000",
    "regimen_fiscal": "02",
    "work_shift_type": "01",
    "payroll_calendar_number": 2,
    "contract_number": 5,
    "work_schedule_number": 3,
    "work_schedule_bundle_number": null,
    "work_schedule_bundle_start_step": null,
    "organizational_units": [
      { "organizational_unit_number": 10, "organizational_unit_type_key": "region" }
    ],
    "created_at": "2026-05-25T10:00:00.000Z",
    "updated_at": "2026-05-25T10:00:00.000Z"
  }
]
}
```

## Consulta un empleado especifico [#consulta-un-empleado-especifico]

***

Se puede buscar un empleado particular por su número de empleado (filtro de coincidencia exacta).

## Query params [#query-params-1]

| Parametro         | Tipo    | Requerido | Default | Descripcion                           |
| ----------------- | ------- | --------- | ------- | ------------------------------------- |
| `employee_number` | integer | No        | -       | Filtra por número de empleado exacto. |

**cURL**

```bash
curl -X GET "https://app.integranom.com/api/v1/employees?employee_number=1" \
-H "Authorization: Bearer TU_API_KEY" \
-H "Content-Type: application/json"
```

**Respuesta**

```json
{
"count": 1,
"page": 1,
"page_size": 20,
"total_pages": 1,
"next": null,
"previous": null,
"results": [
  {
    "employee_number": 1,
    "internal_number": null,
    "first_name": "María",
    "middle_name": null,
    "paternal_last_name": "González",
    "maternal_last_name": "Pérez",
    "gender": "female",
    "birth_date": "1990-01-01T00:00:00.000Z",
    "birth_country": "México",
    "birth_state": "CDMX",
    "birth_state_code": null,
    "birth_municipality_code": null,
    "birth_city": "Ciudad de México",
    "birth_place": "Ciudad de México",
    "nationality": "Mexicana",
    "phone_number": "+525512345678",
    "secondary_phone_number": null,
    "rfc": "GOPM900101AB1",
    "curp": "GOPM900101MDFNRR07",
    "postal_code": "06000",
    "work_center_state_code": "CMX",
    "home_street": null,
    "home_exterior_number": null,
    "home_interior_number": null,
    "home_neighborhood": null,
    "home_municipality_code": null,
    "home_city": null,
    "home_state_code": null,
    "home_postal_code": null,
    "fiscal_address_same_as_home": false,
    "domicile_state_code": null,
    "fiscal_street": null,
    "fiscal_exterior_number": null,
    "fiscal_interior_number": null,
    "fiscal_neighborhood": null,
    "fiscal_municipality_code": null,
    "fiscal_city": null,
    "bank": null,
    "clabe": null,
    "account_number": null,
    "card_number": null,
    "notes": null,
    "legal_entity_number": 1,
    "status": "active",
    "hire_date": "2026-01-15T00:00:00.000Z",
    "seniority_date": null,
    "termination_date": null,
    "job_position_code": "DEV",
    "branch_code": "CDMX",
    "department_code": "ING",
    "cost_center_code": "CC01",
    "employer_registration": "A1234567890",
    "imss_number": "12345678903",
    "contributes_to_imss": true,
    "worker_type": "subordinate",
    "minimum_wage_zone": "general",
    "imss_worker_type": "permanent",
    "imss_work_schedule": "full",
    "salary_type": "fixed",
    "is_unionized": false,
    "receives_annual_isr_adjustment": true,
    "opts_into_annual_isr_adjustment": false,
    "is_included_in_payroll_calculations": true,
    "daily_base_salary": "500.0000",
    "regimen_fiscal": "02",
    "work_shift_type": "01",
    "payroll_calendar_number": 2,
    "contract_number": 5,
    "work_schedule_number": 3,
    "work_schedule_bundle_number": null,
    "work_schedule_bundle_start_step": null,
    "organizational_units": [
      { "organizational_unit_number": 10, "organizational_unit_type_key": "region" }
    ],
    "created_at": "2026-05-25T10:00:00.000Z",
    "updated_at": "2026-05-25T10:00:00.000Z"
  }
]
}
```

## Errores [#errores]

| Status | Causa                                |
| ------ | ------------------------------------ |
| `400`  | Valor inválido en `employee_number`. |
| `401`  | API key ausente o inválida.          |