API Documentation

The CanIPhish Public API (v3) lets you drive your tenant programmatically. You can read reporting and intelligence data — campaign results, human-risk scores, dark-web breaches, domain supply-chain posture and the tenants you can access — and manage configuration by creating, updating, deleting and duplicating campaigns, employee lists, content-library items (phishing emails, sender IDs, phishing websites, voice-phishing templates and training modules) and platform settings.

This article is a practical overview. For the complete, always-current reference — every endpoint, its parameters, request/response schemas and a “try it” console — see the interactive API reference at api-docs.caniphish.com.

Base URL

All endpoints live under:

https://api.caniphish.com/api/v3

Authentication

Every request must include two headers:

The user identified by X-Email-Address must have access to the tenantID supplied in the request body. Each successful call consumes one unit of your tenant’s API quota.

Keep your API key secret. It grants the same access the associated user has. Store it in a secrets manager or environment variable — never commit it to source control or expose it in client-side code.

Access & authorization

Access depends on the endpoint type:

• Read & reporting endpoints (tenant lookups, campaign/training reporting, employee information, dark-web data, the domain supply-chain scan) are available to any authenticated user with access to the tenant. Some depend on the relevant feature being enabled (for example, dark-web monitoring).
• Management / write endpoints are gated. A request is rejected with 403 unless both of the following hold:
  1. Role — the requesting user is a Platform Admin (AD) or Platform Super Admin (SA) on the tenant.
  2. Entitlement — the tenant has an active Professional or Enterprise subscription, an active Enterprise trial, or is a partner-managed tenant billed under a master subscription whose master tenant holds an Enterprise subscription.

You can check both conditions up front by calling get-entitlements, which reports whether the caller is an admin and whether the tenant is write- and Enterprise-entitled — useful for a client that wants to preflight before attempting a gated call.

Request & response conventions

• All endpoints are POST.
• Most requests take a JSON body that includes a tenantID. A couple of read endpoints (the tenant-ID lookups) need only the authentication headers.
• Success responses are 200 with a JSON object.
• Authentication / validation errors return 400 with { "Error": "message" }.
• Authorization (role / subscription) failures return 403 with { "Error": "message" }.
• Errors also include a machine-readable ErrorCode — one of AUTH_ERROR, QUOTA_EXCEEDED, TENANT_ACCESS_DENIED, PERMISSION_DENIED, ENTITLEMENT_REQUIRED, or MISSING_REQUIRED_FIELD — so you can branch on it in code rather than parsing messages.

Quota & rate tracking

Each successful call uses one API-quota unit. Every response carries three headers so you can track consumption in real time:

X-API-Quota-Limit       your tenant's quota
X-API-Quota-Used        units consumed so far
X-API-Quota-Remaining   units left

Call get-entitlements at any time to read your current plan and quota.

Working with tenants

Most actions target a specific tenant, passed as tenantID in the request body. If your API key can reach more than one tenant (for example, an MSP or partner account), first call the tenant-lookup endpoint (get-tenant-access) — which needs only the auth headers — to retrieve the tenant IDs you can access, then supply the appropriate tenantID on each subsequent call.

Quickstart

1. Find the tenants you can access (headers only):

curl -X POST https://api.caniphish.com/api/v3/account/get-tenant-access \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Email-Address: you@example.com"

2. Check your entitlements and quota:

curl -X POST https://api.caniphish.com/api/v3/account/get-entitlements \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Email-Address: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{ "tenantID": "YOUR_TENANT_ID" }'

3. List your campaigns:

curl -X POST https://api.caniphish.com/api/v3/campaigns/list-campaigns \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Email-Address: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{ "tenantID": "YOUR_TENANT_ID" }'

What you can manage

The API is organised into these areas (see the interactive reference for the full endpoint list in each):

Common workflows

Chain endpoints in order to complete an end-to-end task:

• Run a phishing simulation — create-employee-list → create-sender-id → create-phishing-email → create-phishing-website → create-phishing-campaign; later pull results with get-campaign-results.
• Assign training — create-employee-list → (optional) create-training-module → create-training-campaign; track with get-training-results and get-training-certificate.
• Combined phishing + training — as above, but with create-phishing-training-campaign.
• Onboard employees from a directory — list-directory-integrations → get-directory-groups → create-employee-list (with listSource: "directory").
• Authorise a sending domain — request-domain-verification → verify-domain → lock-domain; the domain can then back sender IDs and phish reporting.
• Compliance reporting — generate-report for an on-demand PDF, or update-scheduled-reports for recurring delivery (recipients must be on verified domains).
• Event-driven integration — update-webhook with an HTTPS endpoint to receive phishing/training events.
• Preflight what you can do — get-entitlements before attempting gated calls.

Error handling

Handle failures by status code and ErrorCode:

Best practices

• Preflight with get-entitlements before write operations to avoid predictable 403s.
• Watch the quota headers on every response and back off before you hit the limit.
• Use returned names in follow-up calls. Some resources (for example campaign names) are sanitised on save — use the value returned in the response, not the string you sent, for later get/update/delete calls.
• Verify domains before using them for sender IDs, phish reporting, or scheduled-report recipients.
• Secure your key and rotate it if it may have been exposed.

Need help?

The full, interactive reference — with every endpoint, schema and a live “try it” console — is at api-docs.caniphish.com. If you get stuck, contact CanIPhish support with the endpoint, request body (with your API key removed) and the Error/ErrorCode you received, and we’ll help you resolve it.