1. Partner API v2
  2. Resources
  3. Clients

Clients

The organizations you manage. A client is a tenant in the INFIMA dashboard.
18 endpointsScope readClientAdminWelcomeEmailSettingsClientBrandingOnboardingSelectionsReportPhishingButtonSettingsClientSettings
GET/v2/clients
RequiresreadscopeCursor-paginatedReturns Page of Client

Every client the key can access, with a summary of user counts, risk, training, phishing, and enabled features. Summaries are computed on request and cached for a few minutes; call this once per sync run, not once per user.

Query parametersall optional unless marked

idsstring

Comma-separated client ids to restrict the list to.

qstring

Case-insensitive match on client name.

updated_sincestring (date-time)

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

sortstring
One ofname-namecreated_at-created_atrisk_score-risk_score

Default "name"

limitinteger

Default 100min 1 · max 500

cursorstring

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

curl "https://app.infimasecapis.com/v2/clients" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectPage of Client
dataarray of Client
Show item properties(12)
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
pageobject
Show properties(2)
next_cursorstringNullable

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

has_moreboolean
POST/v2/clients
RequireswritescopeReturns Client

Provisions a new client under your partner account. Requires a key with access to all clients (403 otherwise). The client starts with the Security Awareness Foundations program, the same as one created in the dashboard, and appears in GET /clients immediately. Names are unique per partner, ignoring case: a name another active client already has returns 409. A partner account on trial with an agreement to accept also gets 409 until it activates in the dashboard. Send an Idempotency-Key so a retried request returns the client it already created.

Request bodyapplication/json

namestringRequired

max length 128

industrystring

Industry used for benchmarking. One of healthcare, legal, accounting, financial_services, real_estate, construction, manufacturing, professional_services, nonprofit, education, retail_hospitality, technology, government, other.

external_idstring

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

max length 255

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 →
GET/v2/clients/{client_id}
RequiresreadscopeReturns Client

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

curl "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10" \
  -H "X-API-Key: $INFIMA_API_KEY"
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
Errors404Not found within the key's accessError envelope →
PATCH/v2/clients/{client_id}
RequireswritescopeReturns Client

Rename a client or set its industry / external id. Only the fields you send change; send at least one. external_id set to null or "" clears it; industry cannot be cleared, only changed. Renaming to a name another active client of yours has returns 409. 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

max length 128

industrystring

One of the values listed on createClient.

external_idstringNullable

max length 255

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 request403The key cannot perform this action or reach this client404Not found within the key's access409The object already existsError envelope →
GET/v2/clients/{client_id}/admins
RequiresreadscopeCursor-paginatedReturns Page of Admin

Client-scoped dashboard admins for this client only.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Query parametersall optional unless marked

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/admins" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectPage of Admin
dataarray of Admin
Show item properties(8)
idstring
emailstring (email)
namestring
rolestring
One ofowneradminviewer
scopestring

Partner admins see every client; client admins see one.

One ofpartnerclient
client_idstringNullable

Set when scope is client.

last_login_atstring (date-time)Nullable
created_atstring (date-time)
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}/admins/invites
Requireswritescope

Sends the standard admin invitation email for this client, the dashboard's Invite admin. The invitee becomes an admin of this client only, as admin (Administrator) or viewer (read-only); never a partner admin, and never with billing access. The invite expires after 30 days like a dashboard invite; expires_at says when. Lets a PSA-driven onboarding flow hand the client their dashboard login without a manual step.

An address that already administers this client, or that has an open invite to it, returns 409. An admin of your other clients may be invited: redeeming the invite extends their access to this client.

Send an Idempotency-Key: a retried request replays the original 202 instead of sending a second invitation.

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 →
PATCH/v2/clients/{client_id}/admins/{admin_id}
RequireswritescopeReturns Admin

Sets a client admin's role, the dashboard's Edit role on the client's Admins page: admin (Administrator) or viewer (read-only). Only the role changes; which clients the admin can reach stays as it is, and billing access is never set from the API.

Only the client's own admins (scope: client in GET /clients/{client_id}/admins, invited to this client) can be changed here. An admin whose access you gave from your partner settings (a scoped admin) returns 409: change it there. An id that is not one of this client's admins returns 404. The response is the admin after the change.

Returns 200: Saved

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

admin_idstringRequired

