Getting started overview

Integrating with Veriphone for phone number validation involves a sequence of steps, beginning with account creation and culminating in making API calls. The core functionality is accessible via a RESTful API, primarily utilizing HTTP GET requests to a dedicated endpoint, with responses formatted in JSON. Veriphone provides documentation and code examples in multiple languages to facilitate the integration process.

The standard workflow includes:

  1. Account Creation: Registering on the Veriphone platform to gain access to the dashboard and API key.
  2. API Key Retrieval: Locating the unique API key within the user dashboard, which is essential for authenticating requests.
  3. First API Call: Constructing and executing an initial HTTP GET request to the validation endpoint, passing the API key and a phone number as parameters.
  4. Response Processing: Interpreting the JSON response data returned by the API to determine the validity and additional details of the phone number.

Prior to making live calls, developers can utilize Veriphone's free tier, which allows up to 1,000 requests per month for testing and development purposes.

Step What to do Where to find it
1. Sign Up Create a new Veriphone account. Veriphone homepage
2. Get API Key Locate your unique API Access Key. Veriphone Dashboard (after signup)
3. Make Request Construct an HTTP GET request to the validation endpoint. Veriphone API documentation
4. Process Response Parse the JSON response to extract validation data. Veriphone documentation API response structure

Create an account and get keys

To begin using the Veriphone API, the initial step is to register for an account. This process establishes your user profile on the Veriphone platform and provides access to the necessary credentials for API interaction.

  1. Navigate to the Veriphone Homepage: Open your web browser and go to the Veriphone website.
  2. Initiate Signup: Look for a "Sign Up" or "Get API Key" button, typically located prominently on the homepage. Click this to start the registration process.
  3. Complete Registration Form: You will be prompted to enter basic information such as your email address and a password. Follow the on-screen instructions to complete your registration. Account creation typically involves email verification to confirm ownership of the provided email address.
  4. Access Your Dashboard: Once registered and logged in, you will be directed to your personal Veriphone dashboard.
  5. Retrieve API Key: Within the dashboard, there will be a section dedicated to your API credentials. Locate your unique API Access Key. This key is a string of alphanumeric characters that authenticates your requests to the Veriphone API. It is crucial to keep this key confidential and secure, as it grants access to your account's API usage. The Veriphone documentation on API keys provides further details on managing your credentials.

The API key is a fundamental component for all API requests. Without it, the Veriphone API will not process your requests, returning authentication errors. Developers should store API keys securely, such as in environment variables, and avoid hardcoding them directly into application source code.

Your first request

After acquiring your API key, you can make your first call to the Veriphone API. The API is designed for simplicity, using standard HTTP GET requests. The primary endpoint for phone number validation is straightforward, requiring two key parameters: your API Key and the phone number to be validated.

The base URL for the validation endpoint is:

https://api.veriphone.io/v2/verify

To make a request, you append your API key and the phone number as query parameters. The phone number should be provided in international format (e.g., +12025550170).

Example Request (cURL)

A basic cURL command demonstrates how to construct this request:

curl "https://api.veriphone.io/v2/verify?key=YOUR_API_KEY&phone=%2B12025550170"

Replace YOUR_API_KEY with your actual API key obtained from your Veriphone dashboard, and %2B12025550170 with the URL-encoded phone number you wish to validate. The %2B represents the + sign.

Example Response

A successful request will return a JSON object similar to this:

{
  "phone": "+12025550170",
  "phone_valid": true,
  "phone_type": "mobile",
  "country": "United States",
  "country_code": "US",
  "country_prefix": "+1",
  "international_number": "+1 202-555-0170",
  "local_number": "(202) 555-0170",
  "carrier": "Example Carrier Corp",
  "location": "Washington, D.C.",
  "is_prepaid": false,
  "is_roaming": false,
  "block": false,
  "error": null
}

This response structure provides comprehensive details about the phone number, including its validity, type (e.g., mobile, landline), associated country, and carrier information. Detailed explanations of each field are available in the Veriphone API reference.

