VPN Check

Endpoint Overview

POST /api/v1/vpn/vpn-check

Description

The VPN Check API provides comprehensive analysis of IP addresses to identify VPN usage, proxy connections, and potential security threats. This endpoint performs real-time geolocation lookups and security assessments, returning detailed information about the IP address including geographical location, connection type, and security indicators.

This API is essential for businesses that need to verify user authenticity, prevent fraud, detect anonymized traffic, and enforce geo-restriction policies. By analyzing IP addresses in real-time, organizations can make informed decisions about user access, transaction approval, and security measures.

The endpoint returns rich data including continent, country, region, city-level location data, ISP information, connection types, and critical security flags such as VPN detection, proxy identification, Tor network usage, and threat assessments.

Key Benefits

Real-time VPN Detection: Instantly identify if an IP address is associated with VPN services or proxy servers

Comprehensive Geolocation Data: Access detailed location information down to city-level precision with coordinates

Enhanced Security Intelligence: Detect potential threats including crawlers, Tor networks, and anonymization services

Fraud Prevention: Make informed decisions based on IP reputation and connection type analysis

Use Cases

E-commerce & Payments

Content Streaming & Media

Financial Services & Banking

Fraud Detection: Identify suspicious transactions originating from VPN or proxy connections that may indicate fraudulent activity

Geographic Restrictions: Enforce regional pricing, product availability, and shipping restrictions based on actual user location

Payment Verification: Validate that payment methods match the user's declared location by checking IP authenticity

Account Security: Detect account takeover attempts by identifying unusual login patterns from anonymized IPs

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token for your desired environment.

Include in Requests: Add the token to the Authorization header as Bearer YOUR_JWT_TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox Environment: https://sandbox.surepass.app

Production Environment: https://kyc-api.surepass.app

The JWT token must be valid and not expired. Token expiration and refresh mechanisms should be implemented in your application to maintain uninterrupted service.

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication. Format: `Bearer YOUR_JWT_TOKEN`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
ip_address	string	Yes	The IP address to be analyzed. Supports only IPv4 format.

Example Request

