1. Partner API v2
  2. Resources
  3. Phishing

Phishing

Simulation results, summaries, and the templates a client's simulations use.
5 endpointsScope readPhishingResultPhishingSummaryPhishingTemplate
GET/v2/users/{user_id}/phishing

List a user's phishing simulation resultsLink to this endpoint

RequiresreadscopeCursor-paginatedReturns Page of PhishingResult

Path parameters

user_idstringRequired

User id (the user's INFIMA id).

Query parametersall optional unless marked

sincestring (date-time)

Only records at or after this time (RFC 3339).

untilstring (date-time)

Only records before this time (RFC 3339).

statusstring

The furthest a simulation got. Statuses are ordered; reported is the good outcome.

One ofsentopenedclickedreportedcredentials_submittedattachment_opened
limitinteger

Default 100min 1 · max 500

cursorstring

Opaque cursor from the previous page's page.next_cursor.

curl "https://app.infimasecapis.com/v2/users/b7e1c0d2-44aa-5f9e-8c33-1a2b3c4d5e6f/phishing" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectPage of PhishingResult
dataarray of PhishingResult
Show item properties(14)
idstring

The result's id; the result_id returned by POST /clients/{client_id}/phishing/sends.

user_idstring
client_idstring
templateobject
Show properties(3)
idstring
namestring
categorystring
statusstring

The furthest a simulation got. Statuses are ordered; reported is the good outcome.

One ofsentopenedclickedreportedcredentials_submittedattachment_opened
sent_atstring (date-time)
opened_atstring (date-time)Nullable
clicked_atstring (date-time)Nullable
reported_atstring (date-time)Nullable
credentials_submitted_atstring (date-time)Nullable
attachment_opened_atstring (date-time)Nullable
originstringNullable

How the send started: scheduled by the client's automatic simulation schedule, on_demand by an admin or an API call choosing the users, experiment as part of a phishing experiment. Null for older sends outside an experiment, from before INFIMA recorded how a send started. Open enum: new values may be added.

One ofscheduledon_demandexperiment
remediationobjectNullable

Present when a click triggered behavior training.

Show properties(2)
course_idstring
statusstring

upcoming = start date in the future; open = started, not overdue; overdue = not completed by the end of the due date (it is overdue from the next day, UTC), except that a phishing-remediation (behavior) assignment is only overdue while the client requires that training and is otherwise open; completed = passed.

One ofupcomingopenoverduecompleted
updated_atstring (date-time)
pageobject
Show properties(2)
next_cursorstringNullable

Pass as cursor to fetch the next page. Null on the last page.

has_moreboolean
GET/v2/clients/{client_id}/phishing/summary

Get a client's phishing summaryLink to this endpoint

RequiresreadscopeReturns PhishingSummary

Counts and rates for a window. Use window=30d for a monthly report, 365d for a trailing year.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Query parametersall optional unless marked

windowstring
One of30d90d365dall

Default "90d"

curl "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/phishing/summary" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectPhishingSummary
client_idstring
windowstring
sentinteger
openedinteger
clickedinteger
reportedinteger
credentials_submittedinteger
attachments_openedinteger
click_ratenumber (float)
report_ratenumber (float)
users_targetedinteger
repeat_clickersinteger

Users who clicked more than once in the window.

computed_atstring (date-time)
GET/v2/clients/{client_id}/phishing/results

List phishing simulation resultsLink to this endpoint

RequiresreadscopeCursor-paginatedReturns Page of PhishingResult

One record per simulated email sent to a user in the client, with its current outcome. For an event feed, poll with updated_since: a record's updated_at changes each time its status advances (opened, clicked, reported).

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Query parametersall optional unless marked

sincestring (date-time)

Only records at or after this time (RFC 3339).

untilstring (date-time)

Only records before this time (RFC 3339).

updated_sincestring (date-time)

Only objects whose updated_at is at or after this time. Use it for delta syncs.

statusstring

Comma-separated statuses.

user_idstring
limitinteger

Default 100min 1 · max 500

cursorstring

Opaque cursor from the previous page's page.next_cursor.

curl "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/phishing/results" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectPage of PhishingResult
dataarray of PhishingResult
Show item properties(14)
idstring

The result's id; the result_id returned by POST /clients/{client_id}/phishing/sends.

user_idstring
client_idstring
templateobject
Show properties(3)
idstring
namestring
categorystring
statusstring

The furthest a simulation got. Statuses are ordered; reported is the good outcome.

One ofsentopenedclickedreportedcredentials_submittedattachment_opened
sent_atstring (date-time)
opened_atstring (date-time)Nullable
clicked_atstring (date-time)Nullable
reported_atstring (date-time)Nullable
credentials_submitted_atstring (date-time)Nullable
attachment_opened_atstring (date-time)Nullable
originstringNullable

How the send started: scheduled by the client's automatic simulation schedule, on_demand by an admin or an API call choosing the users, experiment as part of a phishing experiment. Null for older sends outside an experiment, from before INFIMA recorded how a send started. Open enum: new values may be added.

One ofscheduledon_demandexperiment
remediationobjectNullable

Present when a click triggered behavior training.

Show properties(2)
course_idstring
statusstring

upcoming = start date in the future; open = started, not overdue; overdue = not completed by the end of the due date (it is overdue from the next day, UTC), except that a phishing-remediation (behavior) assignment is only overdue while the client requires that training and is otherwise open; completed = passed.

One ofupcomingopenoverduecompleted
updated_atstring (date-time)
pageobject
Show properties(2)
next_cursorstringNullable

Pass as cursor to fetch the next page. Null on the last page.

has_moreboolean
GET/v2/clients/{client_id}/phishing/templates

List phishing templates enabled for a clientLink to this endpoint

RequiresreadscopeCursor-paginatedReturns Page of PhishingTemplate

The templates the client's users can receive, so you can pick one for an on-demand send. Content is not included.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Query parametersall optional unless marked

categorystring
localestring
One ofenesfr-ca
limitinteger

Default 100min 1 · max 500

cursorstring

Opaque cursor from the previous page's page.next_cursor.

curl "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/phishing/templates" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectPage of PhishingTemplate
dataarray of PhishingTemplate
Show item properties(7)
idstring

The template's id, shared by its translations. A client's own templates without one have no id.

namestring
subjectstring
categorystring
localestring
One ofenesfr-ca
difficultystringNullable
One ofeasymediumhard
ownerstring
One ofinfimapartnerclient
pageobject
Show properties(2)
next_cursorstringNullable

Pass as cursor to fetch the next page. Null on the last page.

has_moreboolean
POST/v2/clients/{client_id}/phishing/sends

Send an on-demand phishing simulationLink to this endpoint

Requireswritescope

Queues a simulation to up to 500 of the client's users, the way an admin's on-demand send from the dashboard does. Every user gets the template in their own language (falling back to English when it has no translation), and templates limited to other regions are never sent.

template_id
is a template id from GET /clients/{client_id}/phishing/templates and must be enabled for the client. Omit it to let INFIMA pick, per user, an enabled template the user has not received before.
category
(2.2) narrows that pick to one category: the category value the templates in GET /clients/{client_id}/phishing/templates carry. At least one enabled template in it must reach the client. Not together with template_id.
send_at
schedules the send, up to 30 days ahead. Omit it, or pass a time in the past, to send now.
send_until
(2.2) spreads the send: each user gets their own random time between send_at (or now, when send_at is omitted) and send_until, so the emails do not all land in the same minute. It must be after send_at and at most 30 days ahead; each send's own time is in the response.

The request is all or nothing on validation: if any user_ids entry is not a user of this client, template_id is not enabled, category has no enabled template, or both are sent, the response is 400 listing every problem and nothing is sent. Users who exist but cannot be sent to are returned in skipped with a reason instead: inactive (the user is inactive), phishing_disabled (phishing simulations are turned off for the user's group), no_template (no enabled template in the user's language or region), or queue_error (the send could not be queued, whether the database or the job queue refused it; retry those users).

Each queued send has a result_id: the id the result carries in GET /clients/{client_id}/phishing/results and GET /users/{user_id}/phishing once the email has gone out, with origin on_demand.

Send an Idempotency-Key. Every successful call sends real simulation emails, and a call without a key that is retried (after a timeout, say) sends them again. With a key, a retry within 24 hours returns the original 202 and sends nothing.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Request bodyapplication/json

user_idsarray of stringRequired

Ids of the client's users. Each may appear once.

max 500 items

template_idstring

A template id enabled for the client. Omit to let INFIMA pick per user.

categorystring

Pick per user from this category of the client's enabled templates. Not with template_id.

send_atstring (date-time)

When to send, at most 30 days ahead. Omit to send now.

send_untilstring (date-time)

The end of a window that starts at send_at (or now); each user is sent at their own random time inside it. At most 30 days ahead.

curl -X POST "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/phishing/sends" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": [
      "b7e1c0d2-44aa-5f9e-8c33-1a2b3c4d5e6f"
    ],
    "template_id": "credential/m365-password-expiry",
    "category": "credential_harvest",
    "send_at": "2026-09-18T14:03:00Z",
    "send_until": "2026-09-18T14:03:00Z"
  }'
Response objectObject
sendsarray of object
Show item properties(4)
user_idstring
result_idstring
template_idstringNullable

The template sent, in the user's language. Null for a client's own template that has no id.

send_atstring (date-time)

When this user's email goes out; inside the window when send_until was given.

skippedarray of object

Users of the client who were not sent to, and why.

Show item properties(2)
user_idstring
reasonstring

Open enum; new reasons may be added.

One ofinactivephishing_disabledno_templatequeue_error
Errors400Invalid request403The key cannot perform this action or reach this client404Not found within the key's access409The object already existsError envelope →
Coming in 2.x1 more Phishing operation is specified for a later 2.x release.See the roadmap