Common next steps

After successfully making your first API call, several common development paths emerge, depending on your application's requirements:

  1. Integrate with an SDK: Veriphone provides official SDKs for multiple programming languages including Python, PHP, and Node.js. Using an SDK can simplify API interaction by handling HTTP requests, response parsing, and error handling, allowing developers to focus on application logic. For example, a Python SDK might abstract the cURL command into a simpler function call.

  2. Error Handling Implementation: Implement robust error handling to manage cases where the API call fails or returns an error. This includes handling network issues, invalid API keys, or malformed phone numbers. The Veriphone API returns specific error codes and messages in its JSON responses for these scenarios. Consistent error handling can make an application more resilient.

  3. Rate Limiting Management: Be aware of the rate limits associated with your Veriphone plan. Implement mechanisms in your application to manage the frequency of API requests to avoid exceeding these limits, which could lead to temporary service interruptions. Strategies might include request queuing or exponential backoff for retries.

  4. Automated Workflows: Incorporate Veriphone validation into automated workflows for tasks such as user registration forms, contact list cleansing, or fraud detection. For instance, before storing a new user's phone number, validate it using the API. This proactive validation helps maintain data integrity and improve communication efficiency.

  5. Explore Pricing and Scaling: As your usage grows beyond the free tier, review Veriphone's pricing plans to select a subscription that aligns with your application's scalability needs. Paid plans offer increased request volumes, starting from 25,000 requests/month for $9.99.

  6. Security Best Practices: Beyond securing your API key as identified by the Google Developers guide on API key best practices, ensure that any user-provided phone numbers are properly sanitized before being sent to the API to prevent injection vulnerabilities. Use HTTPS for all API communication to protect data in transit, which Veriphone inherently supports.

Troubleshooting the first call

When making your first API call to Veriphone, issues can arise from various factors. Careful examination of the request and response can help identify and resolve common problems.

  • Invalid API Key: This is a frequent cause of authentication errors. Double-check that the API key included in your request exactly matches the key displayed in your Veriphone dashboard. Ensure there are no leading or trailing spaces, or incorrect characters. If in doubt, generate a new key from your dashboard if the option is available, or copy it directly again.

  • Incorrect Endpoint URL: Verify that the base URL for the API call is correct: https://api.veriphone.io/v2/verify. Any typos or incorrect protocols (e.g., http instead of https) can lead to connection failures or 404 Not Found errors.

  • Malformed Phone Number: The API expects phone numbers to be in an international format, ideally starting with a plus sign (+) followed by the country code and subscriber number (e.g., +12025550170). If you are using a tool like cURL, ensure the + sign is URL-encoded as %2B. Incorrect formatting can lead to the API reporting the number as invalid or unprocessable rather than a general system error. Refer to the Veriphone documentation on phone number formatting for specifics.

  • Network Issues / Firewall: Ensure that your development environment or server has outbound access to api.veriphone.io. Corporate firewalls or local security software can sometimes block API requests. Attempting the request from a different network or temporarily disabling local firewall rules can help diagnose this.

  • Exceeded Free Tier Limits: While Veriphone offers a free tier, it is limited to 1,000 requests per month. If you have made numerous testing calls, you might have hit this limit, resulting in an error indicating exceeded usage. Check your dashboard for current usage statistics. If the limit is reached, you may need to wait until the next billing cycle or upgrade your plan.

  • JSON Response Parsing Error: If your code is attempting to parse the API response and encountering errors, first confirm that the raw response is indeed valid JSON. Tools like online JSON validators can confirm this. If the API returns a non-200 status code (e.g., 401, 403, 429, 5xx), the response body might contain an error object or plain text, not the expected successful validation JSON. Your code should check the HTTP status code before attempting to parse the body as a successful API response.

  • Refer to Documentation: The Veriphone documentation includes a section on error codes that provides specific details for common issues. Reviewing this section can often pinpoint the exact problem based on the error message received.