1. Partner API v2
  2. Roadmap
Coming in 2.x — not available in 2.0 (returns 404)

Coming in 2.x

Specified so you can plan for them; not available in 2.0. Every operation here returns 404 until it ships.
23 planned operations11 resources
WritesCreate clients and users, manage collections, assign courses and frameworks, and send on-demand phishing.
WebhooksPush notifications when things change, instead of polling.
Reported emailsThe feed of real emails your clients’ users report.
MCP serverThis same API, exposed to AI assistants.

These are additive: nothing in 2.0 changes when they ship.

Clients

3 plannedLive Clients endpoints
POST/v2/clients

Create a clientLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescopeReturns Client

Provisions a new client under your partner account. Requires a key with access to all clients. The client starts with the Security Awareness Foundations program, the same as one created in the dashboard, and appears in GET /clients immediately.

Request bodyapplication/json

namestringRequired
industrystring

Optional industry label used for benchmarking.

external_idstring

Your own identifier for this client (PSA company id, CRM id). Stored and returned as-is; not used for lookups yet.

curl -X POST "https://app.infimasecapis.com/v2/clients" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Manufacturing",
    "industry": "manufacturing",
    "external_id": "PSA-10482"
  }'
Response objectClient
idstring
namestring
industrystringNullable
external_idstringNullable
created_atstring (date-time)
updated_atstring (date-time)
usersobject
Show properties(2)
activeinteger
inactiveinteger
riskobject
Show properties(3)
average_scoreinteger
gradestring

Letter grade derived from the score. A is 800 and above, B 700, C 600, D 400, F below 400.

One ofABCDF
high_risk_usersinteger

Users graded D or F.

trainingobject
Show properties(2)
on_track_ratenumber (float)

Percentage of active users with no overdue course.

overdue_usersinteger
phishingobject
Show properties(2)
click_rate_90dnumber (float)
report_rate_90dnumber (float)
frameworksarray of string

Ids of frameworks assigned to the client.

featuresobject
Show properties(2)
dark_web_monitoringboolean
directory_syncstringNullable
One ofmicrosoftgoogle
Errors400Invalid request403The key cannot perform this action or reach this client409The object already existsError envelope →
PATCH/v2/clients/{client_id}

Update a clientLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescopeReturns Client

Rename a client or set its industry / external id. Archiving and deleting clients stay in the dashboard because they affect billing.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Request bodyapplication/json

namestring
industrystring
external_idstring
curl -X PATCH "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Manufacturing",
    "industry": "manufacturing",
    "external_id": "PSA-10482"
  }'
Response objectClient
idstring
namestring
industrystringNullable
external_idstringNullable
created_atstring (date-time)
updated_atstring (date-time)
usersobject
Show properties(2)
activeinteger
inactiveinteger
riskobject
Show properties(3)
average_scoreinteger
gradestring

Letter grade derived from the score. A is 800 and above, B 700, C 600, D 400, F below 400.

One ofABCDF
high_risk_usersinteger

Users graded D or F.

trainingobject
Show properties(2)
on_track_ratenumber (float)

Percentage of active users with no overdue course.

overdue_usersinteger
phishingobject
Show properties(2)
click_rate_90dnumber (float)
report_rate_90dnumber (float)
frameworksarray of string

Ids of frameworks assigned to the client.

featuresobject
Show properties(2)
dark_web_monitoringboolean
directory_syncstringNullable
One ofmicrosoftgoogle
Errors400Invalid request404Not found within the key's accessError envelope →
POST/v2/clients/{client_id}/admins/invites

Invite a client adminLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescope

Sends the standard admin invitation email for this client. Lets a PSA-driven onboarding flow hand the client their dashboard login without a manual step. The invite expires the same way a dashboard invite does.

Returns 202: Invitation queued

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Request bodyapplication/json

emailstring (email)Required
rolestring
One ofadminviewer

Default "admin"

curl -X POST "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/admins/invites" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "it-lead@acme-mfg.com",
    "role": "admin"
  }'
Response objectObject
emailstring
statusstring
One ofqueued
expires_atstring (date-time)
Errors400Invalid request409The object already existsError envelope →

Users

2 plannedLive Users endpoints
POST/v2/clients/{client_id}/users

Create a userLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescopeReturns User

Adds a single user to the client outside directory sync. The user lands in the client's Manual group, is classified into a risk role (or takes the one you send), and picks up any framework-required courses. No welcome email is sent unless you set send_welcome_email.

