Partner API v2
Roadmap

Coming in 2.x — not available yet (returns 404)

Coming in 2.x

Specified so you can plan for them; not available yet. Every operation here returns 404 until it ships.

14 planned operations9 resources

More writesAssign courses and frameworks, send policy reminders, generate reports, run a directory sync, resolve exposures, and invite admins.

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 already shipped changes when they ship.

Clients

1 plannedLive Clients endpoints

POST/v2/clients/{client_id}/admins/invites

Invite a client adminLink to this endpoint

Coming in 2.x — not available yet (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 objectObject3 properties

emailstring

statusstring

One ofqueued

expires_atstring (date-time)

Errors400Invalid request409The object already existsError 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 yet (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 objectObject3 properties

course_idstring

assigned_countinteger

skippedarray of object

Show item properties(2)

user_idstring

reasonstring

One ofalready_completedinactive

Errors400Invalid requestError envelope →

Frameworks

2 plannedLive Frameworks endpoints

POST/v2/clients/{client_id}/frameworks

Assign a frameworkLink to this endpoint

Coming in 2.x — not available yet (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 objectObject3 properties

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 yet (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

1 plannedLive Phishing endpoints

GET/v2/clients/{client_id}/phishing/reported

List real emails users reportedLink to this endpoint

Coming in 2.x — not available yet (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 ReportedEmail2 properties

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 yet (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 objectObject1 property

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 yet (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 objectExposure10 properties

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 yet (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 objectReport8 properties

idstring

client_idstring

typestring

Open enum.

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 yet (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 objectObject2 properties

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 yet (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 Webhook2 properties

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 yet (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:

event	fires when
`client.created`	a client is provisioned
`user.created`, `user.updated`, `user.deactivated`	a user record changes, including via directory sync
`phishing.result.updated`	a simulation advances (opened, clicked, reported, credentials submitted, attachment opened)
`phishing.email.reported`	a user reports a real email
`training.assignment.completed`	a user passes a course
`training.assignment.overdue`	an assignment passes its due date without completion
`policy.acknowledged`	a user signs a policy
`dark_web.exposure.found`	a new exposure is detected for a user
`sync.completed`, `sync.failed`	a directory sync run finishes
`report.ready`	a generated report is available

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

Request bodyapplication/json

urlstring (uri)Required

eventsarray of stringRequired

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 objectWebhook9 properties

idstring

urlstring (uri)

eventsarray of string

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 yet (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 objectWebhook8 properties

idstring

urlstring (uri)

eventsarray of string

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 yet (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 yet (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 objectObject3 properties

deliveredboolean

status_codeinteger

duration_msinteger