Employees API - Whalemate Docs

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

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)

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

What is it for?

Manage employees (target collaborators for 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 a collaborator (opens, clicks, reports, compromised credentials, etc.).

How is it implemented?

Base URL:

All endpoints live 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 via the X-API-KEY header.

X-API-KEY: tu_api_key_de_empresa

You can generate or check your key from Settings → Integrations → API Keys card → Active Keys. Details are in API Keys: how to generate, use, and revoke them.

The company is automatically resolved from the API Key: you do not 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)