If the client uses directory sync, prefer letting sync create users; a manually created user with the same email is merged on the next sync.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Request bodyapplication/json · UserCreate

emailstring (email)Required
first_namestring
last_namestring
departmentstring
job_titlestring
manager_emailstring (email)
rolestring

Omit to let INFIMA classify from job title, department, and email.

One ofadminexecutivehrfinancestandard
preferred_languagestring
One ofenesfr-ca
collection_idsarray of string
send_welcome_emailboolean

Default false

curl -X POST "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/users" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "maria.lopez@acme-mfg.com",
    "first_name": "Maria",
    "last_name": "Lopez",
    "department": "Finance",
    "job_title": "Accounts Payable Specialist",
    "manager_email": "sam.ortiz@acme-mfg.com",
    "role": "admin",
    "preferred_language": "en",
    "collection_ids": [
      "6f1c2a7e-3b9d-4c1a-9e8f-0a1b2c3d4e5f"
    ],
    "send_welcome_email": false
  }'
Response objectUser
idstring
client_idstring
emailstring (email)
first_namestring
last_namestring
departmentstringNullable
job_titlestringNullable
manager_emailstring (email)Nullable
statusstring
One ofactiveinactive
rolestring

The role used to weight a user's risk signals.

One ofadminexecutivehrfinancestandard
preferred_languagestring
One ofenesfr-ca
sourcestring

Where the user record came from.

One ofmicrosoftgooglemanualapi
groupobjectNullable

The directory group or manual group the user belongs to.

Show properties(2)
idstring
namestring
riskobject
Show properties(2)
scoreinteger
gradestring

Letter grade derived from the score. A is 800 and above, B 700, C 600, D 400, F below 400.

One ofABCDF
trainingobject
Show properties(3)
on_trackboolean
overdue_countinteger
next_courseobjectNullable
Show properties(3)
course_idstring
titlestring
due_onstring (date)
created_atstring (date-time)
updated_atstring (date-time)
Errors400Invalid request409The object already existsError envelope →
PATCH/v2/users/{user_id}

Update a userLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescopeReturns UserDetail

Partial update. Fields you set through the API are marked as manual overrides so the next directory sync does not overwrite them, the same as editing in the dashboard.

Path parameters

user_idstringRequired

User id (the user's INFIMA id).

Request bodyapplication/json · UserUpdate

statusstring
One ofactiveinactive
first_namestring
last_namestring
departmentstring
job_titlestring
manager_emailstring (email)Nullable
rolestring

The role used to weight a user's risk signals.

One ofadminexecutivehrfinancestandard
preferred_languagestring
One ofenesfr-ca
curl -X PATCH "https://app.infimasecapis.com/v2/users/b7e1c0d2-44aa-5f9e-8c33-1a2b3c4d5e6f" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "first_name": "Maria",
    "last_name": "Lopez",
    "department": "Finance",
    "job_title": "Accounts Payable Specialist",
    "manager_email": "sam.ortiz@acme-mfg.com",
    "role": "admin",
    "preferred_language": "en"
  }'
Response objectUserDetail
idstring
client_idstring
emailstring (email)
first_namestring
last_namestring
departmentstringNullable
job_titlestringNullable
manager_emailstring (email)Nullable
statusstring
One ofactiveinactive
rolestring

The role used to weight a user's risk signals.

One ofadminexecutivehrfinancestandard
preferred_languagestring
One ofenesfr-ca
sourcestring

Where the user record came from.

One ofmicrosoftgooglemanualapi
groupobjectNullable

The directory group or manual group the user belongs to.

Show properties(2)
idstring
namestring
riskUserRisk
Show properties(7)
scoreinteger
gradestring

Letter grade derived from the score. A is 800 and above, B 700, C 600, D 400, F below 400.

One ofABCDF
baselineinteger

The starting score for the user's role before signals are applied.

rolestring

The role used to weight a user's risk signals.

One ofadminexecutivehrfinancestandard
talliesobject

Raw counts over the trailing 12 months. The score applies recency weighting internally.

Show properties(11)
courses_completedinteger
phishing_clicksinteger
phishing_reportsinteger
credential_submissionsinteger
attachments_openedinteger
real_phish_reportedinteger
password_breaches_activeinteger
password_breaches_resolvedinteger
pii_breachesinteger
basic_breachesinteger
dormant_on_trainingboolean
factorsarray of object

Each signal's signed contribution, role multiplier applied.

