API de Empleados

Referencia técnica para gestionar empleados (colaboradores objetivo) desde sistemas externos: listar, crear, actualizar, eliminar y consultar su historial de eventos de campaña vía la API de Whalemate.

¿Para qué sirve?

Gestionar los empleados (colaboradores objetivo de tus simulaciones) desde tus propios sistemas: nómina, HRIS, scripts de sincronización, etc.
Crear, actualizar, consultar y eliminar empleados sin pasar por la interfaz de Whalemate.
Consultar el historial de eventos de campaña de un colaborador (aperturas, clics, reportes, credenciales comprometidas, 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:

La API usa autenticación por API Key mediante el header X-API-KEY.

X-API-KEY: tu_api_key_de_empresa

Puedes generar o consultar tu clave desde Configuración → Integraciones → tarjeta Claves API → Claves Activas. El detalle está 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 en el body ni en la URL, y cada request opera únicamente sobre las víctimas de tu compañía.

Headers requeridos:

Header	Valor	Obligatorio
`X-API-KEY`	Tu API Key de empresa	✅ Sí
`Content-Type`	`application/json`	✅ Sí (en `POST`/`PUT`)
`Accept`	`application/json`	✅ Sí

Endpoints

Listar empleados

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

Query params

Param	Tipo	Default	Descripción
`per_page`	integer	`20`	Cantidad de resultados por página
`filter[name]`	string	—	Filtra por nombre (coincidencia parcial)
`filter[last_name]`	string	—	Filtra por apellido (parcial)
`filter[email]`	string	—	Filtra por email (parcial)
`filter[department]`	string	—	Filtra por departamento (parcial)
`filter[country]`	string	—	Filtra por país (parcial)
`filter[position]`	string	—	Filtra por cargo (parcial)
`filter[status]`	string	`active`	`active` (excluye eliminadas) \| `inactive` (solo eliminadas) \| `all`

Ejemplo:

GET {{base_url}}/api/companies/v1/victims?filter[country]=Brazil

Respuesta (200 OK)

{
  "data": [
    {
      "id": 12,
      "email": "[email protected]",
      "first_name": "Juan",
      "last_name": "Pérez",
      "department": "Finanzas",
      "position": "Analista",
      "country": "Argentina",
      "personal_id": "30123456",
      "active": true,
      "booster": "normal",
      "groups": [
        { "id": 4, "name": "Finanzas", "type": "custom" }
      ]
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "per_page": 20, "total": 134, "last_page": 7 }
}

Ver un empleado

GET {{base_url}}/api/companies/v1/victims/{id}

Respuesta (200 OK)

Mismo objeto que en el listado, sin el envoltorio data. Devuelve 404 si el id no existe o no pertenece a tu compañía.

Crear un empleado

POST {{base_url}}/api/companies/v1/victims

Body (JSON)

Campo	Tipo	Obligatorio	Descripción
`email`	string	✅	Email único del colaborador
`first_name`	string	✅	Nombre
`last_name`	string	✅	Apellido
`country`	string	✅	País
`language`	string	✅	Uno de `es`, `pt`, `en`
`position`	string	✅	Cargo
`department`	string	✅	Departamento
`booster`	string	✅	Uno de `low`, `normal`, `high`, `critical`
`phone_number`	string	❌	Teléfono con código de país, con `+` (por ejemplo `+5491122334455`) o con `00` adelante. Se aceptan espacios, guiones, puntos y paréntesis, que se limpian antes de guardar. Un número sin `+` ni `00` se rechaza con `422`: Whalemate no adivina el país. Los teléfonos de línea fija válidos se aceptan.
`personal_id`	string	❌	Identificador personal (DNI, legajo, etc.)

Cambio de contrato (1-oct-2026): hasta esa fecha phone_number aceptaba cualquier texto. Desde hoy, si lo envías sin código de país, la API responde 422. Revisa tus integraciones que cargan teléfonos locales (por ejemplo, 10 dígitos) y agrega el código de país antes de enviarlos.

Ejemplo

POST {{base_url}}/api/companies/v1/victims
X-API-KEY: tu_api_key_de_empresa

{
  "email": "[email protected]",
  "first_name": "Ana",
  "last_name": "Gómez",
  "country": "Argentina",
  "language": "es",
  "position": "Contadora",
  "department": "Finanzas",
  "phone_number": "+5491122334455",
  "personal_id": "28999111",
  "booster": "high"
}

Respuesta exitosa (201 Created): el objeto de la víctima creada, con el mismo shape que en Ver una víctima.

Actualizar empleado

PUT {{base_url}}/api/companies/v1/victims/{id}

Acepta los mismos campos que Crear un empleado. email, first_name, last_name, country, language, position, department y booster son obligatorios; phone_number y personal_id son opcionales. El email debe seguir siendo único, ignorando el propio empleado.

Cambio de contrato (1-oct-2026): hasta esa fecha phone_number aceptaba cualquier texto. Desde hoy, si lo envías sin código de país, la API responde 422. Revisa tus integraciones que cargan teléfonos locales (por ejemplo, 10 dígitos) y agrega el código de país antes de enviarlos.

Respuesta (200 OK): el objeto actualizado.

Eliminar empleado

DELETE {{base_url}}/api/companies/v1/victims/{id}

Respuesta (204 No Content): sin body. El colaborador queda como inactivo (soft delete) y deja de aparecer en el listado por defecto (filter[status]=active).

Eventos de un empleado

GET {{base_url}}/api/companies/v1/victims/{id}/events

Devuelve el historial de eventos de campaña del colaborador, ordenado por fecha descendente.

Respuesta (200 OK)

Array plano (sin paginación):

[
  {
    "id": 501,
    "date_time": "2026-05-12 09:31:00",
    "type": "Clicked Link",
    "campaign_name": "Campaña Q2 - Phishing bancario",
    "campaign_id": 33
  }
]

Tipos de evento posibles: Email Sent, Failed, Clicked Link, Email Reported, Email Opened, Credential Harvesting, File Open, Download, Reported, Impersonated.

404 Not Found si la víctima no existe o no pertenece a tu compañía.

Errores comunes

Código	Causa	Body
`401`	Falta el header `X-API-KEY`	`{ "error": "API Key required" }`
`403`	API Key inexistente o revocada	`{ "error": "Invalid API Key" }`
`404`	El recurso no existe o pertenece a otra compañía	—
`422`	Error de validación (email duplicado, campo faltante, valor fuera de enum, teléfono inválido…)	`{ "messages": ["..."], "code": 422 }`
`422`	`phone_number` sin código de país	mismo formato; el mensaje dice que falta el código de país y da el ejemplo `+5491122334455`
`422`	`phone_number` con código de país que no corresponde a un número válido	mismo formato; el mensaje dice que el número no es válido para el país que declara
`409`	Cupo de licencias agotado (solo Crear)	`{ "messages": ["..."], "code": 409, "error_code": "victim_license_limit_reached", "licenses": N, "active_victims": N }`

Ejemplo cURL

curl -X POST https://api.whalemate.io/api/companies/v1/victims \
  -H "X-API-KEY: tu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "Ana",
    "last_name": "Gómez",
    "country": "Argentina",
    "language": "es",
    "position": "Contadora",
    "department": "Finanzas",
    "booster": "high"
  }'

❓ Preguntas frecuentes

¿Dónde consigo mi API Key?

En Configuración → Integraciones → tarjeta Claves API → Claves Activas. Ahí se generan, se listan y se revocan.

¿Qué pasa si elimino una víctima por error?

El borrado es lógico (soft delete): la víctima pasa a estar inactiva pero no se pierde. Podés listarla de nuevo con filter[status]=inactive o all, y volver a crearla/activarla según tu flujo.

¿Puedo crear víctimas en lote (batch)?

El endpoint actual procesa una víctima por solicitud. Si el registro en lote es prioritario para tu organización, podés solicitarlo en roadmap.whalemate.com/roadmap.

¿Cómo asigno una víctima a un grupo desde la API?

Este endpoint no gestiona grupos directamente; el campo groups en la respuesta es de solo lectura. La asignación a grupos se hace desde la plataforma o vía las integraciones de sincronización (Google/Microsoft/Okta).

¿Qué significa el campo booster?

Es el nivel de exposición/atención que la víctima recibe en las simulaciones (low, normal, high, critical). Afecta la frecuencia y dificultad de las campañas que le llegan.

Me llega un 422 al crear un empleado con teléfono, y antes funcionaba.

Revisa que phone_number empiece con + o 00 y tenga el código de país. Desde el 1-oct-2026 un número local sin código de país se rechaza.

¿Puedo mandar el teléfono con espacios o guiones?

Sí, se limpian y se guarda sin esos símbolos.

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

API de Empleados

¿Para qué sirve?

Gestionar los empleados (colaboradores objetivo de tus simulaciones) desde tus propios sistemas: nómina, HRIS, scripts de sincronización, etc.
Crear, actualizar, consultar y eliminar empleados sin pasar por la interfaz de Whalemate.
Consultar el historial de eventos de campaña de un colaborador (aperturas, clics, reportes, credenciales comprometidas, 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:

La API usa autenticación por API Key mediante el header X-API-KEY.

X-API-KEY: tu_api_key_de_empresa

La compañía se resuelve automáticamente a partir de la API Key: no envías company_id en el body ni en la URL, y cada request opera únicamente sobre las víctimas de tu compañía.

Headers requeridos:

Header	Valor	Obligatorio
`X-API-KEY`	Tu API Key de empresa	✅ Sí
`Content-Type`	`application/json`	✅ Sí (en `POST`/`PUT`)
`Accept`	`application/json`	✅ Sí

Endpoints

Listar empleados

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

Query params

Param	Tipo	Default	Descripción
`per_page`	integer	`20`	Cantidad de resultados por página
`filter[name]`	string	—	Filtra por nombre (coincidencia parcial)
`filter[last_name]`	string	—	Filtra por apellido (parcial)
`filter[email]`	string	—	Filtra por email (parcial)
`filter[department]`	string	—	Filtra por departamento (parcial)
`filter[country]`	string	—	Filtra por país (parcial)
`filter[position]`	string	—	Filtra por cargo (parcial)
`filter[status]`	string	`active`	`active` (excluye eliminadas) \| `inactive` (solo eliminadas) \| `all`

Ejemplo:

GET {{base_url}}/api/companies/v1/victims?filter[country]=Brazil

Respuesta (200 OK)

{
  "data": [
    {
      "id": 12,
      "email": "[email protected]",
      "first_name": "Juan",
      "last_name": "Pérez",
      "department": "Finanzas",
      "position": "Analista",
      "country": "Argentina",
      "personal_id": "30123456",
      "active": true,
      "booster": "normal",
      "groups": [
        { "id": 4, "name": "Finanzas", "type": "custom" }
      ]
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "per_page": 20, "total": 134, "last_page": 7 }
}

Ver un empleado

GET {{base_url}}/api/companies/v1/victims/{id}

Respuesta (200 OK)

Mismo objeto que en el listado, sin el envoltorio data. Devuelve 404 si el id no existe o no pertenece a tu compañía.

Crear un empleado

POST {{base_url}}/api/companies/v1/victims

Body (JSON)

Campo	Tipo	Obligatorio	Descripción
`email`	string	✅	Email único del colaborador
`first_name`	string	✅	Nombre
`last_name`	string	✅	Apellido
`country`	string	✅	País
`language`	string	✅	Uno de `es`, `pt`, `en`
`position`	string	✅	Cargo
`department`	string	✅	Departamento
`booster`	string	✅	Uno de `low`, `normal`, `high`, `critical`
`phone_number`	string	❌	Teléfono con código de país, con `+` (por ejemplo `+5491122334455`) o con `00` adelante. Se aceptan espacios, guiones, puntos y paréntesis, que se limpian antes de guardar. Un número sin `+` ni `00` se rechaza con `422`: Whalemate no adivina el país. Los teléfonos de línea fija válidos se aceptan.
`personal_id`	string	❌	Identificador personal (DNI, legajo, etc.)

Cambio de contrato (1-oct-2026): hasta esa fecha phone_number aceptaba cualquier texto. Desde hoy, si lo envías sin código de país, la API responde 422. Revisa tus integraciones que cargan teléfonos locales (por ejemplo, 10 dígitos) y agrega el código de país antes de enviarlos.

Ejemplo

POST {{base_url}}/api/companies/v1/victims
X-API-KEY: tu_api_key_de_empresa

{
  "email": "[email protected]",
  "first_name": "Ana",
  "last_name": "Gómez",
  "country": "Argentina",
  "language": "es",
  "position": "Contadora",
  "department": "Finanzas",
  "phone_number": "+5491122334455",
  "personal_id": "28999111",
  "booster": "high"
}

Respuesta exitosa (201 Created): el objeto de la víctima creada, con el mismo shape que en Ver una víctima.

Actualizar empleado

PUT {{base_url}}/api/companies/v1/victims/{id}

Cambio de contrato (1-oct-2026): hasta esa fecha phone_number aceptaba cualquier texto. Desde hoy, si lo envías sin código de país, la API responde 422. Revisa tus integraciones que cargan teléfonos locales (por ejemplo, 10 dígitos) y agrega el código de país antes de enviarlos.

Respuesta (200 OK): el objeto actualizado.

Eliminar empleado

DELETE {{base_url}}/api/companies/v1/victims/{id}

Respuesta (204 No Content): sin body. El colaborador queda como inactivo (soft delete) y deja de aparecer en el listado por defecto (filter[status]=active).

Eventos de un empleado

GET {{base_url}}/api/companies/v1/victims/{id}/events

Devuelve el historial de eventos de campaña del colaborador, ordenado por fecha descendente.

Respuesta (200 OK)

Array plano (sin paginación):

[
  {
    "id": 501,
    "date_time": "2026-05-12 09:31:00",
    "type": "Clicked Link",
    "campaign_name": "Campaña Q2 - Phishing bancario",
    "campaign_id": 33
  }
]

Tipos de evento posibles: Email Sent, Failed, Clicked Link, Email Reported, Email Opened, Credential Harvesting, File Open, Download, Reported, Impersonated.

404 Not Found si la víctima no existe o no pertenece a tu compañía.

Errores comunes

Código	Causa	Body
`401`	Falta el header `X-API-KEY`	`{ "error": "API Key required" }`
`403`	API Key inexistente o revocada	`{ "error": "Invalid API Key" }`
`404`	El recurso no existe o pertenece a otra compañía	—
`422`	Error de validación (email duplicado, campo faltante, valor fuera de enum, teléfono inválido…)	`{ "messages": ["..."], "code": 422 }`
`422`	`phone_number` sin código de país	mismo formato; el mensaje dice que falta el código de país y da el ejemplo `+5491122334455`
`422`	`phone_number` con código de país que no corresponde a un número válido	mismo formato; el mensaje dice que el número no es válido para el país que declara
`409`	Cupo de licencias agotado (solo Crear)	`{ "messages": ["..."], "code": 409, "error_code": "victim_license_limit_reached", "licenses": N, "active_victims": N }`

Ejemplo cURL

curl -X POST https://api.whalemate.io/api/companies/v1/victims \
  -H "X-API-KEY: tu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "Ana",
    "last_name": "Gómez",
    "country": "Argentina",
    "language": "es",
    "position": "Contadora",
    "department": "Finanzas",
    "booster": "high"
  }'

❓ Preguntas frecuentes

¿Dónde consigo mi API Key?

En Configuración → Integraciones → tarjeta Claves API → Claves Activas. Ahí se generan, se listan y se revocan.

¿Qué pasa si elimino una víctima por error?

El borrado es lógico (soft delete): la víctima pasa a estar inactiva pero no se pierde. Podés listarla de nuevo con filter[status]=inactive o all, y volver a crearla/activarla según tu flujo.

¿Puedo crear víctimas en lote (batch)?

El endpoint actual procesa una víctima por solicitud. Si el registro en lote es prioritario para tu organización, podés solicitarlo en roadmap.whalemate.com/roadmap.

¿Cómo asigno una víctima a un grupo desde la API?

¿Qué significa el campo booster?

Es el nivel de exposición/atención que la víctima recibe en las simulaciones (low, normal, high, critical). Afecta la frecuencia y dificultad de las campañas que le llegan.

Me llega un 422 al crear un empleado con teléfono, y antes funcionaba.

Revisa que phone_number empiece con + o 00 y tenga el código de país. Desde el 1-oct-2026 un número local sin código de país se rechaza.

¿Puedo mandar el teléfono con espacios o guiones?

Sí, se limpian y se guarda sin esos símbolos.

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

API de Empleados - Whalemate Centro de ayuda | Productlane