Admin id (the admin's INFIMA id).

Request bodyapplication/json

rolestringRequired
One ofadminviewer
curl -X PATCH "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/admins/1c2d3e4f-5a6b-4c7d-8e9f-a0b1c2d3e4f5" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin"
  }'
Response objectAdmin
idstring
emailstring (email)
namestring
rolestring
One ofowneradminviewer
scopestring

Partner admins see every client; client admins see one.

One ofpartnerclient
client_idstringNullable

Set when scope is client.

last_login_atstring (date-time)Nullable
created_atstring (date-time)
Errors400Invalid request404Not found within the key's access409The object already existsError envelope →
DELETE/v2/clients/{client_id}/admins/{admin_id}
Requireswritescope

Removes the admin's access to this client, the dashboard's Remove on the client's Admins page. Their access to your other clients, if any, is unchanged. The same rules as changing the role apply: a scoped admin returns 409, an id that is not one of this client's admins 404.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

admin_idstringRequired

Admin id (the admin's INFIMA id).

curl -X DELETE "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/admins/1c2d3e4f-5a6b-4c7d-8e9f-a0b1c2d3e4f5" \
  -H "X-API-Key: $INFIMA_API_KEY"
Errors404Not found within the key's access409The object already existsError envelope →
GET/v2/clients/{client_id}/welcome-emails
RequiresreadscopeReturns WelcomeEmailSettings

The client's Welcome Email card on the dashboard's People page: whether new users get a welcome email, when it goes out, and how many are waiting. client_override is the client's own on/off (null when it follows your partner-wide setting); enabled is what applies. A new user's email waits delay_business_days business days after they were added, and nothing goes out before first_send_date.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

curl "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/welcome-emails" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectWelcomeEmailSettings
enabledboolean

Whether new users get a welcome email.

client_overridebooleanNullable

The client's own setting; null follows yours.

send_hourinteger

The UTC hour welcome emails go out.

send_hour_follows_partnerboolean

True when the client follows your setting and sends at your hour.

delay_business_daysinteger

Business days a new user waits for their email.

delay_overrideintegerNullable

The client's own delay; null follows yours.

first_send_datestring (date)Nullable

No welcome email goes out before this day.

new_users_sincestring (date-time)Nullable

Only users added after this are welcomed; null means every user.

last_sent_atstring (date-time)Nullable
due_countinteger

Users the next run would email.

scheduled_countinteger

Users still waiting out the delay.

next_scheduled_datestring (date)Nullable
PATCH/v2/clients/{client_id}/welcome-emails
RequireswritescopeReturns WelcomeEmailSettings

Changes only what you send; a field left out stays as it is. The dashboard's Save on the Welcome Email card.

  • client_override: true or false for the client's own setting, null to follow your partner-wide setting again.
  • send_hour (0 to 23, UTC): the hour the client's own schedule runs. It is used while client_override is true; a client that follows your setting sends at your partner-wide hour.
  • delay_business_days (0 to 30): business days a new user waits for their email; null follows your partner-wide delay.
  • first_send_date (YYYY-MM-DD): no welcome email goes out before this day; null removes the date.
  • include_existing: when this change first turns welcome emails on, true also welcomes the users the client already has; otherwise only users added from now on are welcomed, as in the dashboard. Ignored on any other change.

All fields are checked before anything is saved, so a 400 changes nothing. The response is the settings after the change.

Returns 200: Saved

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Request bodyapplication/json · WelcomeEmailSettingsUpdate

client_overridebooleanNullable
send_hourinteger

min 0 · max 23

delay_business_daysintegerNullable

min 0 · max 30

first_send_datestring (date)Nullable
include_existingboolean
curl -X PATCH "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/welcome-emails" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_override": true,
    "send_hour": 0,
    "delay_business_days": 0,
    "first_send_date": "2026-09-18",
    "include_existing": true
  }'
Response objectWelcomeEmailSettings
enabledboolean

Whether new users get a welcome email.

client_overridebooleanNullable

The client's own setting; null follows yours.

send_hourinteger

The UTC hour welcome emails go out.

send_hour_follows_partnerboolean

True when the client follows your setting and sends at your hour.

delay_business_daysinteger

Business days a new user waits for their email.

delay_overrideintegerNullable

The client's own delay; null follows yours.

first_send_datestring (date)Nullable

No welcome email goes out before this day.

new_users_sincestring (date-time)Nullable

Only users added after this are welcomed; null means every user.

last_sent_atstring (date-time)Nullable
due_countinteger

Users the next run would email.

scheduled_countinteger

Users still waiting out the delay.

next_scheduled_datestring (date)Nullable
Errors400Invalid requestError envelope →
POST/v2/clients/{client_id}/welcome-emails/sends
Requireswritescope

Sends the welcome emails that are due now instead of waiting for the next scheduled run, the dashboard's "Send now". Who is due follows the client's settings exactly as the schedule does (the delay, users added before welcome emails were turned on), and a user is never welcomed twice. One send per client every 10 minutes: another call within that window returns 429 with Retry-After; a call that found nobody due does not use the window. Returns 409 while welcome emails are off for the client or before its first_send_date.

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/welcome-emails/sends" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectObject
recipient_countinteger

Users due a welcome email. 0 means nobody is due and nothing was sent.

Errors409The object already exists429Too many requestsError envelope →
PATCH/v2/clients/{client_id}/branding
RequireswritescopeReturns ClientBranding

The client's sender on the dashboard's client Settings › Branding: the name and address the client's training and notification emails come from. Changes only what you send; "" removes the client's own value so your partner-wide sender applies. The logo is uploaded in the dashboard. The response is the client's branding after the change.

Returns 200: Saved

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Request bodyapplication/json

sending_namestring

max length 128

sending_emailstring
curl -X PATCH "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/branding" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sending_name": "Acme IT",
    "sending_email": "it@acme-mfg.com"
  }'
Response objectClientBranding
sending_namestring
sending_emailstring
logo_urlstringNullable
Errors400Invalid requestError envelope →
GET/v2/clients/{client_id}/onboarding/selections
RequiresreadscopeReturns OnboardingSelections

The onboarding modules a new user of this client goes through before their first course, the dashboard's client Onboarding page: every module the client can use (INFIMA's library, yours, and the client's own) and which are selected. source is client when the client has its own selection, partner when it follows yours, and none when nothing is selected. effective says whether a module is delivered: once the client has its own selection, your partner-wide selection no longer applies to it.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

curl "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/onboarding/selections" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectOnboardingSelections
sourcestring
One ofclientpartnernone
modulesarray of object
Show item properties(8)
idstring
titlestring
descriptionstring
ownerstring

Whose module it is.

One ofinfimapartnerclient
selectedboolean

Selected by the client or by you.

effectiveboolean

Delivered to the client's new users.

selected_bystring
One ofclientpartnernone
sequence_orderinteger
PUT/v2/clients/{client_id}/onboarding/selections
RequireswritescopeReturns OnboardingSelections

Replaces the client's own onboarding selection with modules, in the order given (sequence_order, 1 or more and different for each module, overrides the order). Each id is a module from GET /clients/{client_id}/onboarding/selections; an unknown id returns 400 naming it. An empty list removes the client's own selection so it follows yours again. Custom modules are made by INFIMA on request and then appear in the list. The response is the selection after the change.

Returns 200: Saved

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Request bodyapplication/json

modulesarray of objectRequired
Show item properties(2)
idstringRequired
sequence_orderinteger

min 1

curl -X PUT "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/onboarding/selections" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modules": [
      {
        "id": "42",
        "sequence_order": 1
      }
    ]
  }'
Response objectOnboardingSelections
sourcestring
One ofclientpartnernone
modulesarray of object
Show item properties(8)
idstring
titlestring
descriptionstring
ownerstring

Whose module it is.

One ofinfimapartnerclient
selectedboolean

Selected by the client or by you.

effectiveboolean

Delivered to the client's new users.

selected_bystring
One ofclientpartnernone
sequence_orderinteger
Errors400Invalid requestError envelope →
GET/v2/clients/{client_id}/report-phishing-button
RequiresreadscopeReturns ReportPhishingButtonSettings

Where the client's reported emails go, the dashboard's client Settings › Report Phishing Button: report_address is the client's Report Phishing Mailbox ("" when your partner-wide mailbox applies), and each of recipients gets its own copy of every report too. Whether a report is forwarded from the user's own mailbox is in GET /clients/{client_id}/settings. Microsoft Defender reporting is connected in the dashboard.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

curl "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/report-phishing-button" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectReportPhishingButtonSettings
report_addressstring
recipientsarray of string
PATCH/v2/clients/{client_id}/report-phishing-button
RequireswritescopeReturns ReportPhishingButtonSettings

