Getting started overview

Integrating with Numverify involves a sequence of steps designed to enable phone number validation within your applications. The process begins with account creation, followed by obtaining your unique API access key. This key is central to authenticating all requests made to the Numverify API. Once authenticated, developers can send GET requests to validate phone numbers, receiving structured JSON responses containing details such as validity status, country of origin, line type, and carrier information. The API is designed for straightforward integration, offering clear documentation and code examples in multiple programming languages to facilitate a rapid setup process.

The Numverify API is primarily used for real-time phone number validation, which can support use cases like preventing fraudulent sign-ups and improving data quality by verifying contact information. The API reference documentation provides comprehensive details on available parameters and response structures for various validation scenarios.

Create an account and get keys

To begin using Numverify, you must first register for an account on their official website. This step is necessary to obtain your unique API access key, which authenticates your requests to the validation service. Numverify offers a free tier for 250 requests per month, allowing developers to test the API's functionality before committing to a paid plan.

Registration Process:

  1. Navigate to the Numverify homepage.
  2. Click on the "Sign Up" or "Get API Key" button.
  3. Provide the required information, typically an email address and a password.
  4. Agree to the terms of service.
  5. Complete any email verification steps if prompted.

Upon successful registration, you will be redirected to your account dashboard. Your API access key will be prominently displayed within this dashboard. This key is a unique string of characters that identifies your account and authorizes your API calls. It is crucial to keep this key confidential to prevent unauthorized use of your API quota.

Example of an API Key location:

Your API Access Key:
********************************
  YOUR_ACCESS_KEY_GOES_HERE
********************************

Your first request

After acquiring your API access key, you can make your first API call to validate a phone number. Numverify's API is accessible via standard HTTP GET requests. The base URL for the API is http://api.numverify.com/validate. You will need to append your access key and the phone number you wish to validate as query parameters.

Request Parameters:

  • access_key: Your unique API access key.
  • number: The phone number to be validated (e.g., 14158586273).
  • country_code (optional): A 2-letter country code (e.g., US) to specify the default country for validation if the number has no international prefix.
  • format (optional): Set to 1 to receive formatted local and international versions of the number in the response.

Example API Call (cURL):

The following cURL command demonstrates a basic validation request. Replace YOUR_ACCESS_KEY with your actual API access key and 14158586273 with the phone number you want to validate.

curl "http://api.numverify.com/validate?access_key=YOUR_ACCESS_KEY&number=14158586273"

Example API Call (Python):

Using the requests library in Python, you can construct and send the same validation request:

import requests

access_key = "YOUR_ACCESS_KEY"
phone_number = "14158586273"

params = {
    "access_key": access_key,
    "number": phone_number
}

response = requests.get("http://api.numverify.com/validate", params=params)
data = response.json()

print(data)

Example API Call (PHP):

In PHP, you can use file_get_contents or cURL to make the request:

<?php

$access_key = "YOUR_ACCESS_KEY";
$phone_number = "14158586273";

$url = "http://api.numverify.com/validate?access_key=" . $access_key . "&number=" . $phone_number;

$json_response = file_get_contents($url);
$validation_result = json_decode($json_response, true);

print_r($validation_result);

?>

Expected Response:

A successful response will return a JSON object containing various details about the validated number. An example response structure is:

{
    "valid": true,
    "number": "14158586273",
    "local_format": "(415) 858-6273",
    "international_format": "+1 415 858 6273",
    "country_prefix": "+1",
    "country_code": "US",
    "country_name": "United States of America",
    "carrier": "AT&T Mobility LLC",
    "line_type": "mobile"
}

The valid field indicates whether the number is a legitimate phone number. Other fields provide additional contextual information, such as the carrier and line type, which can be useful for various applications. For a complete list of response parameters, refer to the Numverify API documentation.

Common next steps

