Employee API

Technical reference for managing employees (target collaborators) from external systems: list, create, update, delete, and view their campaign event history via the Whalemate API.

What is it for?

Manage employees (the target colleagues of your simulations) from your own systems: payroll, HRIS, sync scripts, etc.
Create, update, query, and delete employees without going through the Whalemate interface.
Query the campaign event history of an employee (opens, clicks, reports, compromised credentials, etc.).

How is it implemented?

Base URL:

All endpoints are under the prefix {{base_url}}/api/companies/v1.

To get the production host (base_url), contact your Whalemate representative or write to us through the support chat.

Authentication:

The API uses API Key authentication through the X-API-KEY header.

X-API-KEY: tu_api_key_de_empresa

You can generate or check your key from Configuración → Integraciones → card Claves API → Claves Activas. The details are in API Keys: how to generate, use, and revoke them.

The company is resolved automatically from the API Key: you don't send company_id in the body or the URL, and each request operates only on your company's victims.

Required headers:

Header	Value	Required
`X-API-KEY`	Your company API Key	✅ Yes
`Content-Type`	`application/json`	✅ Yes (on `POST`/`PUT`)
`Accept`	`application/json`	✅ Yes

Endpoints

List employees

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

Query params

Param	Type	Default	Description
`per_page`	integer	`20`	Number of results per page
`filter[name]`	string	-	Filters by first name (partial match)
`filter[last_name]`	string	-	Filters by last name (partial)
`filter[email]`	string	-	Filters by email (partial)
`filter[department]`	string	-	Filters by department (partial)
`filter[country]`	string	-	Filters by country (partial)
`filter[position]`	string	-	Filters by position (partial)
`filter[status]`	string	`active`	`active` (excludes deleted) \| `inactive` (deleted only) \| `all`

Example:

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

Response (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 }
}

View an employee

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

Response (200 OK)

Same object as in the list, without the data wrapper. Returns 404 if the id does not exist or does not belong to your company.

Create an employee

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

Body (JSON)

Field	Type	Required	Description
`email`	string	✅	Unique email of the employee
`first_name`	string	✅	First name
`last_name`	string	✅	Last name
`country`	string	✅	Country
`language`	string	✅	One of `es`, `pt`, `en`
`position`	string	✅	Position
`department`	string	✅	Department
`booster`	string	✅	One of `low`, `normal`, `high`, `critical`
`phone_number`	string	❌	Phone number with country code, with `+` (for example `+5491122334455`) or with `00` in front. Spaces, hyphens, dots, and parentheses are accepted and are removed before saving. A number without `+` or `00` is rejected with `422`: Whalemate does not guess the country. Valid landline numbers are accepted.
`personal_id`	string	❌	Personal identifier (DNI, employee ID, etc.)

Contract change (1-oct-2026): until that date phone_number accepted any text. From today, if you send it without a country code, the API responds 422. Check your integrations that load local phone numbers (for example, 10 digits) and add the country code before sending them.

Example

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"
}

Successful response (201 Created): the object of the created victim, with the same shape as in View a victim.

Update employee

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

Accepts the same fields as Create an employee. email, first_name, last_name, country, language, position, department and booster are required; phone_number and personal_id are optional. The email must remain unique, ignoring the employee itself.

Contract change (1-oct-2026): until that date phone_number accepted any text. From today, if you send it without a country code, the API responds 422. Check your integrations that load local phone numbers (for example, 10 digits) and add the country code before sending them.

Response (200 OK): the updated object.

Delete employee

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

Response (204 No Content): no body. The employee is left as inactive (soft delete) and no longer appears in the default list (filter[status]=active).

Events of an employee

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

Returns the campaign event history of the employee, sorted by date descending.

Response (200 OK)

Flat array (no pagination):

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

Possible event types: Email Sent, Failed, Clicked Link, Email Reported, Email Opened, Credential Harvesting, File Open, Download, Reported, Impersonated.