Show item properties(3)
keystring
labelstring
deltainteger
computed_atstring (date-time)
trainingobject
Show properties(3)
on_trackboolean
overdue_countinteger
next_courseobjectNullable
Show properties(3)
course_idstring
titlestring
due_onstring (date)
created_atstring (date-time)
updated_atstring (date-time)
collectionsarray of object
Show item properties(2)
idstring
namestring
dark_webobjectNullable

Null when Dark Web Monitoring is not enabled for the client.

Show properties(3)
unresolved_exposuresinteger
resolved_exposuresinteger
highest_severitystring

critical = passwords exposed; high = sensitive personal data; medium = basic account data; low = spam lists.

One ofcriticalhighmediumlow
Errors400Invalid request404Not found within the key's accessError envelope →

Training

1 plannedLive Training endpoints
POST/v2/clients/{client_id}/training/assignments

Assign a courseLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescope

Assign a course to the whole client, a collection, or specific users, with a due date. The use case we have in mind: a SOC or PSA workflow assigns targeted remediation after a real incident. Users who already completed the course within its renewal window are skipped and listed in the response.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Request bodyapplication/json

course_idstringRequired
audienceAudienceRequired

Who an action applies to. Exactly one of the shapes.

Show properties(3)
typestringRequired
One ofallcollectionusers
collection_idstring

Required when type is collection.

user_idsarray of string

Required when type is users.

due_onstring (date)
notifyboolean

Send the assignment email now.

Default true

curl -X POST "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/training/assignments" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "course_id": "phishing-fundamentals",
    "audience": {
      "type": "all",
      "collection_id": "6f1c2a7e-3b9d-4c1a-9e8f-0a1b2c3d4e5f",
      "user_ids": [
        "b7e1c0d2-44aa-5f9e-8c33-1a2b3c4d5e6f"
      ]
    },
    "due_on": "2026-10-31",
    "notify": true
  }'
Response objectObject
course_idstring
assigned_countinteger
skippedarray of object
Show item properties(2)
user_idstring
reasonstring
One ofalready_completedinactive
Errors400Invalid requestError envelope →

Collections

4 plannedLive Collections endpoints
POST/v2/clients/{client_id}/collections

Create a collectionLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescopeReturns Collection

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Request bodyapplication/json

namestringRequired
descriptionstring
curl -X POST "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/collections" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Finance team",
    "description": "Everyone who approves payments or vendor changes"
  }'
Response objectCollection
idstring
client_idstring
namestring
descriptionstringNullable
member_countinteger
created_bystring
One ofdashboardapi
created_atstring (date-time)
updated_atstring (date-time)
Errors409The object already existsError envelope →
DELETE/v2/clients/{client_id}/collections/{collection_id}

Delete a collectionLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescope

Removes the collection. Users are not affected; framework and policy assignments scoped to it stop applying.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

collection_idstringRequired

Collection id (the collection's INFIMA id).

curl -X DELETE "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/collections/6f1c2a7e-3b9d-4c1a-9e8f-0a1b2c3d4e5f" \
  -H "X-API-Key: $INFIMA_API_KEY"
Errors404Not found within the key's accessError envelope →
POST/v2/clients/{client_id}/collections/{collection_id}/members

Add membersLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescope

Adds one or more users. Users already in the collection are ignored, not errors.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

collection_idstringRequired

Collection id (the collection's INFIMA id).

Request bodyapplication/json

user_idsarray of stringRequired

max 500 items

curl -X POST "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/collections/6f1c2a7e-3b9d-4c1a-9e8f-0a1b2c3d4e5f/members" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": [
      "b7e1c0d2-44aa-5f9e-8c33-1a2b3c4d5e6f"
    ]
  }'
Response objectObject
added_countinteger
member_countinteger
Errors400Invalid requestError envelope →
DELETE/v2/clients/{client_id}/collections/{collection_id}/members/{user_id}

Remove a memberLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescope

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

collection_idstringRequired