Once you have successfully made your first API call and validated a phone number, several common next steps can enhance your integration and leverage Numverify's full capabilities:

  1. Error Handling: Implement robust error handling in your application to gracefully manage API errors, such as invalid access keys, invalid phone numbers, or rate limit exceeded responses. The API returns specific error codes and messages that can be used to inform users or log issues (Numverify error codes documentation).
  2. Advanced Parameters: Explore additional API parameters like country_code to specify a default country for validation or format=1 to receive formatted versions of the number in the response. These can refine validation results, especially for international numbers without explicit country codes.
  3. Integrate into Workflows: Embed phone number validation into your application's workflows. This could include user registration forms to prevent fraudulent sign-ups, CRM systems to clean contact data, or e-commerce platforms to verify shipping contact details.
  4. Monitor Usage: Regularly check your API usage against your plan limits. Your Numverify dashboard provides insights into your request volume, helping you anticipate when an upgrade might be necessary or identify unexpected usage patterns.
  5. Secure API Key: Ensure your API key is stored securely and not exposed in client-side code or public repositories. For server-side applications, use environment variables or a secure configuration management system to manage your API key. General best practices for API key security are outlined by sources such as Google Cloud's API key security guidance.
  6. Explore SDKs/Libraries: While Numverify does not provide official SDKs, community-contributed libraries or custom wrappers can simplify API interaction in your preferred programming language. Consider creating a lightweight wrapper class or module to encapsulate API calls and response parsing.

Quick Reference for Getting Started

Step What to Do Where
1. Create Account Register for a free or paid Numverify account. Numverify Homepage
2. Get API Key Locate your unique API access key in your dashboard. Numverify Account Dashboard
3. Make First Request Construct a GET request with your API key and a phone number. Your code editor (cURL, Python, PHP examples provided)
4. Parse Response Process the JSON response to check validation status and details. Your application logic
5. Implement Error Handling Add logic to manage API errors and invalid responses. Your application logic
6. Secure API Key Store your API key securely, e.g., in environment variables. Server environment/configuration files

Troubleshooting the first call

Encountering issues during your initial API call is common. Here's a guide to troubleshooting the most frequent problems:

API Key Issues:

  • Invalid Access Key: Double-check that you have copied your API access key correctly from your Numverify dashboard. Even minor typos or extra spaces can invalidate the key.
  • Key Not Activated: In some cases, a newly generated key might require a few minutes to become active. Wait a short period and try again.
  • Expired or Revoked Key: If you're using an older key, ensure it hasn't expired or been revoked due to account issues or security concerns. Check your Numverify account settings.

Rate Limit Exceeded:

  • Free Tier Limits: The free tier is limited to 250 requests per month. If you exceed this, subsequent requests will fail. Monitor your usage in your Numverify dashboard.
  • Paid Plan Limits: Even on paid plans, there are per-minute or per-hour rate limits. If you're sending a high volume of requests quickly, consider implementing a delay or batching mechanism.
  • Error Response: The API will typically return an error object indicating a rate limit issue, such as "code": 104, "info": "You have exceeded your daily request limit."

Invalid Phone Number:

  • Incorrect Format: Ensure the phone number is provided in a valid international format (e.g., +14158586273) or with an explicit country code parameter. Missing '+' or incorrect country codes can lead to validation failures.
  • Non-existent Number: The API might report a number as invalid if it doesn't exist or is not recognized by global numbering plans.

Network Connectivity Issues:

  • Firewall/Proxy: If you're making requests from within a corporate network, a firewall or proxy might be blocking outbound HTTP requests to the Numverify API endpoint. Consult your network administrator.
  • DNS Resolution: Ensure your system can resolve api.numverify.com to its correct IP address.

Checking Response Errors:

Numverify provides detailed error responses in JSON format. Always inspect the success field (which will be false for errors) and the error object for specific codes and information:

{
    "success": false,
    "error": {
        "code": 101,
        "type": "missing_access_key",
        "info": "You have not supplied an API Access Key. [Required format: access_key=YOUR_ACCESS_KEY]"
    }
}

The Numverify documentation lists all possible error codes and their meanings, which is the primary resource for diagnosing specific API response issues.