Developers v2.2.0

Partner API v2

Version 2 of the INFIMA Partner API gives partners, their clients' IT teams, and the vendors they work with read access to everything the INFIMA dashboard shows: clients, users, human risk, training, phishing, framework compliance, policies, Dark Web Monitoring, reports, and directory sync.

2.1 adds writes. create and update clients and users, manage collections, and send on-demand phishing simulations. Further writes and webhooks are listed under Coming in 2.x so you can plan for them; they return 404 until they ship.

Get an API keyDownload OpenAPI spec

v1 (/v1) keeps working unchanged for existing integrations. v1 reference (being retired)

GET/v2/clients200
{
  "data": [
    {
      "id": "3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10",
      "name": "Acme Manufacturing",
      "risk": {
        "average_score": 742,
        "grade": "B",
        "high_risk_users": 7
      },
      "frameworks": [
        "hipaa",
        "nist-csf"
      ]
    }
  ],
  "page": {
    "next_cursor": "eyJ0IjoiMjAy…",
    "has_more": true
  }
}
41
Endpoints
13
Resources
read
Scope needed

Quickstart

From key to client data in three requests

Everything below runs against production with a read-only key.

  1. 1

    Get an API key

    Send your API key in the X-API-Key header on every request. Keys are generated in the partner dashboard under Settings → Integrations → API Keys.

    How keys, scopes, and client access work

    Settings → Integrations → API Keys

    Power BI nightly

    ak_prod_3f2a••••••••••••

    readAll clients
    X-API-Key: $INFIMA_API_KEY
  2. 2

    Make your first request

    Call GET /v2/partner/api-key. Returns the title, scopes, and client access of the key used to make this request.

    Describe the calling key

    curl "https://app.infimasecapis.com/v2/partner/api-key" \
  -H "X-API-Key: $INFIMA_API_KEY"
  3. 3

    Page through your clients

    Every list accepts limit (default 100, max 500) and cursor. The response carries data (the page) and page (next_cursor, has_more). Pass next_cursor back as cursor to get the next page.

    Pagination & filtering

    curl "https://app.infimasecapis.com/v2/clients?limit=100" \
  -H "X-API-Key: $INFIMA_API_KEY"

# Then pass page.next_cursor back as cursor until has_more is false
curl "https://app.infimasecapis.com/v2/clients?limit=100&cursor=$NEXT_CURSOR" \
  -H "X-API-Key: $INFIMA_API_KEY"

API reference

Resources

41 read endpoints across 13 resources, from your partner account down to a single user’s training and exposures.

Partner3 endpoints

Your partner account, its admins, and the key you are calling with.

  • GET/v2/partner
  • GET/v2/partner/admins
  • GET/v2/partner/api-key
Open reference
Clients5 endpoints

The organizations you manage. A client is a tenant in the INFIMA dashboard.

  • GET/v2/clients
  • POST/v2/clients
  • GET/v2/clients/{client_id}
+2 more · Open reference
Users4 endpoints

The people enrolled in a client's program.

  • GET/v2/clients/{client_id}/users
  • POST/v2/clients/{client_id}/users
  • GET/v2/users/{user_id}
+1 more · Open reference
Risk2 endpoints

Human risk score, grade, and the signals behind them.

  • GET/v2/users/{user_id}/risk
  • GET/v2/clients/{client_id}/risk
Open reference
Training3 endpoints

Curriculum, course catalog, and course assignments.

  • GET/v2/users/{user_id}/training
  • GET/v2/courses
  • GET/v2/clients/{client_id}/training/curriculum
Open reference
Collections7 endpoints

Admin-managed groups of users used as audiences for training, frameworks, and policies.

  • GET/v2/clients/{client_id}/collections
  • POST/v2/clients/{client_id}/collections
  • GET/v2/clients/{client_id}/collections/{collection_id}
+4 more · Open reference
Frameworks2 endpoints

Compliance frameworks assigned to a client and how the client measures against them.

  • GET/v2/frameworks
  • GET/v2/clients/{client_id}/frameworks
Open reference
Phishing5 endpoints

Simulation results, summaries, and the templates a client's simulations use.

  • GET/v2/users/{user_id}/phishing
  • GET/v2/clients/{client_id}/phishing/summary
  • GET/v2/clients/{client_id}/phishing/results
+2 more · Open reference
Policies2 endpoints

Policy documents and sign-off tracking.

  • GET/v2/clients/{client_id}/policies
  • GET/v2/clients/{client_id}/policies/{policy_id}/acknowledgments
Open reference
Dark Web4 endpoints

Dark Web Monitoring exposure data. Requires the feature to be enabled for the client.

  • GET/v2/users/{user_id}/exposures
  • GET/v2/clients/{client_id}/dark-web
  • GET/v2/clients/{client_id}/dark-web/exposures
+1 more · Open reference
Reports2 endpoints

Generated PDF and Excel reports in the client's archive.

  • GET/v2/clients/{client_id}/reports
  • GET/v2/clients/{client_id}/reports/{report_id}
Open reference
Sync1 endpoint

Directory sync status for Microsoft 365 and Google Workspace.

  • GET/v2/clients/{client_id}/sync
Open reference
Emails1 endpoint

Emails INFIMA has sent to a user (welcome, reminders, phishing simulations).

  • GET/v2/users/{user_id}/emails
Open referenceComing in 2.xPlanned operations14 writes, webhooks, and feeds specified for later 2.x releases. Not available yet.See the roadmapOpenAPI 3.0 specThe contract these pages are built from. Generate a client, import it into Postman, or point an assistant at it.Download YAML

Guides

How the API behaves

The rules every endpoint follows, so one integration pattern covers the whole API.

AuthenticationSend your key in a header. Its client access and scopes decide what it can read.Pagination & filteringCursor pages, date-range and delta filters, and sorting on every list.ErrorsOne error envelope, the codes you can expect, and the request id to quote.Rate limitsPer-key and per-client budgets, the headers that report them, and caching.Ids & timestampsOpaque string ids for everything you can address; RFC 3339 timestamps in UTC.VersioningWhat can change within v2, and how deprecations are announced.

Coming from v1?

What changed from v1

  • One id scheme
  • Resources, not verbs
  • The platform's current shape
  • Cursor pagination, date-range and updated_since filters
  • Consistent errors, request ids, and rate-limit headers
Read the guide
Coming in 2.x

Coming in 2.x

Specified so you can plan for them; not available yet. Every operation here returns 404 until it ships. These are additive: nothing already shipped changes when they ship.

See all 14 planned operations

More writes

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

Webhooks

Push notifications when things change, instead of polling.

Reported emails

The feed of real emails your clients’ users report.

MCP server

This same API, exposed to AI assistants.