Recommendations

Recommendation APIs provided by Fraud Prevention are used to assess risk level, obtain recommendations, and provide feedback

Download OpenAPI description

recommendations.openapi.json

recommendations.openapi.yaml

Servers

Sandbox environment

https://api.sbx.transmitsecurity.io/risk/v1/

Production environment (US)

https://api.transmitsecurity.io/risk/v1/

Production environment (EU)

https://api.eu.transmitsecurity.io/risk/v1/

Production environment (CA)

https://api.ca.transmitsecurity.io/risk/v1/

Production environment (AU)

https://api.au.transmitsecurity.io/risk/v1/

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

Recommended way to handle the reported action

recommendation.typestringrequired

Recommendation type

Enum"CHALLENGE""DENY""ALLOW""TRUST"

recommendation.resultstring

The outcome of the action.

Enum"success""failure""incomplete"

recommendation.challenge_typestring

The type of challenge enforced for the reported action.

Enum"email_otp""totp""push_otp""voice_otp""idv""captcha""invisible_captcha""password""passkey"

risk_scorenumber[ 0 .. 100 ]required

Used to assess the risk level of the client action

Example: 73.2

contextobjectrequired

Identifies the context in which the action occurred

context.action_idstringrequired

Identifier of the client action

Example: "885cd06b527a97498200560b67123fe221b5a39fd98d8d22cdb7ca8ec16ed62d"

context.action_typestringrequired

Type of client action this recommendation was issued for

Example: "login"

context.action_performed_atnumberrequired

Unix epoch time in milliseconds the action event was reported

Example: 1648028118123

context.device_timestampnumber

Unix epoch timestamp (ms) from the device clock when the action is triggered via triggerActionEvent(). For backend-triggered actions, uses the server time (Date.now()). Used to correlate client and server events.

Example: 1648028107819

context.client_idstring

Identifies the client associated with the action

Example: "d152ddd.ece93f4.c2a3d12.riskid.security"

context.application_idstringrequired

Identifies the application associated with the action

Example: "ece93f4"

context.tenant_idstring

Identifies your tenant within Transmit

Example: "c2a3d12"

context.device_idstringrequired

Unique device identifier. On web, stored in the cookie. On mobile, uses platform-provided identifiers such as Android ID (hex string) or iOS identifierForVendor (alphanumeric). Not derived from IMEI or other hardware identifiers.

Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIwZGE4ZmZjYy01NmE1LTRmMjgtYThkZi04NDY5MmYwYThmYTAiLCJ2ZXJzaW9uIjoxLCJpYXQiOjE2NTU3OTYzODQ1MzF9.TeGoqlCe_6eWzl9a3-vAumG4Xap8WjwsgcO2-DzGtLg"

context.correlation_idstring

Any ID that could help relate the action with external context or session (if set via triggerActionEvent() SDK calls)

Example: "bcb934d8-89cb-433b-a4c7-b7d94299586b"

context.device_fingerprintstringrequired

Hash value on all the device data collected from the browser

Example: "a3c8f5ea75cb65fcdc3d0452b985f957a46e24afdc912e93dac1e115ecf408e5"

context.device_public_keystring

A unique and persistent identifier derived from cryptographic binding

Example: "625ad815e47a1a05318c98185ff8cfb35fd706d836a1ad7459842f381929a8e3"

context.user_idstring

Opaque identifier of the user in your system (if set via setAuthenticatedUser() or init() SDK calls)

Example: "5c4afa75c"

context.claimed_user_idstring

User ID of the not yet authenticated user, used to enhance risk and trust assessments. Once the user is authenticated, drs.setAuthenticatedUser() should be called.

Example: "5c4afa75c"

context.locationstring

The place in the application in which the action was performed (such as the page URL)

Example: "https://www.amazingapp.com/shops?target=1"

context.ipstring(ipv4)

IP address

context.ip_countrystring

Country code, specified in a two-letter format (ISO 3166-1 alpha-2)

Example: "UK"

context.ip_regionstring

Location region identified by IP address

Example: "California"

context.ip_location_citystring

Location city identified by IP address

Example: "Los Angeles"

context.ip_location_zipstring

Location zip code identified by IP address

Example: 92131

context.ip_location_longitudestring

Geolocation longitude identified by IP address

Example: "-117.0903"

context.ip_location_latitudestring

Geolocation latitude identified by IP address

Example: "32.9167"

context.ip_asn_namestring

Globally unique identifier that defines a group of one or more IP prefixes

Example: "AS174 Cogent Communications"

context.ip_asn_idstring

Globally unique identifier that defines a group of one or more IP prefixes

Example: "AS174"

context.ip_organization_namestring

IP organization name

Example: "Cogent Communications"

context.ip_organization_typestring

Type of IP connection

Example: "isp"

context.ip_location_timezonestring

Timezone location identified by IP address

Example: "America/Los_Angeles"

context.device_timezonestring

Timezone on device

Example: "America/Los_Angeles"

context.device_languagesArray of strings

Languages on device

Example: ["en-US","en"]

context.device_platformstring

Type of device platform

Example: "desktop"

context.os_namestring

Name of the operating system (e.g., macOS)

Example: "macOS"

context.os_versionstring

Operating system version

Example: "14.1.0"

context.browser_namestring

Name of the browser (e.g., Chrome)

Example: "Chrome"

context.browser_versionstring

Browser major version

Example: "113"

context.user_agentstring

User agent