Changes only what you send. report_address is one plain address ("" uses your partner-wide mailbox). recipients replaces the client's additional recipients: up to 10 plain addresses, duplicates ignored; [] removes them all. Every address is checked before anything is saved, so a 400 changes nothing. The response is the settings after the change.

Returns 200: Saved

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Request bodyapplication/json

report_addressstring
recipientsarray of string

max 10 items

curl -X PATCH "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/report-phishing-button" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "report_address": "phishing@acme-mfg.com",
    "recipients": [
      "soc@northwind-it.com"
    ]
  }'
Response objectReportPhishingButtonSettings
report_addressstring
recipientsarray of string
Errors400Invalid requestError envelope →
GET/v2/clients/{client_id}/settings
RequiresreadscopeReturns ClientSettings

The settings you choose when onboarding a client, the dashboard's client Settings pages, in one object: phishing, training, Dark Web Monitoring and the Report Phishing Button. A setting that can follow your partner-wide value has client_override (the client's own value, null when it follows yours) next to enabled or mode (the value that applies).

Recipient lists have their own endpoint: GET /clients/{client_id}/recipients/{kind}.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

curl "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/settings" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectClientSettings
phishingobject
Show properties(5)
interval_daysintegerNullable
bannerstring
One ofmicrominiverbose
synthetic_received_headerboolean
external_sender_tagSettingOverride
Show properties(2)
enabledboolean

The value that applies.

client_overridebooleanNullable

The client's own value; null when it follows your partner-wide value.

sender_namesobject
Show properties(2)
modestring
One ofmade_upreal_by_role
client_overridestringNullable
One ofmade_upreal_by_role
trainingobject
Show properties(6)
courses_per_yearinteger
adaptiveboolean
grace_daysintegerNullable

The client's own grace period; null uses the default.

framework_grace_daysintegerNullable

Grace period for framework courses; null uses grace_days.

default_grace_daysinteger
title_rolesarray of object

This client's own job title to risk role remaps, for the job titles its active users have.

Show item properties(2)
titlestring
rolestring

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

One ofadminexecutivehrfinanceitstandard
dark_webobject
Show properties(2)
enabledboolean
breach_notificationsobject
Show properties(4)
alertsSettingOverride
Show properties(2)
enabledboolean

The value that applies.

client_overridebooleanNullable

The client's own value; null when it follows your partner-wide value.

notify_userSettingOverride
Show properties(2)
enabledboolean

The value that applies.

client_overridebooleanNullable

The client's own value; null when it follows your partner-wide value.

sending_namestring
sending_emailstring
report_phishing_buttonobject
Show properties(1)
send_from_userSettingOverride
Show properties(2)
enabledboolean

The value that applies.

client_overridebooleanNullable

The client's own value; null when it follows your partner-wide value.

PATCH/v2/clients/{client_id}/settings
RequireswritescopeReturns ClientSettings

Changes only what you send: every sub-object and field is optional, and a field left out stays as it is. Send client_override: null (or null for a grace period) to drop the client's own value so it follows your partner-wide value again, as the dashboard's "Use partner default" does. Read-only fields (enabled, mode, default_grace_days) are ignored. All fields are checked before anything is saved, so a 400 changes nothing; it lists every problem in details (training.courses_per_year). The changes are saved one setting at a time, so a 500 can leave some of them saved; every field sets a value, so sending the same request again is safe. The response is the client's settings after the change.

  • phishing.interval_days: days between simulations, at least 5. It is kept with the client's users, so a client with none yet (before its first sync or user) returns 409; set it once users arrive. Until then the client gets the default.
  • phishing.banner: the Inky-style warning banner (micro, mini, verbose), or "" for none. Choosing a banner removes a custom text header, as in the dashboard.
  • phishing.synthetic_received_header: adds the look-alike Received and X-Originating-IP headers to Microsoft 365 simulations.
  • phishing.external_sender_tag.client_override: Outlook's "External" tag on Microsoft 365 simulations. On unless you turned it off.
  • phishing.sender_names.client_override: made_up or real_by_role. Real names put the names of the client's own staff on look-alike senders and need phishing.sender_names.acknowledged: true, the dashboard's consent tick, whenever the result is real names (including following a partner-wide real_by_role).
  • training.courses_per_year (1 to 12) and training.adaptive (fill empty slots from the adaptive course pool) are the client's own values; they have no partner fallback to return to, so null is refused.
  • training.grace_days and training.framework_grace_days (1 to 730): days to finish an assigned course; null returns to the default.
  • training.title_roles: job title to risk role remaps for this client. Each entry sets one title; role: null removes its remap. Titles not sent are untouched.
  • dark_web.enabled: Dark Web Monitoring scans for this client.
  • dark_web.breach_notifications: client_override for alerts and for emailing the affected user, and the alert sender (sending_name, sending_email; "" uses the default sender). Who receives alerts is PUT /clients/{client_id}/recipients/breach_notification.
  • report_phishing_button.send_from_user.client_override: whether a report is forwarded from the reporting user's own mailbox.

