Get recommendation

Request

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

Security

risk_access_token

Query

action_tokenstringrequired

Action token returned by the SDK when the action was reported

Default:"REPLACE_WITH_ACTION_TOKEN"

user_idstringdeprecated

*Deprecated – This parameter is no longer required. Identity and context should be provided during the triggerActionEvent or reportActionResult call. This API now only retrieves the calculated recommendation tied to the action_token.

Default:"REPLACE_WITH_USER_ID"

curl -i -X GET \
  'https://api.sbx.transmitsecurity.io/risk/v1/recommendation?action_token=REPLACE_WITH_ACTION_TOKEN&user_id=REPLACE_WITH_USER_ID' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Recommendation

Bodyapplication/json

idstringrequired

Recommendation identifier

Example:"385cd06b527a974982e0560b67123fe2b1b5a39fd98d8d32cdbaca8ec16fd62d"

issued_atnumberrequired

Unix epoch time in milliseconds this recommendation was issued at

Example:1648028118123

recommendationobjectrequired

Decision the engine produced for the action.

risk_scorenumber, [ 0 .. 100 ]required

Used to assess the risk level of the action.

Example:73.2

contextobjectrequired

Identifies the context in which the action occurred.

risk_signalsobject

Additional informative signals derived from the action.

reasonsArray of stringsrequired

Reasons that contributed to the recommendation.

Example:

[
  "BEHAVIOR_BOT",
  "IP_RISKY_REPUTATION",
  "DEVICE_SUSPICIOUS_ATTRIBUTE",
  "PROFILE_DEVICE_NEW"
]

transaction_dataobject

Transaction data-points provided with the action via the SDK.

custom_attributesobject

Tenant-defined custom attributes attached to the action. These add context to an action but must match the schema defined in the Admin Portal. Invalid attributes are ignored and not included in the response.

threatsArray of strings

List of all detected threats.

Example:

[
  "ACCOUNT_TAKEOVER",
  "NEW_FRAUD_ACCOUNT"
]

preview_ruleobject

Rule configured in preview mode that would have determined this action's recommendation if all enabled rules were in production. Useful for impact analysis without changing live behavior.

Response

{
  "id": "385cd06b527a974982e0560b67123fe2b1b5a39fd98d8d32cdbaca8ec16fd62d",
  "issued_at": 1648028118123,
  "recommendation": {
    "type": "CHALLENGE",
    "result": "success",
    "challenge_type": "email_otp"
  },
  "risk_score": 73.2,
  "context": {
    "action_id": "885cd06b527a97498200560b67123fe221b5a39fd98d8d22cdb7ca8ec16ed62d",
    "action_type": "login",
    "action_performed_at": 1648028118123,
    "device_timestamp": 1648028107819,
    "client_id": "d152ddd.ece93f4.c2a3d12.riskid.security",
    "application_id": "ece93f4",
    "tenant_id": "c2a3d12",
    "device_id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIwZGE4ZmZjYy01NmE1LTRmMjgtYThkZi04NDY5MmYwYThmYTAiLCJ2ZXJzaW9uIjoxLCJpYXQiOjE2NTU3OTYzODQ1MzF9.TeGoqlCe_6eWzl9a3-vAumG4Xap8WjwsgcO2-DzGtLg",
    "correlation_id": "bcb934d8-89cb-433b-a4c7-b7d94299586b",
    "device_fingerprint": "a3c8f5ea75cb65fcdc3d0452b985f957a46e24afdc912e93dac1e115ecf408e5",
    "device_public_key": "625ad815e47a1a05318c98185ff8cfb35fd706d836a1ad7459842f381929a8e3",
    "user_id": "5c4afa75c",
    "claimed_user_id": "5c4afa75c",
    "location": "https://www.amazingapp.com/shops?target=1",
    "ip": "160.221.187.219",
    "ip_country": "US",
    "ip_location_region": "California",
    "ip_domain": "example.com",
    "ip_location_city": "Los Angeles",
    "ip_location_zip": "92131",
    "ip_location_longitude": "-117.0903",
    "ip_location_latitude": "32.9167",
    "ip_asn_id": "AS174",
    "ip_asn_name": "AS174 Cogent Communications",
    "ip_organization_name": "Cogent Communications",
    "ip_organization_type": "isp",
    "ip_location_timezone": "America/Los_Angeles",
    "device_timezone": "America/Los_Angeles",
    "device_languages": [ … ],
    "device_platform": "desktop",
    "os_name": "macOS",
    "os_version": "14.1.0",
    "browser_name": "Chrome",
    "browser_version": "113",
    "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.90 Safari/537.36"
  },
  "risk_signals": {
    "device": { … },
    "network": { … },
    "behavior": { … },
    "history": { … }
  },
  "reasons": [
    "BEHAVIOR_BOT",
    "IP_RISKY_REPUTATION",
    "DEVICE_SUSPICIOUS_ATTRIBUTE",
    "PROFILE_DEVICE_NEW"
  ],
  "transaction_data": {
    "amount": 1500.75,
    "currency": "USD",
    "type": "purchase",
    "method": "card",
    "channelId": "MOBILE_APP",
    "reason": "Monthly subscription payment",
    "transactionDate": 1712594340000,
    "payer": { … },
    "payee": { … },
    "purchase": { … },
    "avs": { … }
  },
  "custom_attributes": {
    "property1": "string",
    "property2": "string"
  },
  "threats": [
    "ACCOUNT_TAKEOVER",
    "NEW_FRAUD_ACCOUNT"
  ],
  "preview_rule": {
    "rule_name": "string",
    "recommendation": "ALLOW",
    "risk_score": 0
  }
}