API de contactos, oportunidades y recorridos

Estos endpoints permiten que tu propio código, Zapier o n8n actúen sobre tu cuenta: añadir contactos, abrir y mover oportunidades, inscribir contactos en recorridos y leer los identificadores que esas llamadas necesitan. Usan la misma clave de API que la API de envío.

Authorization: Bearer mia_live_...

Cada familia de endpoints admite 60 solicitudes por minuto y clave. Por encima, recibes 429. Los errores llegan como {"error": "…"} con un estado 4xx. El contrato completo, con cada forma de respuesta, está en la especificación OpenAPI.

Contactos

Crear o actualizar

POST /api/v1/contacts añade una dirección a una lista de contactos, o la actualiza si ya está:

{
  "listId": "list_abc123",
  "email": "[email protected]",
  "fields": { "first_name": "Ada", "company": "Analytical Engines" }
}

Responde 201 para un contacto nuevo y 200 para una actualización, con el contacto guardado. Para enviar hasta 500 de una vez, usa {"listId": "…", "contacts": [{"email": "…", "first_name": "…"}, …]}, que responde con recuentos.

Cada dirección se verifica al guardarse. La API nunca registra una respuesta de consentimiento, así que estos contactos reciben envíos como antes. Un contacto individual que superaría el límite de contactos de tu plan recibe 409.

Buscar

GET /api/v1/[email protected] devuelve el contacto de esa dirección en cada lista, del más reciente al más antiguo. Añade &listId= para buscar solo en una lista. Cada búsqueda queda registrada en el registro de acceso a datos personales de tu cuenta, como un contacto consultado en el panel.

Listas

GET /api/v1/lists devuelve el id, name, fields y rowCount de cada lista de contactos. Ningún dato de contacto.

Oportunidades

Crear

POST /api/v1/deals:

{
  "email": "[email protected]",
  "title": "Annual plan",
  "value": 1200,
  "currency": "EUR"
}

Indica el contacto con email, o con listId más rowId. Con solo un correo, la oportunidad va a la lista actualizada más recientemente que contenga la dirección. Sin pipelineId ni stageId, entra en la primera etapa abierta de tu pipeline predeterminado. currency es USD por defecto.

Envía una cabecera Idempotency-Key (un número de pedido, por ejemplo) para que los reintentos sean seguros. Una repetición con la misma clave responde 200 con "created": false en vez de crear una segunda oportunidad.

Actualizar o mover

PATCH /api/v1/deals/{id} acepta title, value, currency y stageId. Mover a una etapa ganada o perdida cierra la oportunidad. Primero se valida todo el cuerpo, así que una etapa desconocida no cambia nada. Un movimiento dispara el disparador de recorrido Cambio de etapa de una oportunidad y el webhook deal.stage_changed, igual que un movimiento en el tablero.

Pipelines

GET /api/v1/pipelines devuelve tus pipelines, primero el predeterminado, cada uno con sus etapas (id, name, kind). Úsalo para encontrar el stageId al que mover una oportunidad.

Recorridos

GET /api/v1/journeys lista tus recorridos con su identificador, nombre, disparador y si están activos. ?trigger=api devuelve solo aquellos en los que tu código puede inscribir contactos.

POST /api/v1/journeys/{id}/trigger con {"email": "…", "listId": "…"} inscribe a un contacto en un recorrido cuyo disparador es Llamada a la API. Consulta recorridos.

Eventos de ejemplo

GET /api/v1/events/sample?type=deal.stage_changed devuelve {"events": [ … ]} con un sobre de webhook de ejemplo de ese tipo, o uno de cada tipo sin type. Las herramientas de automatización lo usan para enseñarte los campos antes de que llegue un evento real.

Webhooks

GET, POST /api/v1/webhooks y DELETE /api/v1/webhooks/{id} gestionan las suscripciones a eventos. Consulta webhooks y eventos.