API de GoHighLevel: Guía de Integración para Desarrolladores

La API de GoHighLevel permite conectar la plataforma con cualquier sistema externo, automatizar procesos que van más allá de los workflows nativos y construir integraciones personalizadas. En esta guía cubrimos todo lo que un desarrollador necesita saber para empezar: los endpoints principales, los dos métodos de autenticación (API Key y OAuth 2.0), cómo configurar webhooks para eventos en tiempo real, los rate limits y casos de uso prácticos. Si no tienes experiencia técnica, este tutorial es avanzado; te recomendamos empezar por nuestros tutoriales de GoHighLevel y los workflows antes de abordar la API.

Visión general de la API de GoHighLevel

La API de GoHighLevel es una API REST que permite interactuar programáticamente con prácticamente todas las funcionalidades de la plataforma: contactos, oportunidades, calendarios, workflows, conversaciones, funnels, pagos y más. Todas las respuestas se devuelven en formato JSON.

Existen dos versiones de la API:

• API v1: La versión original, que usa autenticación por API Key. Sigue operativa pero no recibe nuevas funcionalidades. La documentación está disponible en developers.gohighlevel.com.
• API v2: La versión actual y recomendada, que usa OAuth 2.0 para la autenticación. Ofrece más endpoints, mejores respuestas de error y documentación más completa. La base URL es https://services.leadconnectorhq.com.

Para nuevas integraciones, siempre recomendamos usar la API v2. La v1 solo tiene sentido si estás manteniendo una integración existente que ya la usa y no tienes recursos para migrar.

La documentación oficial de la API está disponible en el portal de desarrolladores de GoHighLevel. Es importante consultarla como referencia principal, ya que los endpoints pueden actualizarse con frecuencia. Esta guía complementa la documentación oficial con explicaciones en español, contexto y ejemplos prácticos.

Autenticación: API Key vs OAuth 2.0

El primer paso para usar la API es autenticarte. GoHighLevel ofrece dos métodos, cada uno adecuado para diferentes escenarios.

API Key (v1)

El método más sencillo. Cada subcuenta de GoHighLevel tiene una API Key única que puedes encontrar en Settings > Business Profile > API Key. Para usarla, incluye la clave en el header de cada petición:

Authorization: Bearer tu_api_key_aqui

Ventajas: Configuración inmediata, ideal para scripts internos y automatizaciones rápidas.
Limitaciones: Solo accede a los datos de una subcuenta. Si gestionas múltiples clientes, necesitas una API Key por cada uno. No es adecuada para aplicaciones que distribuyas a terceros.

OAuth 2.0 (v2)

El método recomendado para integraciones profesionales. OAuth 2.0 permite que tu aplicación solicite acceso a la cuenta de un usuario de GoHighLevel sin necesitar su API Key directamente. El flujo funciona así:

1. Registra tu aplicación en el portal de desarrolladores de GoHighLevel (marketplace.gohighlevel.com). Obtendrás un Client ID y un Client Secret.
2. Redirige al usuario a la página de autorización de GoHighLevel, donde aceptará los permisos que tu app solicita (scopes).
3. Recibe un código de autorización en tu URL de callback.
4. Intercambia el código por un access token y un refresh token.
5. Usa el access token en tus peticiones a la API.
6. Refresca el token cuando expire (cada 24 horas) usando el refresh token.

Ventajas: Más seguro, permite acceder a múltiples cuentas con una sola aplicación, necesario para publicar en el marketplace.
Limitaciones: Configuración más compleja, necesitas gestionar el ciclo de vida de los tokens.

Scopes (permisos)

Al usar OAuth 2.0, debes especificar qué permisos necesita tu aplicación. Los scopes más comunes son:

• contacts.readonly / contacts.write — Leer/escribir contactos.
• opportunities.readonly / opportunities.write — Leer/escribir oportunidades.
• calendars.readonly / calendars.write — Leer/escribir calendarios y citas.
• conversations.readonly / conversations.write — Leer/escribir conversaciones.
• workflows.readonly — Leer workflows (no se pueden crear workflows por API).
• locations.readonly / locations.write — Leer/escribir subcuentas.

