API reference

AfriPhish exposes a REST API under /api/v1. Programmatic API access requires the Pro plan or higher.

Base URL — https://api.afriphish.com/api/v1 (your deployment may differ). Interactive OpenAPI docs are served at /docs on the backend.

Authentication

The API uses JWT bearer tokens. Obtain one by logging in:

curl -X POST https://api.afriphish.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "admin@yourcompany.com", "password": "••••••••" }'

{ "access_token": "eyJ…", "refresh_token": "eyJ…" }

Send the access token on every request:

curl https://api.afriphish.com/api/v1/organizations/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Access tokens are short-lived (15 min). Exchange a refresh token for a new pair at POST /auth/refresh.

Common endpoints

Method & path	Description
`GET /plans`	Public tier catalogue
`GET /organizations/me`	Your organisation
`GET /organizations/me/entitlements`	Live plan, seats, features, trial
`POST /organizations/me/logo`	Upload/replace the org logo
`GET /users`	List users
`POST /users/invite`	Invite a user
`GET /users/roles`	Assignable role catalogue
`GET /phishing/campaigns`	List campaigns
`POST /phishing/campaigns`	Create a campaign
`GET /training/modules`	List training modules
`GET /policies`	List policies
`GET /policies/{id}/roster`	Signature roster (signed / unsigned)
`POST /policies/{id}/notify`	Distribute a policy to sign
`GET /interventions/rules`	Coaching rules
`GET /reports/catalogue`	Available reports
`GET /reports/download/{key}`	Export a report (`?format=csv\|json\|pdf\|html`)
`GET /legal/documents`	Legal document templates (DPA / Terms / Privacy)

Errors

Standard HTTP status codes. A few worth knowing:

401 Unauthorized — missing/expired token.
402 Payment Required — your plan doesn't include this feature, or your trial has expired. Upgrade to unlock. See Plans.
403 Forbidden — your role isn't permitted, a seat cap was hit, or the organisation is deactivated.

Error bodies are JSON:

{ "detail": "Your plan does not include this feature. Upgrade to unlock it." }

Rate limits

Endpoints are rate-limited per category (auth, tracking, default). If you exceed a limit you'll receive 429 Too Many Requests; back off and retry.

Questions about the API? Email sales@afriphish.com and we'll connect you with an engineer.