Collection id (the collection's INFIMA id).

user_idstringRequired

User id (the user's INFIMA id).

curl -X DELETE "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/collections/6f1c2a7e-3b9d-4c1a-9e8f-0a1b2c3d4e5f/members/b7e1c0d2-44aa-5f9e-8c33-1a2b3c4d5e6f" \
  -H "X-API-Key: $INFIMA_API_KEY"
Errors404Not found within the key's accessError envelope →

Frameworks

2 plannedLive Frameworks endpoints
POST/v2/clients/{client_id}/frameworks

Assign a frameworkLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescope

Assigns a framework to the whole client or to a collection. Assigning a framework schedules its required courses for the audience, so this is a heavy action. Send dry_run: true first to see what would be scheduled without changing anything, the same preview the dashboard shows.

Returns 201: Assigned (or previewed when `dry_run` is true)

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Request bodyapplication/json

framework_idstringRequired
audienceAudience

Who an action applies to. Exactly one of the shapes.

Show properties(3)
typestringRequired
One ofallcollectionusers
collection_idstring

Required when type is collection.

user_idsarray of string

Required when type is users.

modulesobject

Which parts of the framework to enforce. All true by default except policies.

Show properties(4)
trainingboolean

Default true

phishingboolean

Default true

policiesboolean

Default false

reportingboolean

Default true

dry_runboolean

Default false

curl -X POST "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/frameworks" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "framework_id": "hipaa",
    "audience": {
      "type": "all",
      "collection_id": "6f1c2a7e-3b9d-4c1a-9e8f-0a1b2c3d4e5f",
      "user_ids": [
        "b7e1c0d2-44aa-5f9e-8c33-1a2b3c4d5e6f"
      ]
    },
    "modules": {
      "training": true,
      "phishing": true,
      "policies": false,
      "reporting": true
    },
    "dry_run": false
  }'
Response objectObject
dry_runboolean
assignmentFrameworkAssignment
Show properties(6)
idstring
frameworkobject
Show properties(3)
idstring
namestring
categorystring
audienceobject
Show properties(3)
typestring
One ofallgroupcollection
idstringNullable
namestringNullable
modulesobject
Show properties(4)
trainingboolean
phishingboolean
policiesboolean
reportingboolean
evaluationobject
Show properties(5)
metinteger
totalinteger
percentageinteger
requirementsarray of object
Show item properties(6)
keystring
namestring
metboolean
valuenumberNullable

The measured value where the requirement is numeric (for example completion percentage).

targetnumberNullable
detailstring
evaluated_atstring (date-time)
created_atstring (date-time)
courses_to_schedulearray of object
Show item properties(3)
course_idstring
titlestring
user_countinteger
Errors400Invalid request409The object already existsError envelope →
DELETE/v2/clients/{client_id}/frameworks/{assignment_id}

Remove a framework assignmentLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescope

Removes the assignment. Courses already completed stay on the users' records; courses not yet started are withdrawn.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

assignment_idstringRequired

Framework assignment id, as returned in the client's framework list.

curl -X DELETE "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/frameworks/5e6f7a8b-9c0d-4e1f-9a2b-3c4d5e6f7a8b" \
  -H "X-API-Key: $INFIMA_API_KEY"
Errors404Not found within the key's accessError envelope →

Phishing

2 plannedLive Phishing endpoints
POST/v2/clients/{client_id}/phishing/sends

Send an on-demand phishing simulationLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescope

Schedules a simulation to one or more users. Omit template_id to let INFIMA pick one the user has not seen, in the user's language, respecting the client's category settings. Omit send_at to send now. Each queued send returns a result id you can follow in GET /clients/{client_id}/phishing/results.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Request bodyapplication/json

user_idsarray of stringRequired

max 100 items

template_idstring
send_atstring (date-time)
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",
    "send_at": "2026-09-18T14:03:00Z"
  }'
Response objectObject
sendsarray of object
Show item properties(4)
user_idstring
result_idstring
template_idstring
send_atstring (date-time)
Errors400Invalid requestError envelope →
GET/v2/clients/{client_id}/phishing/reported

List real emails users reportedLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirereadscopeCursor-paginatedReturns Page of ReportedEmail

Emails users flagged with the Report Phishing button that were not simulations, with the triage outcome. This is the feed a SOC or PSA would want for ticketing. Fields marked draft depend on the triage data the client's mailbox integration provides.

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).

classificationstring

Triage outcome for a reported real email. Draft; depends on the mailbox integration.

One ofphishingspamsafepending
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/reported" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectPage of ReportedEmail
dataarray of ReportedEmail
Show item properties(9)
idstring
user_idstring
client_idstring
reported_atstring (date-time)
subjectstring
senderstring (email)
classificationstring

Triage outcome for a reported real email. Draft; depends on the mailbox integration.

One ofphishingspamsafepending
classified_atstring (date-time)Nullable
mailbox_actionstringNullable