Solicita solo los permisos que tu aplicación realmente necesita. Esto es una buena práctica de seguridad y aumenta la probabilidad de que los usuarios acepten la autorización.

Endpoints principales de la API

La API de GoHighLevel cubre la mayoría de las funcionalidades de la plataforma. Estos son los endpoints que más se usan en integraciones reales:

Contactos

El recurso más usado de la API. Permite crear, leer, actualizar y eliminar contactos, así como buscar por email, teléfono o cualquier campo.

• GET /contacts/ — Listar contactos (con filtros y paginación).
• GET /contacts/:id — Obtener un contacto específico.
• POST /contacts/ — Crear un contacto nuevo.
• PUT /contacts/:id — Actualizar un contacto existente.
• DELETE /contacts/:id — Eliminar un contacto.
• GET /contacts/lookup — Buscar contacto por email o teléfono.
• POST /contacts/:id/tags — Añadir tags a un contacto.

Oportunidades

Gestiona las oportunidades del pipeline de ventas.

• GET /opportunities/ — Listar oportunidades.
• POST /opportunities/ — Crear una oportunidad.
• PUT /opportunities/:id — Actualizar (mover de etapa, cambiar estado).
• DELETE /opportunities/:id — Eliminar una oportunidad.

Calendarios y citas

• GET /calendars/ — Listar calendarios.
• GET /calendars/:id/appointments — Listar citas de un calendario.
• POST /calendars/:id/appointments — Crear una cita.
• PUT /calendars/appointments/:id — Actualizar una cita.

Conversaciones

• GET /conversations/ — Listar conversaciones.
• GET /conversations/:id/messages — Obtener mensajes de una conversación.
• POST /conversations/messages — Enviar un mensaje (email, SMS).

Locations (subcuentas)

• GET /locations/ — Listar subcuentas.
• GET /locations/:id — Obtener detalles de una subcuenta.
• POST /locations/ — Crear una subcuenta (solo con plan adecuado).

Webhooks: eventos en tiempo real

Los webhooks permiten que GoHighLevel notifique a tu sistema cuando ocurre un evento, en lugar de tener que consultar la API periódicamente (polling). Son fundamentales para integraciones en tiempo real.

Cómo funcionan los webhooks

Configuras una URL de tu servidor en GoHighLevel, y cada vez que ocurre un evento específico, GoHighLevel envía una petición HTTP POST a esa URL con los datos del evento en formato JSON. Tu servidor procesa esos datos y ejecuta la lógica que necesites.

Eventos disponibles

Los eventos más comunes que puedes suscribir son:

• ContactCreate / ContactUpdate / ContactDelete: Cuando se crea, modifica o elimina un contacto.
• OpportunityCreate / OpportunityUpdate: Cuando se crea o mueve una oportunidad.
• AppointmentCreate / AppointmentUpdate: Cuando se agenda o modifica una cita.
• NoteCreate: Cuando se añade una nota a un contacto.
• TaskCreate: Cuando se crea una tarea.
• InboundMessage: Cuando se recibe un mensaje entrante.
• OutboundMessage: Cuando se envía un mensaje saliente.

Configuración de webhooks

Puedes configurar webhooks de dos formas:

• En la interfaz: Ve a Settings > Webhooks en la subcuenta, introduce tu URL y selecciona los eventos.
• Por API: Usa el endpoint POST /webhooks/ para crear webhooks programáticamente.

Buenas prácticas para webhooks:

• Responde siempre con un HTTP 200 en menos de 5 segundos. Si tu procesamiento es largo, acepta el webhook inmediatamente y procesa los datos en segundo plano.
• Implementa un mecanismo de reintentos. Si tu servidor no responde, GoHighLevel reintentará el envío varias veces, pero es buena práctica tener tu propio sistema de recuperación.
• Valida los datos recibidos. Aunque los webhooks de GoHighLevel son de confianza, siempre es buena práctica verificar que los datos son válidos antes de procesarlos.
• Registra los webhooks recibidos (logging) para poder depurar problemas.

