# Listar (/docs/developers/api-reference/legal-entities/list)

## Descripcion general [#descripcion-general]

Este endpoint permite obtener un listado paginado de las razones sociales pertenecientes a tu organización. Una razón social (legal entity) agrupa empleados y registros patronales bajo un mismo nombre fiscal. Las razones sociales eliminadas se excluyen automáticamente. El tamaño de página es fijo en 20 resultados.

`legal_entity_number` es un identificador secuencial por organización, estable y reutilizado como segmento de URL en `PATCH` y `DELETE`. Los números de razones sociales eliminadas **no** se reasignan a registros futuros. `updated_at` es `null` mientras la razón social no haya sido modificada desde su creación.

## Endpoint [#endpoint]

`GET https://app.integranom.com/api/v1/legal-entities`

## Consulta multiples razones sociales [#consulta-multiples-razones-sociales]

***

## Query params [#query-params]

| Parametro | Tipo                  | Requerido | Default | Descripcion                                                                                             |
| --------- | --------------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `page`    | integer ≥ 1           | No        | 1       | Página solicitada. Valores fuera de rango o no numéricos caen a `1`. El tamaño de página es fijo en 20. |
| `active`  | `"true"` \| `"false"` | No        | -       | Filtra por el flag `is_active`. Cualquier otro valor responde con `400`.                                |

**cURL**

```bash
curl -X GET "https://app.integranom.com/api/v1/legal-entities" \
-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/legal-entities?page=2",
"previous": null,
"results": [
  {
    "legal_entity_number": 1,
    "name": "Acme S.A. de C.V.",
    "is_active": true,
    "created_at": "2026-05-25T10:00:00.000Z",
    "updated_at": null
  }
]
}
```

## Consulta una razon social especifica [#consulta-una-razon-social-especifica]

***

Se puede buscar una razón social particular por su número (org-scoped) o por nombre exacto (recortado). Los nombres no son únicos dentro de la organización.

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

| Parametro             | Tipo             | Requerido | Default | Descripcion                                                                                  |
| --------------------- | ---------------- | --------- | ------- | -------------------------------------------------------------------------------------------- |
| `legal_entity_number` | integer positivo | No        | -       | Filtra por número exacto. Debe ser entero positivo; cualquier otro valor responde con `400`. |
| `name`                | string           | No        | -       | Filtra por nombre exacto (recortado).                                                        |

**cURL**

```bash
curl -X GET "https://app.integranom.com/api/v1/legal-entities?legal_entity_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": [
  {
    "legal_entity_number": 1,
    "name": "Acme S.A. de C.V.",
    "is_active": true,
    "created_at": "2026-05-25T10:00:00.000Z",
    "updated_at": null
  }
]
}
```

## Forma del recurso [#forma-del-recurso]

Cada elemento de `results[]` (y cada respuesta de `POST`/`PATCH` single) tiene la siguiente forma:

| Campo                 | Tipo                             | Notas                                                                                                                                               |
| --------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `legal_entity_number` | integer                          | Identificador secuencial por organización. Estable, reutilizado como segmento de URL. Los números de razones sociales eliminadas no se reasignan.   |
| `name`                | string                           | Razón social. No es necesario que sea única dentro de la organización.                                                                              |
| `is_active`           | boolean                          | Controlado por el usuario. Independiente del borrado — una razón social inactiva sigue apareciendo en `GET` (salvo que filtres con `active=false`). |
| `created_at`          | timestamp ISO 8601 (UTC)         |                                                                                                                                                     |
| `updated_at`          | timestamp ISO 8601 (UTC) \| null | `null` mientras la razón social no haya sido modificada desde su creación.                                                                          |

## Errores [#errores]

| Status | Causa                                                                             |
| ------ | --------------------------------------------------------------------------------- |
| `400`  | `legal_entity_number` no es entero positivo; o `active` no es `"true"`/`"false"`. |
| `401`  | API key ausente o inválida.                                                       |
| `403`  | API key no vinculada a una organización, o no autorizada para esta operación.     |
| `500`  | Error no manejado. Cuerpo: `{ "message": "Internal Server Error" }`.              |