404 Not Found if the victim does not exist or does not belong to your company.

Common errors

Code	Cause	Body
`401`	Missing `X-API-KEY` header	`{ "error": "API Key required" }`
`403`	API Key does not exist or was revoked	`{ "error": "Invalid API Key" }`
`404`	The resource does not exist or belongs to another company	-
`422`	Validation error (duplicate email, missing field, value outside enum, invalid phone number…)	`{ "messages": ["..."], "code": 422 }`
`422`	`phone_number` without country code	same format; the message says the country code is missing and gives the example `+5491122334455`
`422`	`phone_number` with a country code that does not match a valid number	same format; the message says the number is not valid for the country it declares
`409`	License quota exhausted (Create only)	`{ "messages": ["..."], "code": 409, "error_code": "victim_license_limit_reached", "licenses": N, "active_victims": N }`

cURL example

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"
  }'

❓ Frequently asked questions

Where do I get my API Key?

In Configuración → Integraciones → card Claves API → Claves Activas. There they are generated, listed, and revoked.

What happens if I delete a victim by mistake?

The deletion is logical (soft delete): the victim becomes inactive but is not lost. You can list it again with filter[status]=inactive or all, and create or activate it again depending on your flow.

Can I create victims in bulk (batch)?

The current endpoint processes one victim per request. If bulk registration is a priority for your organization, you can request it at roadmap.whalemate.com/roadmap.

How do I assign a victim to a group from the API?

This endpoint does not manage groups directly; the groups field in the response is read-only. Group assignment is done from the platform or through the sync integrations (Google/Microsoft/Okta).

What does the field booster mean?

It is the level of exposure and attention the victim receives in simulations (low, normal, high, critical). It affects the frequency and difficulty of the campaigns that reach them.

I get a 422 when creating an employee with a phone number, and it used to work.

Check that phone_number starts with + or 00 and has the country code. Since 1-oct-2026 a local number without a country code is rejected.

Can I send the phone number with spaces or hyphens?

Yes, they are removed and the number is saved without those symbols.

Do you have feedback or want to request improvements? Let us know at roadmap.whalemate.com/roadmap

Employee API

Technical reference for managing employees (target collaborators) from external systems: list, create, update, delete, and view their campaign event history via the Whalemate API.

What is it for?

Manage employees (the target colleagues of your simulations) from your own systems: payroll, HRIS, sync scripts, etc.
Create, update, query, and delete employees without going through the Whalemate interface.
Query the campaign event history of an employee (opens, clicks, reports, compromised credentials, etc.).

How is it implemented?

Base URL:

All endpoints are under the prefix {{base_url}}/api/companies/v1.

To get the production host (base_url), contact your Whalemate representative or write to us through the support chat.

Authentication:

The API uses API Key authentication through the X-API-KEY header.

X-API-KEY: tu_api_key_de_empresa

You can generate or check your key from Configuración → Integraciones → card Claves API → Claves Activas. The details are in API Keys: how to generate, use, and revoke them.

The company is resolved automatically from the API Key: you don't send company_id in the body or the URL, and each request operates only on your company's victims.

Required headers:

Header	Value	Required
`X-API-KEY`	Your company API Key	✅ Yes
`Content-Type`	`application/json`	✅ Yes (on `POST`/`PUT`)
`Accept`	`application/json`	✅ Yes

Endpoints

List employees

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

Query params

Param	Type	Default	Description
`per_page`	integer	`20`	Number of results per page
`filter[name]`	string	-	Filters by first name (partial match)
`filter[last_name]`	string	-	Filters by last name (partial)
`filter[email]`	string	-	Filters by email (partial)
`filter[department]`	string	-	Filters by department (partial)
`filter[country]`	string	-	Filters by country (partial)
`filter[position]`	string	-	Filters by position (partial)
`filter[status]`	string	`active`	`active` (excludes deleted) \| `inactive` (deleted only) \| `all`

Example:

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

Response (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 }
}

