Getting started overview

Integrating with the IPQualityScore API involves a sequence of steps designed to enable fraud detection and validation services within your applications. The process generally begins with account creation, followed by the retrieval of your unique API key, and culminates in making your first API call to validate data or assess fraud risk. The API is designed as a RESTful interface, utilizing standard HTTP methods for communication.

The IPQualityScore API provides various endpoints for different fraud detection and data validation services, including general fraud scoring, email validation, phone number validation, and proxy/VPN detection. Each endpoint requires specific parameters, with the API key being a consistent requirement for authentication across all services. Successful integration allows developers to programmatically access IPQualityScore's intelligence for real-time decision-making.

To facilitate a smooth onboarding, IPQualityScore provides detailed documentation that includes API specifications and code examples in several programming languages. This guide focuses on the foundational steps to get a basic fraud detection request operational.

Quick Reference: Getting Started Steps

Step What to do Where
1. Sign Up Create a free or paid IPQualityScore account. IPQualityScore Homepage
2. Get API Key Locate your unique API key in your account dashboard. IPQualityScore Account Dashboard
3. Review Docs Understand the basic request structure for your chosen API. IPQualityScore API Reference
4. Construct Request Build your first API call using an IP address and your API key. Your preferred development environment
5. Execute & Verify Send the request and check the JSON response for expected data. Your preferred development environment

Create an account and get keys

Before making any API calls, you need an IPQualityScore account. This account provides access to your API key, which is essential for authenticating your requests and tracking your usage against your plan limits.

Account Creation

  1. Navigate to the IPQualityScore website.
  2. Click on the 'Sign Up' or 'Get Started Free' button, typically located in the top right corner or prominent on the homepage.
  3. Follow the prompts to enter your email address, create a password, and agree to the terms of service.
  4. You may need to verify your email address to activate your account.
  5. Upon successful signup, you will be directed to your IPQualityScore dashboard. The platform offers a free tier that includes 1,000 lookups per month, suitable for initial testing and development.

Retrieving Your API Key

Your API key serves as your unique identifier and authentication token for all API requests. It is crucial to keep this key confidential to prevent unauthorized use of your account.

  1. Log in to your IPQualityScore account dashboard.
  2. Look for a section labeled 'API Key', 'My Account', or 'Settings'. The exact location may vary slightly based on dashboard updates.
  3. Your API key will be displayed. Copy this key and store it securely. It is recommended to use environment variables or a secure configuration management system in production environments rather than hardcoding the key directly into your application code.

Your first request

To illustrate the process, we will make a basic request to the Fraud Detection API, which is one of IPQualityScore's core services. This API allows you to assess the risk associated with an IP address, providing a fraud score and other relevant data points.

API Endpoint and Parameters

The primary endpoint for the Fraud Detection API is https://www.ipqualityscore.com/api/json/ip/<API_KEY>/<IP_ADDRESS>. You will need to replace <API_KEY> with your actual API key and <IP_ADDRESS> with the IP address you wish to check. Additional parameters can be appended as query strings to refine the lookup, as detailed in the IPQualityScore IP Reputation API documentation.

Example Request (using curl)

The following curl command demonstrates how to make a simple GET request. Replace YOUR_API_KEY with your actual key and 1.1.1.1 with a test IP address.

curl "https://www.ipqualityscore.com/api/json/ip/YOUR_API_KEY/1.1.1.1"

Example Response

A successful request will return a JSON object containing various data points related to the IP address. The structure of the response will include:

  • success: A boolean indicating if the request was successful.
  • message: An error message if success is false.
  • fraud_score: A numerical score indicating the likelihood of fraud (0-100).
  • country_code: The ISO 3166-1 alpha-2 country code.
  • region, city, ISP, organization: Geographic and network details.
  • is_proxy, is_vpn, is_tor: Boolean flags indicating proxy, VPN, or Tor usage.
  • recent_abuse, abuse_velocity: Indicators of recent malicious activity.