Rate limits (límites de velocidad)

Como toda API profesional, GoHighLevel impone límites en el número de peticiones que puedes hacer para proteger la estabilidad del servicio. Estos son los límites principales:

• API v2: 10 peticiones por segundo por subcuenta, y un máximo de 100.000 peticiones diarias por aplicación OAuth.
• API v1: Límites más restrictivos, aproximadamente 5 peticiones por segundo.
• Bulk operations: Algunas operaciones masivas (como la importación de contactos) tienen sus propios límites más generosos.

Cuando superas el rate limit, la API devuelve un código HTTP 429 (Too Many Requests) con un header Retry-After que indica cuántos segundos debes esperar antes de reintentar. Para gestionar esto correctamente:

• Implementa un mecanismo de exponential backoff: si recibes un 429, espera 1 segundo; si vuelves a recibirlo, espera 2 segundos; luego 4, 8, etc.
• Usa colas de peticiones para controlar el ritmo de envío y no superar los límites.
• Agrupa operaciones siempre que sea posible. En lugar de hacer 100 peticiones individuales para actualizar 100 contactos, usa los endpoints bulk cuando estén disponibles.

Casos de uso prácticos de la API

La API de GoHighLevel se usa en escenarios donde los workflows nativos no son suficientes. Estos son los casos más comunes que hemos implementado para agencias en España:

1. Sincronización bidireccional con un ERP

Muchas empresas en España usan ERPs como Holded, A3 o SAP. La API permite sincronizar contactos, oportunidades y datos de facturación entre GoHighLevel y el ERP, eliminando la doble entrada de datos. Los webhooks de GoHighLevel notifican al ERP cuando cambia un contacto, y viceversa.

2. Dashboard personalizado con métricas de negocio

Aunque GoHighLevel incluye reporting básico, muchas agencias necesitan dashboards personalizados con métricas específicas. La API permite extraer datos de contactos, oportunidades, citas y conversaciones para alimentar herramientas de BI como Google Data Studio, Power BI o dashboards personalizados.

3. Integración con formularios externos

Si usas formularios de Typeform, JotForm o formularios personalizados en tu web, la API permite enviar los datos directamente al CRM de GoHighLevel y activar workflows automáticamente. Esto es una alternativa a usar los formularios nativos de GoHighLevel.

4. Automatización avanzada con IA

Un caso de uso cada vez más demandado: usar la API para conectar GoHighLevel con servicios de inteligencia artificial (ChatGPT, Claude, etc.) para responder automáticamente a mensajes, cualificar leads o generar propuestas personalizadas basadas en los datos del CRM.

5. Migración masiva desde otras plataformas

Cuando una agencia migra desde HubSpot, ActiveCampaign u otra plataforma, la API permite importar contactos, notas, tags y datos históricos de forma programática, mucho más eficiente que la importación manual por CSV.

GoHighLevel MCP y marketplace de desarrolladores

Además de la API REST, GoHighLevel expone un servidor MCP (Model Context Protocol) que permite a un agente de IA operar la plataforma directamente, y un marketplace de desarrolladores donde se publican las aplicaciones que se integran con ella. Son dos superficies distintas de la misma plataforma y conviene no confundirlas: el MCP es la vía para que un modelo de lenguaje ejecute acciones en tu cuenta; el marketplace es el canal de distribución para aplicaciones de terceros.

Qué es el servidor MCP de GoHighLevel

El Model Context Protocol es un protocolo estándar que permite a clientes de IA descubrir herramientas externas, consultar datos y ejecutar acciones autorizadas. El servidor MCP de HighLevel actúa como puente entre un cliente de IA y tu cuenta: en lugar de programar cada llamada a la API, el agente descubre las operaciones disponibles y las ejecuta bajo los permisos que le hayas concedido.

Según la documentación oficial, existen dos endpoints:

• Endpoint general: https://services.leadconnectorhq.com/mcp/, compatible con cualquier cliente MCP sobre HTTP.
• Endpoints por cliente: https://services.leadconnectorhq.com/mcp/{cliente}/v2. La documentación oficial señala como recomendado el de Claude, /mcp/anthropic/v2, e indica que hay más clientes en camino.

Autenticación del MCP

La autenticación se hace con un Private Integration Token (PIT), distinto de la API Key clásica y de las credenciales OAuth de una app del marketplace. Se genera desde la subcuenta en Settings > Private Integrations > Create New Integration, seleccionando los scopes que quieras conceder. Las cabeceras que espera el endpoint general son:

Authorization: Bearer <tu-private-integration-token>
locationId: <id-de-tu-subcuenta>

Sobre el endpoint recomendado por cliente, la documentación oficial contempla además un inicio de sesión con un clic mediante el flujo de consentimiento de LeadConnector. Para el endpoint general, la documentación de soporte indica que el soporte de OAuth está previsto para una versión futura y que de momento debe usarse el Private Integration Token.

Implicación de seguridad que conviene no pasar por alto: un token de integración privada concede a un agente de IA capacidad de lectura y escritura sobre los datos de la subcuenta según los scopes marcados. Concede solo los mínimos necesarios, usa una subcuenta de pruebas mientras experimentas y trata el token con el mismo cuidado que cualquier credencial de producción.

Qué permite hacer

Los scopes documentados para el servidor MCP cubren contactos, conversaciones y mensajes, oportunidades, calendarios y eventos, pagos, campos personalizados, formularios, ubicaciones, blogs, plantillas de correo y publicación en redes sociales. El endpoint recomendado por cliente añade además productos y tienda, facturas y presupuestos, y el planificador social.

En ese endpoint de segunda versión, la documentación describe un conjunto unificado de cinco herramientas (search, fetch, search_operations, describe_operation y execute_operation) en lugar de exponer una herramienta por endpoint. El agente descubre primero qué operaciones existen y luego las ejecuta, lo que reduce el contexto que necesita cargar.

Clientes compatibles

La documentación oficial menciona como compatibles con el endpoint general Cursor, Windsurf, OpenAI Playground, clientes compatibles con Claude, n8n, agentes personalizados y, en general, cualquier cliente MCP sobre HTTP. Para el endpoint recomendado por cliente, la documentación indica que Claude está operativo y que hay endpoints dedicados previstos para otros clientes.

Este es un terreno en movimiento: tanto los endpoints como el conjunto de herramientas han cambiado en poco tiempo. Antes de construir nada sobre el MCP, contrasta el detalle en la documentación oficial de HighLevel, porque cualquier guía, incluida esta, envejece rápido en esta parte concreta.

El marketplace de GoHighLevel para desarrolladores

El marketplace de GoHighLevel es el directorio oficial de aplicaciones e integraciones que se conectan a la plataforma, y es también la puerta de entrada para publicar la tuya. Conviene distinguir sus dos caras:

• Como usuario: es donde encuentras e instalas aplicaciones de terceros en tu cuenta o en las subcuentas de tus clientes.
• Como desarrollador: es donde registras tu aplicación, obtienes las credenciales OAuth que necesita la API v2 y, si quieres, la publicas para el resto de clientes de la plataforma.

El flujo para empezar es directo: se crea una cuenta de desarrollador en el marketplace y, desde el apartado My Apps, se crea la aplicación con la opción Create App. Las aplicaciones que se listan públicamente pasan por un proceso de revisión previo. La documentación técnica de la API y del propio marketplace se publica en el portal de desarrolladores de HighLevel.

Registrar una aplicación en el marketplace no es solo un paso para distribuir: es el requisito para trabajar con OAuth 2.0 en la API v2, tal como se explica más arriba en esta guía. Si tu integración es interna y solo va a operar sobre tus propias subcuentas, el Private Integration Token suele ser suficiente y te ahorra todo el ciclo de la app.

Preguntas frecuentes sobre la API de GoHighLevel