SmartURLs
Use SmartURLs to analyze shortlink visitors and return the correct redirect, block, or JavaScript verification behavior for a registered keyname.
SmartURLs combines shortlink configuration with visitor IP, user agent, device, country, hostname, and reputation checks before returning the final redirect decision.
Endpoint
GET https://api.stopbot.net/services/shorterlinkParameters
apikey
Yes
Your STOPBOT API key
ip
Yes
Visitor IPv4 or IPv6 address
keyname
Yes
SmartURLs keyname from the STOPBOT panel
ua
No
Visitor user agent
url
No
Current requested URL or path
Parameter Rules
ip
Must be a valid IPv4 or IPv6 address
keyname
Must be 1-64 characters using A-Z, a-z, 0-9, ., _, or -
ua
Optional user agent value used for device and bot/crawler detection
url
Optional requested URL or path
If keyname is invalid, inactive, removed, or not registered for the API key owner, SmartURLs returns a success response with detectActivity: BLOCK BY INVALID KEYNAME.
Example Request
Example Response
Invalid Input Example
If the ip parameter is missing or is not a valid IPv4/IPv6 address, SmartURLs returns 400 Bad Request.
Example response:
Invalid Keyname Example
Invalid, inactive, removed, or unowned keynames do not return a validation error. They return a normal JSON response with a block decision.
Response Fields
Successful SmartURLs responses may include the following fields:
ip
Visitor IP address from the ip request parameter
hostname
Hostname or PTR value resolved for the visitor IP. If no hostname is available, the IP itself may be returned
asn
Autonomous System Number from IP geolocation data
userType
Network user type from IP geolocation data. Current values are business, cellular, hosting, and residential. If unavailable, STOPBOT returns unknown
connectionType
Network connection type from IP geolocation data. Current values are Cable/DSL, Cellular, Corporate, and Dialup. If unavailable, STOPBOT returns unknown
company
Autonomous system organization or company name from IP geolocation data. If unavailable, STOPBOT returns unknown
isp
Internet service provider name from IP geolocation data. If unavailable, STOPBOT returns unknown
city
City name from IP geolocation data. If unavailable, STOPBOT may return unknown
district
District or second subdivision from IP geolocation data when available
region
Region or first subdivision from IP geolocation data. If unavailable, STOPBOT may return unknown
postcode
Postal code from IP geolocation data when available
country
Country name from IP geolocation data. If unavailable, STOPBOT returns unknown
countryCode
Country ISO code from IP geolocation data. If unavailable, STOPBOT returns NN
latitude
Latitude from IP geolocation data. If unavailable, the value may be 0
longitude
Longitude from IP geolocation data. If unavailable, the value may be 0
timezone
Timezone from IP geolocation data. If unavailable, STOPBOT returns UTC
isAnycast
true when the IP geolocation data marks the IP as anycast; otherwise false
device
Device classification derived from the ua request parameter
ua
User agent value from the request. This field is only included when ua is provided
isBot
Visitor classification signal: 0 visitor/non-bot, 1 detected bot/threat, 2 user list match
blockAccess
1 means blocked redirect behavior should be applied; 0 means normal redirect behavior can be used
threatURL
1 when the request is treated as threat-related; otherwise 0
detectActivity
Detection reason returned by the SmartURLs decision flow
redirectTo
Destination URL returned when the keyname configuration is found
jsResponse
JavaScript verification setting from the SmartURLs configuration. 1 means verification is enabled
uniqueCode
Verification token returned when JavaScript verification is enabled
status
API result status
executionTime
Server-side execution time for the request
timeResponse
Response timestamp in YYYY-MM-DD HH:mm:ss format
Redirect Fields
redirectTo
Destination URL your SmartURLs client should use
jsResponse
JavaScript verification setting from the SmartURLs configuration. 1 means verification is enabled
uniqueCode
Present only when jsResponse is 1 and a verification token was generated
blockAccess
1 means SmartURLs selected the blocked redirect behavior; 0 means SmartURLs selected the normal destination
Use blockAccess and redirectTo for the final action. The detectActivity field explains the detection reason and may still contain a block reason when the configuration is set to monitor or allow the visitor.
Do not use isBot as the final redirect decision. SmartURLs can block or redirect a human/non-bot visitor based on your keyname configuration. For example, a country restriction can return:
In this case, the visitor is not classified as a bot, but the SmartURLs client should still use the blocked redirectTo value because blockAccess is 1.
JavaScript Verification Flow
When JavaScript verification is enabled for the keyname, the normal SmartURLs response includes uniqueCode.
The browser should complete verification before the final redirect. Your SmartURLs client should call the same endpoint again with:
Example:
Successful verification response:
If the verification code does not match a pending SmartURLs visitor record, the response may still return status: success without AddVisitorStatus.
When JavaScript verification is not enabled, uniqueCode is not returned.
JavaScript Verification Response Fields
AddVisitorStatus
1 means the pending SmartURLs visitor record was successfully marked as JavaScript verified
status
Verification request status
executionTime
Server-side execution time for the request
timeResponse
Response timestamp in YYYY-MM-DD HH:mm:ss format
Device Values
The device field is derived from the ua request parameter.
Mobile
The user agent contains a known mobile keyword, such as Android, iPhone, iPad, Windows Phone, BlackBerry, Nokia, Kindle, PlayBook, mobi, Silk, Opera Mini, Opera Mobile, UCBrowser, Symbian, Blazer, or WebOS
Desktop
The user agent does not match the mobile keyword list, or no user agent is provided
User Type
The userType field is copied from the IP geolocation data field traits.user_type.
The current STOPBOT IP geolocation database contains these userType values:
business
Business or organization network
cellular
Mobile carrier network
hosting
Hosting, cloud, or data center network
residential
Residential ISP network
If the IP geolocation data does not provide a value, STOPBOT returns:
Connection Type
The connectionType field is copied from the IP geolocation data field traits.connection_type.
The current STOPBOT IP geolocation database contains these connectionType values:
Cable/DSL
Fixed broadband connection
Cellular
Mobile network connection
Corporate
Corporate or organization network connection category
Dialup
Dial-up connection
If the IP geolocation data does not provide a value, STOPBOT returns:
Common Detection Reasons
The detectActivity value can include:
Visitor
No block reason detected
BLOCK BY IP DATABASE.
IP matched STOPBOT IP database or IP range checks
BLOCK BY MALICIOUS ACTIVITY.
IP matched malicious activity or DNS blacklist checks
BLOCK BY HOSTNAME DATABASE.
Hostname matched STOPBOT hostname database
BLOCK BY PROXY/VPN/TOR.
Proxy, VPN, Tor, or spam-source detection
BLOCK BY COUNTRY.
Country is not allowed by configuration
BLOCK BY IP NON-ISP.
Non-ISP network blocked by configuration
BLOCK BY SPIDER CRAWLER
User agent matched bot or crawler detection
BLOCK BY THREAT URL
Request matched repeated failed traffic logic
BLOCK BY INVALID KEYNAME
Keyname is invalid, inactive, removed, or not registered for the API key owner
BLOCK BY DEVICE DESKTOP
Blocked by configured desktop device rule
BLOCK BY DEVICE MOBILE
Blocked by configured mobile device rule
BLOCK BY BLACKLIST IP (USER)
IP matched the user's own IP blacklist
ALLOW BY WHITELIST IP (USER)
IP matched the user's own IP whitelist
BLOCK BY THREAT FEEDS
IP matched STOPBOT threat feeds
BLOCK BY HOSTNAME (USER)
Hostname matched the user's own hostname blacklist
Error Response Fields
Failed SmartURLs responses may include:
errorMessage
Human-readable error message
status
Failed validation may return error or failed, depending on the validation stage
executionTime
Server-side execution time for the request
timeResponse
Response timestamp in YYYY-MM-DD HH:mm:ss format
V1 Difference
Legacy SmartURLs used keyname-based JavaScript tracking.
Current SmartURLs uses a uniqueCode verification token:
Use code for the verification token returned by the current SmartURLs response.
Last updated