View an employee

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

Response (200 OK)

Same object as in the list, without the data wrapper. Returns 404 if the id does not exist or does not belong to your company.

Create an employee

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

Body (JSON)

Field	Type	Required	Description
`email`	string	✅	Unique email of the employee
`first_name`	string	✅	First name
`last_name`	string	✅	Last name
`country`	string	✅	Country
`language`	string	✅	One of `es`, `pt`, `en`
`position`	string	✅	Position
`department`	string	✅	Department
`booster`	string	✅	One of `low`, `normal`, `high`, `critical`
`phone_number`	string	❌	Phone number with country code, with `+` (for example `+5491122334455`) or with `00` in front. Spaces, hyphens, dots, and parentheses are accepted and are removed before saving. A number without `+` or `00` is rejected with `422`: Whalemate does not guess the country. Valid landline numbers are accepted.
`personal_id`	string	❌	Personal identifier (DNI, employee ID, etc.)

Contract change (1-oct-2026): until that date phone_number accepted any text. From today, if you send it without a country code, the API responds 422. Check your integrations that load local phone numbers (for example, 10 digits) and add the country code before sending them.

Example

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"
}

Successful response (201 Created): the object of the created victim, with the same shape as in View a victim.

Update employee

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

Contract change (1-oct-2026): until that date phone_number accepted any text. From today, if you send it without a country code, the API responds 422. Check your integrations that load local phone numbers (for example, 10 digits) and add the country code before sending them.

Response (200 OK): the updated object.

Delete employee

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

Response (204 No Content): no body. The employee is left as inactive (soft delete) and no longer appears in the default list (filter[status]=active).

Events of an employee

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

Returns the campaign event history of the employee, sorted by date descending.

Response (200 OK)

Flat array (no pagination):

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

Possible event types: Email Sent, Failed, Clicked Link, Email Reported, Email Opened, Credential Harvesting, File Open, Download, Reported, Impersonated.

404 Not Found if the victim does not exist or does not belong to your company.

Common errors

Code	Cause	Body
`401`	Missing `X-API-KEY` header	`{ "error": "API Key required" }`
`403`	API Key does not exist or was revoked	`{ "error": "Invalid API Key" }`
`404`	The resource does not exist or belongs to another company	-
`422`	Validation error (duplicate email, missing field, value outside enum, invalid phone number…)	`{ "messages": ["..."], "code": 422 }`
`422`	`phone_number` without country code	same format; the message says the country code is missing and gives the example `+5491122334455`
`422`	`phone_number` with a country code that does not match a valid number	same format; the message says the number is not valid for the country it declares
`409`	License quota exhausted (Create only)	`{ "messages": ["..."], "code": 409, "error_code": "victim_license_limit_reached", "licenses": N, "active_victims": N }`

cURL example

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"
  }'

❓ Frequently asked questions

Where do I get my API Key?

In Configuración → Integraciones → card Claves API → Claves Activas. There they are generated, listed, and revoked.

What happens if I delete a victim by mistake?

Can I create victims in bulk (batch)?

The current endpoint processes one victim per request. If bulk registration is a priority for your organization, you can request it at roadmap.whalemate.com/roadmap.

How do I assign a victim to a group from the API?

This endpoint does not manage groups directly; the groups field in the response is read-only. Group assignment is done from the platform or through the sync integrations (Google/Microsoft/Okta).

What does the field booster mean?

It is the level of exposure and attention the victim receives in simulations (low, normal, high, critical). It affects the frequency and difficulty of the campaigns that reach them.

I get a 422 when creating an employee with a phone number, and it used to work.

Check that phone_number starts with + or 00 and has the country code. Since 1-oct-2026 a local number without a country code is rejected.

Can I send the phone number with spaces or hyphens?

Yes, they are removed and the number is saved without those symbols.

Do you have feedback or want to request improvements? Let us know at roadmap.whalemate.com/roadmap

Employee API - Whalemate Help Center | Productlane