Here's an example of a partial JSON response:

{
  "success": true,
  "message": "",
  "fraud_score": 75,
  "country_code": "US",
  "region": "California",
  "city": "Los Angeles",
  "ISP": "Cloudflare",
  "organization": "Cloudflare, Inc.",
  "is_proxy": false,
  "is_vpn": false,
  "is_tor": false,
  "recent_abuse": true,
  "abuse_velocity": "high",
  "latitude": 34.0522,
  "longitude": -118.2437,
  "zip_code": "90012",
  "timezone": "America/Los_Angeles",
  "mobile": false,
  "host": "1.1.1.1",
  "proxy_type": "",
  "active_vpn": false,
  // ... other fields
}

Code Examples in Other Languages

IPQualityScore provides documentation with code examples for several popular programming languages, including PHP, Python, Ruby, Node.js, Java, and C#. These examples demonstrate how to construct and execute API requests using native HTTP client libraries or dedicated SDKs where available.

Common next steps

After successfully making your first API call, consider these next steps to further integrate IPQualityScore into your applications:

  • Explore Additional Endpoints: Beyond IP reputation, investigate the Email Validation API, Phone Number Validation API, and other services relevant to your fraud prevention strategy.
  • Implement Error Handling: Design your application to gracefully handle API errors, such as invalid API keys, rate limits, or malformed requests. The API response includes a success field and a message field to help diagnose issues.
  • Integrate with Your Application Logic: Use the fraud scores and other data points returned by the API to inform your application's decision-making process. For example, you might block registrations from high-risk IP addresses or flag transactions with elevated fraud scores for manual review.
  • Monitor Usage: Regularly check your IPQualityScore dashboard to monitor your API usage and ensure you remain within your plan's limits. Adjust your plan as needed based on your application's requirements.
  • Secure Your API Key: Ensure your API key is stored and transmitted securely. Avoid exposing it in client-side code or public repositories. Consider using environment variables or a secrets management service.
  • Review Best Practices: Consult the IPQualityScore documentation for best practices on integration, including strategies for optimizing performance and minimizing false positives.

Troubleshooting the first call

Encountering issues during your first API call is not uncommon. Here are some common problems and their solutions:

Invalid API Key

  • Symptom: The API returns an error message indicating an invalid or missing API key, or a success: false with a relevant message.
  • Solution: Double-check that you have copied your API key correctly from your IPQualityScore dashboard. Ensure there are no leading or trailing spaces. Verify that the key is correctly inserted into the URL or request header as specified by the API documentation.

Incorrect Endpoint or Parameters

  • Symptom: The API returns a 404 Not Found error, a 400 Bad Request error, or unexpected data.
  • Solution: Review the IPQualityScore API reference to confirm the correct endpoint URL and required parameters for the service you are trying to access. Ensure all mandatory parameters are included and correctly formatted.

Rate Limiting

  • Symptom: Requests start failing with a 429 Too Many Requests status code, even if your API key is valid.
  • Solution: This indicates you have exceeded your plan's request limits. Wait for the rate limit period to reset, or consider upgrading your IPQualityScore plan. Implement exponential backoff and retry logic in your application to handle rate limits gracefully, as described in common API retry strategies.

Network Connectivity Issues

  • Symptom: Your application receives connection timeouts or network errors when attempting to reach the IPQualityScore API.
  • Solution: Verify your internet connection. Check if there are any firewall rules or network proxies blocking outbound connections to www.ipqualityscore.com. Try making the curl request from a different network environment to isolate the issue.

JSON Parsing Errors

  • Symptom: Your application fails to parse the API response, even though the request appears successful.
  • Solution: Ensure your application's JSON parser is correctly configured to handle the API's response format. Sometimes, unexpected characters or an empty response can cause parsing issues. Inspect the raw response body during debugging to confirm it's valid JSON.