1. Partner API v2
  2. Resources
  3. Risk

Risk

Human risk score, grade, and the signals behind them.
2 endpointsScope readUserRiskClientRisk
GET/v2/users/{user_id}/risk

Get a user's risk scoreLink to this endpoint

RequiresreadscopeReturns UserRisk

The score, grade, baseline, raw tallies, and each factor's contribution.

Path parameters

user_idstringRequired

User id (the user's INFIMA id).

curl "https://app.infimasecapis.com/v2/users/b7e1c0d2-44aa-5f9e-8c33-1a2b3c4d5e6f/risk" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectUserRisk
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)
Errors404Not found within the key's accessError envelope →
GET/v2/clients/{client_id}/risk

Get a client's risk summaryLink to this endpoint

RequiresreadscopeReturns ClientRisk

Average score and grade, distribution of users by grade, the users most at risk, and the top signals driving the score. This is the number the dashboard leads with.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Query parametersall optional unless marked

at_risk_limitinteger

How many at-risk users to include.

Default 10max 100

curl "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/risk" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectClientRisk
client_idstring
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
user_countinteger
distributionobject

Number of active users at each grade.

Show properties(5)
Ainteger
Binteger
Cinteger
Dinteger
Finteger
at_risk_usersarray of object

Users scoring below 600 (grades D and F), worst first, up to at_risk_limit. Empty when no user is that low.

Show item properties(6)
idstring
emailstring
namestring
scoreinteger
gradestring

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

One ofABCDF
top_factorstring
top_factorsarray of object

The signals costing the client the most points, aggregated.

Show item properties(3)
keystring
labelstring
users_affectedinteger
computed_atstring (date-time)