Migration From V1

This guide explains the main differences between the legacy V1 API and the newer V2 API.

Base URLs

Version	Base URL
V1	https://stopbot.net/api
V2	https://api.stopbot.net/services

Endpoint Mapping

Service	V1	V2
Account	/api/account	/services/account
Blocker	/api/blocker	/services/blocker
Blocker V2	/api/v2/blockerv2	/services/v2/blockerv2
SmartURLs	/api/shorterlink	/services/shorterlink
IP Lookup	/api/iplookup	/services/iplookup
Email Validation	/api/email-validation	/services/email-validation
Phone Number Identify	/api/phone	/services/phonenumber

Response Shape Differences

V1 Blocker and SmartURLs commonly returned nested fields:

{
  "IPInfo": {},
  "IPStatus": {
    "isBot": 1,
    "BlockAccess": 1,
    "ThreatURL": 0,
    "DetectActivity": "BLOCK BY HOSTNAME DATABASE."
  }
}

V2 Blocker returns many fields flat:

{
  "isBot": 1,
  "blockAccess": 1,
  "threatURL": 0,
  "detectActivity": "BLOCK BY HOSTNAME DATABASE."
}

V2 Blocker V2 returns nested sections:

{
  "ipInfo": {},
  "status": {
    "bot": 1,
    "block": 1,
    "threatURL": 0,
    "desc": "[Disallow] - IP Blacklist"
  },
  "pageResponse": {
    "type": "RedirectURL",
    "contents": "https://example.com"
  }
}

SmartURLs JS Flow

V1 JavaScript verification:

/api/shorterlink?apikey=...&ip=...&keyname=...&js=1

V2 JavaScript verification:

/services/shorterlink?apikey=...&ip=...&keyname=...&js=1&code={uniqueCode}

V2 returns uniqueCode in the first SmartURLs response when JavaScript verification is required.

Phone Endpoint Rename

V1:

/api/phone

V2:

/services/phonenumber

Error Handling

V1 often returned HTTP 200 with:

{
  "status": "error",
  "message": "..."
}

V2 uses HTTP status codes more directly, such as:

• 400 invalid input

• 401 API key not found

• 402 quota exceeded or expired

• 405 method not allowed

• 503 service unavailable

Migration Checklist

• Replace base URL from https://stopbot.net/api to https://api.stopbot.net/services.

• Update endpoint paths.

• Update response parsing for changed field names.

• Update SmartURLs JS verification to use uniqueCode and code.

• Update phone endpoint from phone to phonenumber.

• Handle V2 HTTP status codes.

• Test each endpoint with a demo API key before switching production traffic.