Draft. What the mailbox integration did with the message.

One ofnonemoved_to_junkdeleted
pageobject
Show properties(2)
next_cursorstringNullable

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

has_moreboolean

Policies

1 plannedLive Policies endpoints
POST/v2/clients/{client_id}/policies/{policy_id}/reminders

Remind unsigned usersLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescope

Sends the standard reminder to everyone who has not signed. Limited to once per policy per day.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

policy_idstringRequired

Policy id (the policy's INFIMA id).

curl -X POST "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/policies/2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e/reminders" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectObject
recipient_countinteger
Errors429Too many requestsError envelope →

Dark Web

1 plannedLive Dark Web endpoints
POST/v2/users/{user_id}/exposures/{breach_name}/resolve

Mark an exposure resolvedLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescopeReturns Exposure

Records that the exposure has been handled (password rotated, user notified). Lets a ticketing workflow close the loop without opening the dashboard. Resolving removes the exposure's weight from the user's risk score.

Path parameters

user_idstringRequired

User id (the user's INFIMA id).

breach_namestringRequired

The breach's name, as returned in breach_name.

curl -X POST "https://app.infimasecapis.com/v2/users/b7e1c0d2-44aa-5f9e-8c33-1a2b3c4d5e6f/exposures/LinkedIn/resolve" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectExposure
user_idstring
breach_namestring
titlestring
domainstringNullable
breach_onstring (date)Nullable
severitystring

critical = passwords exposed; high = sensitive personal data; medium = basic account data; low = spam lists.

One ofcriticalhighmediumlow
data_classesarray of string
first_seen_atstring (date-time)
notified_atstring (date-time)Nullable
resolved_atstring (date-time)Nullable
Errors404Not found within the key's accessError envelope →

Reports

1 plannedLive Reports endpoints
POST/v2/clients/{client_id}/reports

Generate a reportLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescopeReturns Report

Queues a report and returns it with status: pending. Poll GET /clients/{client_id}/reports/{report_id} until status is ready, then use download_url. Lets a partner portal produce the monthly executive summary on demand. Limited to a handful per client per hour.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Request bodyapplication/json

typestringRequired

Open enum.

One ofexecutive_summaryrisk_overviewphishing_overviewtraining_overviewtraining_performanceemployee_historycourse_detailscompliancepolicypolicy_acknowledgmentdark_webmonthly_reporttraining_status_reportmanager_dept_training_reportphishing_performanceglobal_health_report
periodobject

Reporting window where the report type supports one.

Show properties(2)
start_onstring (date)
end_onstring (date)
formatstring
One ofpdfxlsx

Default "pdf"

curl -X POST "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/reports" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "executive_summary",
    "period": {
      "start_on": "2026-09-18",
      "end_on": "2026-09-18"
    },
    "format": "pdf"
  }'
Response objectReport
idstring
client_idstring
typestring

Open enum.

One ofexecutive_summaryrisk_overviewphishing_overviewtraining_overviewtraining_performanceemployee_historycourse_detailscompliancepolicypolicy_acknowledgmentdark_webmonthly_reporttraining_status_reportmanager_dept_training_reportphishing_performanceglobal_health_report
formatstring
One ofpdfxlsx
statusstring
One ofpendingreadyfailed
periodobjectNullable
Show properties(2)
start_onstring (date)
end_onstring (date)
download_urlstringNullable

Signed, valid 24 hours. Only on the detail call and only when status is ready.

created_atstring (date-time)
Errors400Invalid request429Too many requestsError envelope →

Sync

1 plannedLive Sync endpoints
POST/v2/clients/{client_id}/sync/runs

Run a directory sync nowLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescope

Queues a sync outside the schedule, for example right after you add users in the directory. Limited to one per client per hour.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

curl -X POST "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/sync/runs" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectObject
statusstring
One ofqueued
queued_atstring (date-time)
Errors409Sync is not configured for this client429Too many requestsError envelope →

Webhooks

5 plannedNew in 2.x
GET/v2/webhooks

List webhook subscriptionsLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirereadscopeCursor-paginatedReturns Page of Webhook

No parameters. Send the request with your API key.

curl "https://app.infimasecapis.com/v2/webhooks" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectPage of Webhook
dataarray of Webhook
Show item properties(8)
idstring
urlstring (uri)
eventsarray of string
Each one ofclient.createduser.createduser.updateduser.deactivatedphishing.result.updatedphishing.email.reportedtraining.assignment.completedtraining.assignment.overduepolicy.acknowledgeddark_web.exposure.foundsync.completedsync.failedreport.ready
client_idsarray of string
descriptionstringNullable
statusstring

disabled after 24 hours of failed deliveries.

One ofactivepauseddisabled
created_atstring (date-time)
last_delivery_atstring (date-time)Nullable
pageobject
Show properties(2)
next_cursorstringNullable

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

has_moreboolean
POST/v2/webhooks

Create a webhook subscriptionLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescopeReturns Webhook

Subscribes an HTTPS endpoint to events. The subscription inherits the key's client access; narrow it further with client_ids. Each delivery is a POST with a JSON WebhookEvent body and an X-INFIMA-Signature header (t=<unix ts>,v1=<hex HMAC-SHA256> over t + "." + body using the secret returned once at creation). Respond 2xx within 10 seconds; failures retry with backoff for 24 hours.

Proposed events:

eventfires when
client.createda client is provisioned
user.created, user.updated, user.deactivateda user record changes, including via directory sync
phishing.result.updateda simulation advances (opened, clicked, reported, credentials submitted, attachment opened)
phishing.email.reporteda user reports a real email
training.assignment.completeda user passes a course
training.assignment.overduean assignment passes its due date without completion
policy.acknowledgeda user signs a policy
dark_web.exposure.founda new exposure is detected for a user
sync.completed, sync.faileda directory sync run finishes
report.readya generated report is available

Returns 201: Created. `secret` is only returned here.

Request bodyapplication/json

urlstring (uri)Required
eventsarray of stringRequired
Each one ofclient.createduser.createduser.updateduser.deactivatedphishing.result.updatedphishing.email.reportedtraining.assignment.completedtraining.assignment.overduepolicy.acknowledgeddark_web.exposure.foundsync.completedsync.failedreport.ready
client_idsarray of string

Restrict to these clients. Omit for every client the key can access.

descriptionstring
curl -X POST "https://app.infimasecapis.com/v2/webhooks" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/infima",
    "events": [
      "client.created"
    ],
    "client_ids": [
      "3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10"
    ],
    "description": "Open a ticket when a user submits credentials"
  }'