Returns 200: Saved

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Request bodyapplication/json · ClientSettingsUpdate

phishingobject
Show properties(5)
interval_daysinteger

min 5

bannerstring
One ofmicrominiverbose
synthetic_received_headerboolean
external_sender_tagobject
Show properties(1)
client_overridebooleanNullable
sender_namesobject
Show properties(2)
client_overridestringNullable
One ofmade_upreal_by_role
acknowledgedboolean
trainingobject
Show properties(5)
courses_per_yearinteger

min 1 · max 12

adaptiveboolean
grace_daysintegerNullable

min 1 · max 730

framework_grace_daysintegerNullable

min 1 · max 730

title_rolesarray of object

max 100 items

Show item properties(2)
titlestringRequired

max length 200

rolestringNullable

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

One ofadminexecutivehrfinanceitstandard
dark_webobject
Show properties(2)
enabledboolean
breach_notificationsobject
Show properties(4)
alertsobject
Show properties(1)
client_overridebooleanNullable
notify_userobject
Show properties(1)
client_overridebooleanNullable
sending_namestring

max length 128

sending_emailstring (email)
report_phishing_buttonobject
Show properties(1)
send_from_userobject
Show properties(1)
client_overridebooleanNullable
curl -X PATCH "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/settings" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phishing": {
      "interval_days": 0,
      "banner": "",
      "synthetic_received_header": true,
      "external_sender_tag": {
        "client_override": true
      },
      "sender_names": {
        "client_override": "made_up",
        "acknowledged": true
      }
    },
    "training": {
      "courses_per_year": 0,
      "adaptive": true,
      "grace_days": 0,
      "framework_grace_days": 0,
      "title_roles": [
        {
          "title": "title_value",
          "role": "admin"
        }
      ]
    },
    "dark_web": {
      "enabled": true,
      "breach_notifications": {
        "alerts": {
          "client_override": true
        },
        "notify_user": {
          "client_override": true
        },
        "sending_name": "sending_name_value",
        "sending_email": "jane.doe@example.com"
      }
    },
    "report_phishing_button": {
      "send_from_user": {
        "client_override": true
      }
    }
  }'
Response objectClientSettings
phishingobject
Show properties(5)
interval_daysintegerNullable
bannerstring
One ofmicrominiverbose
synthetic_received_headerboolean
external_sender_tagSettingOverride
Show properties(2)
enabledboolean

The value that applies.

client_overridebooleanNullable

The client's own value; null when it follows your partner-wide value.

sender_namesobject
Show properties(2)
modestring
One ofmade_upreal_by_role
client_overridestringNullable
One ofmade_upreal_by_role
trainingobject
Show properties(6)
courses_per_yearinteger
adaptiveboolean
grace_daysintegerNullable

The client's own grace period; null uses the default.

framework_grace_daysintegerNullable

Grace period for framework courses; null uses grace_days.

default_grace_daysinteger
title_rolesarray of object

This client's own job title to risk role remaps, for the job titles its active users have.

Show item properties(2)
titlestring
rolestring

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

One ofadminexecutivehrfinanceitstandard
dark_webobject
Show properties(2)
enabledboolean
breach_notificationsobject
Show properties(4)
alertsSettingOverride
Show properties(2)
enabledboolean

The value that applies.

client_overridebooleanNullable

The client's own value; null when it follows your partner-wide value.

notify_userSettingOverride
Show properties(2)
enabledboolean

The value that applies.

client_overridebooleanNullable

The client's own value; null when it follows your partner-wide value.

sending_namestring
sending_emailstring
report_phishing_buttonobject
Show properties(1)
send_from_userSettingOverride
Show properties(2)
enabledboolean

The value that applies.

client_overridebooleanNullable

The client's own value; null when it follows your partner-wide value.

Errors400Invalid request409The object already existsError envelope →