Example: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.90 Safari/537.36"

risk_signalsobject

Additional informative signals

reasonsArray of stringsrequired

Explains the reasons for the recommendation

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

transaction_dataobject

Transaction data-points given in the relevant action, from the SDK

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 the result of this recommendation if all enabled rules were in production. This is returned to allow you to evaluate the impact of preview rules, and did not impact the actual outcome.

Response

application/json

{
  "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": "192.168.0.1",
    "ip_country": "UK",
    "ip_region": "California",
    "ip_location_city": "Los Angeles",
    "ip_location_zip": 92131,
    "ip_location_longitude": "-117.0903",
    "ip_location_latitude": "32.9167",
    "ip_asn_name": "AS174 Cogent Communications",
    "ip_asn_id": "AS174",
    "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": 120,
    "currency": "USD",
    "reason": "string",
    "transactionDate": 0,
    "payer": { … },
    "payee": { … }
  },
  "threats": [
    "ACCOUNT_TAKEOVER",
    "NEW_FRAUD_ACCOUNT"
  ],
  "preview_rule": {
    "rule_name": "string",
    "recommendation": "string"
  }
}

Create ruleDeprecated

Request

Creates a new recommendation rule. Returns the rule_id used to reference the rule in subsequent requests.

Security

risk_access_token

Bodyapplication/jsonrequired

namestring

Name of the recommendation rule. Must be unique across the tenant. Auto generated if not provided.

Example: "Block risky countries"

priorityinteger[ 1 .. 1000 ]required

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.

Example: 10

matcherobjectrequired

One of:

Activity field matcher. Only one matcher can be defined per rule.

matcher.ip_cidrsArray of strings

List of IP ranges in CIDR notation

recommendationstringrequired

Recommendation type

Enum"CHALLENGE""DENY""TRUST"

enabledbooleanrequired

Whether or not the rule will be evaluated

modestringrequired

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"

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/risk/v1/recommendation/rules \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Block risky countries",
    "priority": 10,
    "matcher": {
      "ip_cidrs": [
        "string"
      ]
    },
    "recommendation": "CHALLENGE",
    "enabled": true,
    "mode": "PREVIEW"
  }'

Responses

Rule created successfully

Bodyapplication/json

messagestring

rule_idstring

ID of the recommendation rule, used to reference the rule

Response

application/json

{
  "message": "string",
  "rule_id": "string"
}

Get all rulesDeprecated

Request

Retrieves a list of all recommendation rules

Security

risk_access_token

curl -i -X GET \
  https://api.sbx.transmitsecurity.io/risk/v1/recommendation/rules \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Rules retrieved successfully

Bodyapplication/json

dataArray of objects

Response

application/json

{
  "data": [
    { … }
  ]
}

Get rule by IDDeprecated

Request

Retrieves a specific recommendation rule by its ID

Security

risk_access_token

Path

rule_idstringrequired

ID of the recommendation rule

curl -i -X GET \
  'https://api.sbx.transmitsecurity.io/risk/v1/recommendation/rules/{rule_id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Rule retrieved successfully

Bodyapplication/json

idstring

Rule ID

dataobject

Recommendation rule

Response

application/json

{
  "id": "string",
  "data": {
    "name": "Block risky countries",
    "priority": 10,
    "matcher": { … },
    "recommendation": "CHALLENGE",
    "enabled": true,
    "mode": "PREVIEW"
  }
}

Update rule by IDDeprecated

Request

Updates a specific recommendation rule

Security

risk_access_token

Path

rule_idstringrequired

ID of the recommendation rule

Bodyapplication/jsonrequired

namestring

Name of the recommendation rule. Must be unique across the tenant. Auto generated if not provided.

Example: "Block risky countries"

priorityinteger[ 1 .. 1000 ]required

Example: 10

matcherobjectrequired

One of:

Activity field matcher. Only one matcher can be defined per rule.

matcher.ip_cidrsArray of strings

List of IP ranges in CIDR notation

recommendationstringrequired

Recommendation type

Enum"CHALLENGE""DENY""TRUST"

enabledbooleanrequired

Whether or not the rule will be evaluated

modestringrequired

Enum"PREVIEW""PRODUCTION"

curl -i -X PUT \
  'https://api.sbx.transmitsecurity.io/risk/v1/recommendation/rules/{rule_id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Block risky countries",
    "priority": 10,
    "matcher": {
      "ip_cidrs": [
        "string"
      ]
    },
    "recommendation": "CHALLENGE",
    "enabled": true,
    "mode": "PREVIEW"
  }'

Responses

Rule updated successfully

Bodyapplication/json

messagestring

Response

application/json

{
  "message": "string"
}

Delete rule by IDDeprecated

Request

Deletes a specific recommendation rule. Note that you can also disable rules if needed using the enabled rule attribute.

Security

risk_access_token

Path

rule_idstringrequired

ID of the recommendation rule

curl -i -X DELETE \
  'https://api.sbx.transmitsecurity.io/risk/v1/recommendation/rules/{rule_id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Rule updated successfully

Bodyapplication/json

messagestring

Response

application/json

{
  "message": "string"
}

Recommendations

Get recommendation

Request

Responses

Create ruleDeprecated

RequestExpand all

Responses

Get all rulesDeprecated

Request

Responses

Get rule by IDDeprecated

Request

Responses

Update rule by IDDeprecated

RequestExpand all

Responses

Delete rule by IDDeprecated

Request

Responses

Request

Request