Recommendations

Download OpenAPI specification:Download

Recommendation APIs provided by Detection and Response services are used to assess risk level, obtain recommendations, and provide feedback

Get recommendation

Get a risk recommendation for a client action reported to the SDK (via triggerActionEvent() call)

SecurityHTTP: risk_access_token
Request
query Parameters
action_token
required
string
Default: "REPLACE_WITH_ACTION_TOKEN"

Action token returned by the SDK when the action was reported

user_id
string
Default: "REPLACE_WITH_USER_ID"

User identifier as sent to the SDK on the client-side

Responses
200

Recommendation

400

Bad request

401

Invalid authentication

403

Invalid authorization

429

Rate limit reached

500

Internal error

get/recommendation
Request samples 
Response samples 
application/json
{
  • "id": "385cd06b527a974982e0560b67123fe2b1b5a39fd98d8d32cdbaca8ec16fd62d",
  • "issued_at": 1648028118123,
  • "recommendation": {
    },
  • "risk_score": 73.2,
  • "context": {
    },
  • "risk_signals": {
    },
  • "reasons": [
    ],
  • "transaction_data": {
    },
  • "preview_rule": {
    }
}
Create ruleDeprecated
Creates a new recommendation rule. Returns the rule_id used to reference the rule in subsequent requests.


SecurityHTTP: risk_access_token 
Request 
Request Body schema: application/json
required
name
string
Name of the recommendation rule. Must be unique across the tenant. Auto generated if not provided.


 
priority
required
integer  [ 1 .. 1000 ] 
Priority of the recommendation rule, which determines the order in which rules are evaluated. Rules are evaluated from smallest to biggest priority value and only the first rule to match will apply. Priority value must be unique.


 
required
ip_cidrs (object) or device_ids (object) or device_fingerprints (object) or user_ids (object) or country_codes (object) or browser_names (object) or os_versions (object) (matcher) 
Activity field matcher. Only one matcher can be defined per rule.


 
recommendation
required
string (rule_recommendation_type) 
Recommendation type


 Enum: "CHALLENGE" "DENY" "TRUST"  
enabled
required
boolean
Whether or not the rule will be evaluated


 
mode
required
string (rule_mode) 
Allows you to simulate a rule and evaluate its impact before releasing it to production. The simulation occurs each time a recommendation is requested. If a preview rule matches the request (meaning, its priority is higher than all matching rules), the response will include this preview rule and what the recommendation would have been if all rules were in production.


 Enum: "PREVIEW" "PRODUCTION"  
Responses 
201
Rule created successfully


400
Bad request


401
Invalid authentication


403
Invalid authorization


409
Unique field collision


429
Rate limit reached


500
Internal error


post/recommendation/rules
Request samples 
application/json
{
  • "name": "Block risky countries",
  • "priority": 10,
  • "matcher": {
    },
  • "recommendation": "CHALLENGE",
  • "enabled": true,
  • "mode": "PREVIEW"
}
Response samples 
application/json
{
  • "message": "string",
  • "rule_id": "string"
}
Get all rulesDeprecated
Retrieves a list of all recommendation rules


SecurityHTTP: risk_access_token 
Responses 
200
Rules retrieved successfully


400
Bad request


401
Invalid authentication


403
Invalid authorization


429
Rate limit reached


500
Internal error


get/recommendation/rules
Request samples 
Response samples 
application/json
{
  • "data": [
    ]
}
Get rule by IDDeprecated
Retrieves a specific recommendation rule by its ID


SecurityHTTP: risk_access_token 
Request 
path Parameters
rule_id
required
string
ID of the recommendation rule


 
Responses 
200
Rule retrieved successfully


400
Bad request


401
Invalid authentication


403
Invalid authorization


404
Not found


429
Rate limit reached


500
Internal error


get/recommendation/rules/{rule_id}
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "data": {
    }
}
Update rule by IDDeprecated
Updates a specific recommendation rule


SecurityHTTP: risk_access_token 
Request 
path Parameters
rule_id
required
string
ID of the recommendation rule


 
Request Body schema: application/json
required
name
string
Name of the recommendation rule. Must be unique across the tenant. Auto generated if not provided.


 
priority
required
integer  [ 1 .. 1000 ] 
Priority of the recommendation rule, which determines the order in which rules are evaluated. Rules are evaluated from smallest to biggest priority value and only the first rule to match will apply. Priority value must be unique.


 
required
ip_cidrs (object) or device_ids (object) or device_fingerprints (object) or user_ids (object) or country_codes (object) or browser_names (object) or os_versions (object) (matcher) 
Activity field matcher. Only one matcher can be defined per rule.


 
recommendation
required
string (rule_recommendation_type) 
Recommendation type


 Enum: "CHALLENGE" "DENY" "TRUST"  
enabled
required
boolean
Whether or not the rule will be evaluated


 
mode
required
string (rule_mode) 
Allows you to simulate a rule and evaluate its impact before releasing it to production. The simulation occurs each time a recommendation is requested. If a preview rule matches the request (meaning, its priority is higher than all matching rules), the response will include this preview rule and what the recommendation would have been if all rules were in production.


 Enum: "PREVIEW" "PRODUCTION"  
Responses 
200
Rule updated successfully


400
Bad request


401
Invalid authentication


403
Invalid authorization


404
Not found


429
Rate limit reached


500
Internal error


put/recommendation/rules/{rule_id}
Request samples 
application/json
{
  • "name": "Block risky countries",
  • "priority": 10,
  • "matcher": {
    },
  • "recommendation": "CHALLENGE",
  • "enabled": true,
  • "mode": "PREVIEW"
}
Response samples 
application/json
{
  • "message": "string"
}
Delete rule by IDDeprecated
Deletes a specific recommendation rule. Note that you can also disable rules if needed using the enabled rule attribute.


SecurityHTTP: risk_access_token 
Request 
path Parameters
rule_id
required
string
ID of the recommendation rule


 
Responses 
200
Rule updated successfully


400
Bad request


401
Invalid authentication


403
Invalid authorization


404
Not found


429
Rate limit reached


500
Internal error


delete/recommendation/rules/{rule_id}
Request samples 
Response samples 
application/json
{
  • "message": "string"
}