1. Partner API v2
  2. Resources
  3. Clients

Clients

The organizations you manage. A client is a tenant in the INFIMA dashboard.
5 endpointsScope readClientAdmin
GET/v2/clients

List clientsLink to this endpoint

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

Create a clientLink to this endpoint

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

Get a clientLink to this endpoint

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}

Update a clientLink to this endpoint

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

List a client's adminsLink to this endpoint

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
Coming in 2.x1 more Clients operation is specified for a later 2.x release.See the roadmap