{
  "ip_address": "104.28.193.11"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding the complete IP analysis results
data.client_id	string	Unique identifier for this API
data.ip_address	string	The IP address that was analyzed
data.details	object	Detailed information about the IP address
data.details.type	string	IP address type
data.details.continent_code	string	Two-letter continent code
data.details.continent_name	string	Full name of the continent
data.details.country_code	string	Two-letter ISO country code
data.details.country_name	string	Full country name
data.details.region_code	string	Region or state code
data.details.region_name	string	Full region or state name
data.details.city	string	City name
data.details.zip	string	Postal/ZIP code
data.details.latitude	number	Geographical latitude coordinate
data.details.longitude	number	Geographical longitude coordinate
data.details.msa	string	Metropolitan Statistical Area code
data.details.dma	string	Designated Market Area code
data.details.radius	string	Accuracy radius in kilometers
data.details.ip_routing_type	string	Type of IP routing
data.details.connection_type	string	Connection type identifier
data.details.location	object	Additional location metadata
data.details.location.geoname_id	string	GeoNames database identifier
data.details.location.capital	string	Capital city of the country
data.details.location.languages	array	Array of language objects spoken in the location
data.details.location.languages[].code	string	ISO language code
data.details.location.languages[].name	string	English name of the language
data.details.location.languages[].native	string	Native name of the language
data.details.security	object	Security analysis and threat detection information
data.details.security.is_proxy	boolean	Indicates if the IP is identified as a proxy
data.details.security.proxy_type	string/null	Type of proxy if detected
data.details.security.is_crawler	boolean/null	Indicates if the IP is associated with web crawlers
data.details.security.crawler_name	string/null	Name of the crawler if detected
data.details.security.crawler_type	string/null	Type of crawler if detected
data.details.security.is_tor	boolean	Indicates if the IP is part of the Tor network
data.details.security.threat_level	string/null	Overall threat level assessment
data.details.security.threat_types	array/null	Array of specific threat types identified
data.details.security.proxy_last_detected	string/null	Timestamp when proxy was last detected
data.details.security.proxy_level	string/null	Level or anonymity of the proxy
data.details.security.vpn_service	boolean	Indicates if the IP is associated with VPN services
data.details.security.anonymizer_status	string/null	Status of anonymization service usage
data.details.security.hosting_facility	boolean/null	Indicates if IP belongs to a hosting facility
status_code	integer	HTTP status code of the response
success	boolean	Indicates if the request was processed successfully
message	string	Human-readable message describing the response
message_code	string	Machine-readable message code for programmatic handling

Example Successful Response

{
  "data": {
    "client_id": "vpn_check_YSZewCsswUoPidLbizZl",
    "ip_address": "104.28.193.11",
    "details": {
      "type": "ipv4",
      "continent_code": "AS",
      "continent_name": "Asia",
      "country_code": "IN",
      "country_name": "India",
      "region_code": "DL",
      "region_name": "Delhi",
      "city": "Delhi",
      "zip": "110006",
      "latitude": 28.635299682617188,
      "longitude": 77.2249984741211,
      "msa": "110006",
      "dma": "110006",
      "radius": "110006",
      "ip_routing_type": "fixed",
      "connection_type": "tx",
      "location": {
        "geoname_id": "1273294",
        "capital": "New Delhi",
        "languages": [
          {
            "code": "hi",
            "name": "Hindi",
            "native": "हिन्दी"
          },
          {
            "code": "en",
            "name": "English",
            "native": "English"
          }
        ]
      },
      "security": {
        "is_proxy": false,
        "proxy_type": null,
        "is_crawler": null,
        "crawler_name": null,
        "crawler_type": null,
        "is_tor": false,
        "threat_level": null,
        "threat_types": null,
        "proxy_last_detected": null,
        "proxy_level": null,
        "vpn_service": true,
        "anonymizer_status": null,
        "hosting_facility": null
      }
    }
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

Invalid IP Address

Unauthorized

Missing Required Field

Rate Limit Exceeded

Internal Server Error

{
  "status_code": 400,
  "success": false,
  "message": "Invalid IP address format",
  "message_code": "invalid_ip_format"
}

This error occurs when the provided IP address is not in a valid IPv4 or IPv6 format. Ensure the IP address follows standard notation.

Integration Best Practices

Security Recommendations

Secure Token Storage: Never expose your JWT tokens in client-side code or public repositories. Store tokens securely using environment variables or secure vault solutions

Token Rotation: Implement automatic token refresh mechanisms to ensure uninterrupted service and reduce security risks from token exposure

HTTPS Only: Always use HTTPS for API requests to ensure data transmission is encrypted and protected from man-in-the-middle attacks

Input Validation: Validate IP addresses on the client side before making API calls to reduce unnecessary requests and improve performance

Error Handling: Implement comprehensive error handling to gracefully manage authentication failures, rate limits, and network issues

Logging and Monitoring: Log all VPN detection attempts and security flags for audit trails and pattern analysis, but ensure no sensitive data is logged

User Experience Guidelines

Transparent Communication: Inform users when VPN or proxy detection is being used and explain why it's necessary for security or compliance

Graceful Degradation: Don't immediately block users with VPN detection; instead, implement risk-based approaches with additional verification steps

Performance Optimization: Cache IP analysis results for a reasonable duration to reduce latency and API costs for repeated checks

Progressive Enhancement: Use IP intelligence as one factor in a multi-layered security approach rather than the sole decision criterion

User Privacy: Clearly communicate your data collection and usage policies, especially regarding geolocation tracking

Accessibility: Ensure that security measures don't disproportionately affect users in regions with limited internet infrastructure who may rely on VPNs

Code Samples

cURL

Python

Node.js

Related APIs

IP Reputation API: Advanced threat intelligence and reputation scoring for IP addresses based on historical behavior and known threat databases

Geolocation API: Detailed geolocation services with ISP information, timezone data, and connection speed estimation

Device Fingerprinting API: Comprehensive device identification to detect multiple accounts, fraud patterns, and device reputation

Risk Scoring API: Consolidated risk assessment combining IP intelligence, device data, and behavioral analytics

Compliance and Legal Considerations

Data Privacy Regulations: Ensure compliance with GDPR, CCPA, and other regional data protection laws when collecting and processing IP address information. Users should be informed about IP tracking in your privacy policy.

Consent Requirements: Depending on your jurisdiction, you may need to obtain user consent before performing IP geolocation and VPN detection.

Data Retention: Implement appropriate data retention policies for IP analysis logs in accordance with regulatory requirements and business needs.

Cross-Border Data Transfer: Be aware of data localization requirements when processing IP data for users in different countries.

Legitimate Interest: Ensure that VPN detection and IP analysis serve a legitimate business purpose such as fraud prevention, security enhancement, or regulatory compliance.

Transparency: Maintain clear documentation of how IP data is used, stored, and shared within your organization and with third parties.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/vpn/vpn-check' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "ip_address": "104.28.193.11" }'

{ "data": { "client_id": "vpn_check_YSZewCsswUoPidLbizZl", "ip_address": "104.28.193.11", "details": { "type": "ipv4", "continent_code": "AS", "continent_name": "Asia", "country_code": "IN", "country_name": "India", "region_code": "DL", "region_name": "Delhi", "city": "Delhi", "zip": "110006", "latitude": 28.635299682617188, "longitude": 77.2249984741211, "msa": "110006", "dma": "110006", "radius": "110006", "ip_routing_type": "fixed", "connection_type": "tx", "location": { "geoname_id": "1273294", "capital": "New Delhi", "languages": [ { "code": "hi", "name": "Hindi", "native": "हिन्दी" }, { "code": "en", "name": "English", "native": "English" } ] }, "security": { "is_proxy": false, "proxy_type": null, "is_crawler": null, "crawler_name": null, "crawler_type": null, "is_tor": false, "threat_level": null, "threat_types": null, "proxy_last_detected": null, "proxy_level": null, "vpn_service": true, "anonymizer_status": null, "hosting_facility": null } } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses