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

## Descripcion general [#descripcion-general]

Este endpoint permite obtener un listado paginado de las **definiciones de campos personalizados de empleados** en tu organización. Los resultados se devuelven en formato JSON e incluyen metadatos de paginación. Las definiciones eliminadas se excluyen automáticamente. El tamaño de página es fijo en 20 resultados.

`key` es el identificador público de cada definición (snake\_case, único por organización) y se usa como segmento de URL en `PATCH` y `DELETE`. `select_options` se devuelve como arreglo de strings (vacío o ausente cuando `type` no es `select`).

## Endpoint [#endpoint]

`GET https://app.integranom.com/api/v1/employee-custom-fields`

## Consulta multiples definiciones [#consulta-multiples-definiciones]

***

## 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. |
| `active`  | `"true"` \| `"false"` | No        | -       | Filtra por el flag `is_active`.                       |

**cURL**

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

**Respuesta**

```json
{
"count": 4,
"page": 1,
"page_size": 20,
"total_pages": 1,
"next": null,
"previous": null,
"results": [
  {
    "key": "shirt_size",
    "name": "Talla de playera",
    "type": "select",
    "description": "Talla solicitada por el empleado.",
    "select_options": ["XS", "S", "M", "L", "XL"],
    "is_required_for_create": false,
    "is_required_for_payroll": false,
    "is_active": true,
    "sort_order": 0,
    "created_at": "2026-05-25T10:00:00.000Z",
    "updated_at": "2026-05-25T10:00:00.000Z"
  }
]
}
```

## Consulta una definicion especifica [#consulta-una-definicion-especifica]

***

Se puede buscar una definición particular por `key` (snake\_case, coincidencia exacta) o por `type` (uno de los cinco valores del enum).

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

| Parametro | Tipo                                                  | Requerido | Default | Descripcion               |
| --------- | ----------------------------------------------------- | --------- | ------- | ------------------------- |
| `key`     | string                                                | No        | -       | Filtra por `key` exacto.  |
| `type`    | `text` \| `number` \| `date` \| `boolean` \| `select` | No        | -       | Filtra por tipo de campo. |

**cURL**

```bash
curl -X GET "https://app.integranom.com/api/v1/employee-custom-fields?key=shirt_size" \
-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": [
  {
    "key": "shirt_size",
    "name": "Talla de playera",
    "type": "select",
    "description": "Talla solicitada por el empleado.",
    "select_options": ["XS", "S", "M", "L", "XL"],
    "is_required_for_create": false,
    "is_required_for_payroll": false,
    "is_active": true,
    "sort_order": 0,
    "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 `type` (debe ser uno de los cinco valores del enum) o en `active`. |
| `401`  | API key ausente o inválida.                                                          |