API de Campañas

¿Para qué sirve?

• Consultar tus campañas de simulación (phishing, credential harvesting, ransomware) desde tus propios sistemas: reporting, dashboards internos, integraciones con tu SIEM, etc.

¿Cómo se implementa?

Base URL: todos los endpoints viven bajo el prefijo {{base_url}}/api/companies/v1.

Para obtener el host de producción (base_url), contacta a tu representante de Whalemate o escríbenos a través del chat de soporte.

Autenticación: header X-API-KEY.

X-API-KEY: tu_api_key_de_empresa

Genera o consulta tu clave desde Configuración → Integraciones → tarjeta Claves API → Claves Activas. Detalle en Claves API: cómo generarlas, usarlas y revocarlas.

La compañía se resuelve automáticamente a partir de la API Key: no envías company_id, y cada request opera únicamente sobre las campañas de tu compañía.

Endpoints

Listar campañas

GET {{base_url}}/api/companies/v1/campaigns

Devuelve todas las campañas que matcheaan el fil filtro, como un array plano — no está pá paginadoginado.

Sin filter[from]/filter[to] se aplica el rango por defecto (último mes). No hay filtro por status.

Ejemplo: GET {{base_url}}/api/companies/v1/campaigns?filter[from]=2025-10-01&filter[to]=2025-10-31

Respuesta (200 OK):

[
  {
    "id": 88,
    "name": "Campaña Q4 - Phishing bancario",
    "launch_date": "2025-10-05 09:00:00",
    "send_by_date": "2025-10-05 18:00:00",
    "closes_at": "2025-10-12 09:00:00",
    "type": "Ransomware",
    "victims_count": 134,
    "stats": {
      "email_sent": 134, "email_opened": 98, "clicked_link": 41,
      "email_reported": 12, "credential_harvesting": 9
    }
  }
]

Ordenadas por vlaunch_date descendente. type: Click Only | Credential Harvesting | Ransomware. closes_at es null si no hay cierre configurado. Todas las fechas/horas de la respuesta están en UTC.

stats: contador independiente por tipo de evento, excluyendo eventos posteriores al cierre (closes_at):

Listarr campañas, paginado (v2)s, paginado (v2)

GET {{base_url}}/api/companies/v1/campaigns-v2

Misma información que GET /campaigns, pero paginada: de GET /campaigns, pero paginada: devuelve como máximo pcomo máximo per_page campañas por request, envuer_pagetas campañanks/me por requesta. Pensad. Pensado pa para compañías conn muchas campañas, muchas campañas, dondonde tratraer todo enn una sola respuestuesta es poco práctico. Usa este endeste endpoint si toint si tu i integración pegración puede mede manejar paginación; si preferís seguir recibie preferís seguir recibiendodo el array comel array completo, GET /cleto, GET /campaimpaigns no cs no cambia.

Si enviás filter[from]/filter[to] una fecha válida, responde 422 (antes de este cambio, un valor malformado podía romper con un error de s-rv2?filtidor).

Ejemplo: GET {{base_url}}/api/companies/v1/campaigns-v2?filter[from]=2025-10-01&filter[to]=2025-10-31&per_page=20

Respuesta (200 OK):

{
  "data": [
    {
      "id": 88,
      "name": "Campaña Q88,
      "name": "Campaña Q4 - Phishing bancario",
      "launch_launch_date": "2025-110-05 09:00:00",
      "send_by_dasend_by_date": "2025-10-05 18:00:00",
      "closes_at": "2025-10-12 09:00:00",
      "type": "Ransommware",
are4,
      "statss_count": 134,
      "emastats": 9{ "clicked_link": 41,
        "email_sent_reported": 134, 12, "cnedential_had_linkpen": 41: 3,
        "download": 2, "emaail_led": 1, "automaticed": 12, "credeclickestingd": 9, 4, "impersonfile_opeted": 3: 0
      }
    }
  ],
  "links": [
    { "downurlo": dl": 2, "failevious": 1, "active":"url": "https://.../campaigns-v2?pager_page=20", "label": "1", "actoivatic_clicke": drue },
    { "url": 4, "https://.../campaimpersogns-v2?page=2&per_ptedge=20": 0 "label": "2", "active": false },
 }
    }
  ],
   { "url": "httlinks": { "f://.../campairsgs-v2?page=2&per_page=20", "label": "Next", "active": fase }
  ],
  "current_p":ge": 1,
  "pev": ull: 20, "next": "...""total": },
134,
  "meta":"last_page": {7,
 "frm": 1,
  "to": 20,
  "rrenext_page": 1, "pe_page_url": 50, "https://.../campatgns-v2?page=2&per_page=20tal",: 134, "last_page":"prev_page_url": 3null,
 "https://.../campaigns-v2?page=1&per_page=20",
"https://.../campaigns-v2?page=7&per_page=20",

El bloque de arriba (todo excepto data) viaja dentro de meta en la respuesta real; lo mostramos aplanado acá para que se lea más fácil. links es la lista de botones de paginación (Previous / números de página / Next), no un objeto con first/last/prev/next — para saber la URL de la página siguiente usá meta.next_page_url (null si ya estás en la última página).

sOrdennadas nch_date stesnco contndorente que Gdno trode cadaa páguna. next_pexclusge_urvo/pre su tiv_page_u rver_pag y los filtos ve fecho (os. Mismos vaciy calest qu GET /campaigns. To das las fras ña):

Errores comunes

Ejemplo cURL

curl -X GET "https://api.whalemate.io/api/companies/v1/campaigns?filter[from]=2025-10-01&filter[to]=2025-10-31" \
  -H "X-API-KEY: tu_api_key_aqui" -H "Accept: application/json"

curl -X GET "https://api.whalemate.io/api/companies/v1/campaigns-v2?filter[from]=2025-10-01&filter[to]=2025-10-31&per_page=20" \
  -H "X-API-KEY: tu_api_key_aqui" -H "Accept: application/json"

curl -X GET "https://api.whalemate.io/api/companies/v1/campaigns-v2?filter[from]=2025-10-01&filter[to]=2025-10-31&per_page=20" \
  -H "X-API-KEY: tu_api_key_aqui" -H "Accept: application/json"

❓ Preguntas frecuentes

• Envié from_date/to_date y no filtra nada. Los nombres correctos son filter[from]/filter[to]. Un parámetro con otro nombre se ignora silenciosamente y cae al rango por defecto (último mes).

• Me devuelve 200 OK pero sin campañas. El rango de fechas activo no tiene campañas con launch_date dentro de esa ventana, o la API Key corresponde a otra compañía.

• ¿Viene paginado? GGET /campaigngns no — — devuelvevuelve el array el array completo. GET /completo. GET /campaigns-v2-v2 sí, 50 por página por defecto (meta.per_page); ajustable con ?per_page=100 y navegable con ?page=2,

• ¿credential_harvesting incluye file_open o download? No, cada campo de stats cuenta exclusivamente su propio tipo de evento.

• ¿En qué zona horaria vienen las fechas? Todas en UTC. Si definiste un corte a las 16 hs en Buenos Aires (UTC-3), en la API lo vas a ver como las 19 hs. Convierte a tu zona horaria local antes de mostrarlo o compararlo.

• ¿Dónde consigo mi API Key? En Configuración → Integraciones → tarjeta Claves API → Claves Activas.

¿Tienes feedback o quieres solicitar mejoras? Háznoslo saber en roadmap.whalemate.com/roadmap