---
title: "Listar contactos"
method: POST
path: "/tools/contacts_getContacts"
tags: ["Contacts"]
---

# Listar contactos

`POST /tools/contacts_getContacts`

## Request

- Base URL: `https://mcp.alegra.com`
- URL: `https://mcp.alegra.com/tools/contacts_getContacts`
- Auth: HTTP bearer

Herramienta MCP: `contacts_getContacts`.

Lista los contactos de la cuenta (clientes, proveedores o ambos) con filtros opcionales y paginación. Los filtros se envían dentro del objeto `params` (p. ej. `{"arguments": {"params": {"type": "client", "limit": 10}}}`).

Ejemplo de llamada JSON-RPC:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "contacts_getContacts",
    "arguments": {
      "params": { "type": "client", "limit": 10 }
    }
  }
}
```

Soporta paginación con `start` y `limit` (hasta 30 por página), orden con `order_field` y `order_direction`, búsqueda por texto libre con `query` (nombre, identificación, email, etc.) y coincidencia exacta de documento con `identification`. Con `type` filtras por `client` o `provider`; con `status` por `active` o `inactive`.

Con `metadata: true` la respuesta es `{ metadata: { total }, data: [...] }` e incluye el total de contactos que coinciden con los filtros; sin `metadata` devuelve solo el arreglo de contactos.

Para buscar un contacto cuando ya conoces su nombre, usa `contacts_getContactByName`.

Solo lectura.

## Request body

- object
  - `params` object: Filtros de la búsqueda de contactos.
    - `limit` integer: Cantidad máxima de contactos a retornar (0–30). Por defecto 30.
    - `start` integer: Desplazamiento inicial de la paginación (número de contactos a omitir).
    - `order_direction` string: Dirección del ordenamiento de los resultados.
    - `order_field` string: Campo por el cual ordenar los resultados.
    - `query` string: Texto libre. Busca coincidencias en nombre, identificación, email, etc.
    - `identification` string: Filtra por número de identificación exacto (NIT, cédula, RFC, según país).
    - `name` string: Filtra por nombre del contacto.
    - `type` 'client' | 'provider': Filtra por tipo de contacto. Si se omite, retorna ambos.
    - `metadata` boolean: Cuando es `true`, la respuesta es `{ metadata: { total }, data: [...] }` e incluye el total de contactos que coinciden con los filtros.
    - `status` 'active' | 'inactive': Filtra contactos por estado (`active` o `inactive`). Filtrado en el backend.
    - `mode` 'advanced' | 'simple': Modo de respuesta: `simple` retorna un subconjunto de campos; `advanced` retorna el contacto completo.

## Response `200`

Lista de contactos.

## Other responses

- `401`: No autorizado (token de Alegra inválido o expirado).

---

[API](https://skmtc.dev/alegra/apis/mcp-alegra.md) - [All operations](https://skmtc.dev/alegra/apis/mcp-alegra/llms.txt) - [OpenAPI document](https://skmtc.dev/alegra/apis/mcp-alegra/revisions/528447af020b?raw)