Response objectWebhook
idstring
urlstring (uri)
eventsarray of string
Each one ofclient.createduser.createduser.updateduser.deactivatedphishing.result.updatedphishing.email.reportedtraining.assignment.completedtraining.assignment.overduepolicy.acknowledgeddark_web.exposure.foundsync.completedsync.failedreport.ready
client_idsarray of string
descriptionstringNullable
statusstring

disabled after 24 hours of failed deliveries.

One ofactivepauseddisabled
created_atstring (date-time)
last_delivery_atstring (date-time)Nullable
secretstring
GET/v2/webhooks/{webhook_id}

Get a webhook subscriptionLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirereadscopeReturns Webhook

Path parameters

webhook_idstringRequired

Webhook subscription id.

curl "https://app.infimasecapis.com/v2/webhooks/8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d1e" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectWebhook
idstring
urlstring (uri)
eventsarray of string
Each one ofclient.createduser.createduser.updateduser.deactivatedphishing.result.updatedphishing.email.reportedtraining.assignment.completedtraining.assignment.overduepolicy.acknowledgeddark_web.exposure.foundsync.completedsync.failedreport.ready
client_idsarray of string
descriptionstringNullable
statusstring

disabled after 24 hours of failed deliveries.

One ofactivepauseddisabled
created_atstring (date-time)
last_delivery_atstring (date-time)Nullable
Errors404Not found within the key's accessError envelope →
DELETE/v2/webhooks/{webhook_id}

Delete a webhook subscriptionLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescope

Path parameters

webhook_idstringRequired

Webhook subscription id.

curl -X DELETE "https://app.infimasecapis.com/v2/webhooks/8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d1e" \
  -H "X-API-Key: $INFIMA_API_KEY"
Errors404Not found within the key's accessError envelope →
POST/v2/webhooks/{webhook_id}/test

Send a test eventLink to this endpoint

Coming in 2.x — not available in 2.0 (returns 404)Will requirewritescope

Delivers a ping event to the endpoint and reports the response.

Returns 200: Delivery attempted

Path parameters

webhook_idstringRequired

Webhook subscription id.

curl -X POST "https://app.infimasecapis.com/v2/webhooks/8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d1e/test" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectObject
deliveredboolean
status_codeinteger
duration_msinteger