API Documentation

The Human Vector has a REST API for phishing simulation and security awareness training: read people, groups and results, run directory syncs, create and send campaigns, draft templates with AI, register webhooks, and, for MSPs, manage client organizations. The REST API is part of the Pro plan.

Base URL

https://thehumanvector.io/api/v1

Authentication

Every request carries an API key as a Bearer token. Create a key in the console: gear menu → API Keys → Create Key, choose its permissions, and copy it (it is shown once).

curl -H "Authorization: Bearer $THV_API_KEY" https://thehumanvector.io/api/v1/campaigns

Errors are JSON: {"error": "code", "message": "..."}. A missing or revoked key returns 401, a key without the needed permission 403, an organization not on Pro 403 plan_required, too many requests 429 with Retry-After.

Specification

The full OpenAPI 3.1 specification, with every endpoint, parameter and response: https://thehumanvector.io/openapi.yaml. Most API tools and AI assistants can load it directly.

Permissions (scopes)

Scope	Allows
`employees:read`	List people and their details.
`employees:write`	Add, update and disable people, run directory syncs.
`groups:read`	List groups and their members.
`campaigns:read`	Templates, campaigns and results.
`campaigns:write`	Create, schedule and send campaigns, draft templates.
`webhooks:read`	List webhook endpoints.
`webhooks:write`	Add and remove webhook endpoints.
`clients:read`	MSPs: list client organizations.
`clients:write`	MSPs: create client organizations.
`keys:read`	List this organization's keys.
`keys:write`	Create and revoke keys.

Endpoints

Endpoint	What it does
`GET /employees`	List people.
`GET /groups`	List groups.
`GET /templates`	List simulation templates.
`POST /templates/generate`	Draft a simulation template with AI (a person reviews it before use).
`GET /campaigns`, `POST /campaigns`	List and create campaigns.
`GET /campaigns/{id}`	One campaign.
`POST /campaigns/{id}/send`	Send a campaign now.
`POST /campaigns/{id}/schedule`	Schedule a campaign.
`GET /campaigns/{id}/stats`	Opens, clicks, submissions, reports and training.
`POST /directory/sync`	Sync people and groups from the connected directory.
`GET /clients`, `POST /clients`	MSPs: list and create client organizations.
`GET /webhooks`, `POST /webhooks`	List and register webhook endpoints for events such as clicks and reports.
`GET /api-keys`, `POST /api-keys`	List and create keys.

Paths are relative to the base URL. The specification is the complete, authoritative list.