Numlookup Getting Started: API Key & First Request (2026)

Getting started overview

Integrating with Numlookup involves a series of steps designed to get you from account creation to a successful API call. This guide focuses on the essential actions required: account registration, obtaining your unique API key, and executing your initial request to validate a phone number. Numlookup offers a straightforward REST API that responds with JSON, making it accessible for developers across various programming environments.

The primary use cases for Numlookup include basic phone number validation, caller identification, and fraud prevention. The service provides a free tier for initial testing, offering 100 lookups per month. For extended usage, paid plans begin at $29 per month for 2,000 lookups.

Before proceeding, ensure you have an internet connection and a development environment capable of making HTTP requests. This typically involves a command-line tool like curl or a programming language with HTTP client libraries (e.g., Python's requests, Node.js's axios).

Getting started quick reference

The following table provides a high-level overview of the steps to get started with Numlookup:

Create an account and get keys

To access the Numlookup API, you must first create an account and obtain an API key. This key serves as your authentication credential for all API requests.

Account registration

1. Navigate to the Numlookup homepage.
2. Click on the "Sign Up" or "Get API Key" button, typically located in the top right corner or prominent on the landing page.
3. Provide the required information, which usually includes your email address and a password.
4. Agree to the terms of service and privacy policy. Numlookup is GDPR compliant.
5. Complete any email verification steps if prompted. This typically involves clicking a link sent to your registered email address.

API key retrieval

Once your account is active and you are logged in, your API key will be available in your developer dashboard:

1. Log in to your Numlookup account.
2. Look for a section labeled "API Keys," "Developer Settings," or similar. This is commonly found in the sidebar or a settings menu.
3. Your unique API key will be displayed. It is a long alphanumeric string. Copy this key securely, as it is essential for authenticating your API calls. Treat your API key like a password; do not expose it in client-side code or public repositories.

Your first request

After obtaining your API key, you are ready to make your first request to the Numlookup API. This example demonstrates a basic phone number lookup.

API endpoint

The primary endpoint for phone number lookups is typically structured as follows:

GET https://api.numlookup.com/api/v1/validate?number={phone_number}&apikey={your_api_key}

Replace {phone_number} with the number you wish to validate (e.g., +15551234567, including the country code) and {your_api_key} with the API key you retrieved from your dashboard.

Example using curl

curl is a command-line tool for making HTTP requests and is widely available on most operating systems, making it suitable for a quick first test. This example assumes you have an API key and a phone number to test.

curl -X GET "https://api.numlookup.com/api/v1/validate?number=+15551234567&apikey=YOUR_API_KEY_HERE"

Remember to replace YOUR_API_KEY_HERE with your actual API key and +15551234567 with the phone number you intend to look up, ensuring it includes the international dialing code. For more information on constructing HTTP requests, refer to MDN Web Docs on the HTTP GET method.

Expected response

A successful request will return a JSON object containing details about the phone number. The exact fields may vary, but a typical successful response for a valid number might look like this:

{
  "valid": true,
  "number": "+15551234567",
  "international_format": "+1 555-123-4567",
  "country_code": "US",
  "country_name": "United States",
  "carrier": "AT&T Mobility",
  "line_type": "mobile",
  "location": "New York"
}

If the number is invalid or an error occurs, the valid field might be false, and an error field with a descriptive message might be present.

Common next steps

After successfully making your first API call, consider these next steps for further integration and development:

• Implement error handling: Design your application to gracefully handle API errors, such as invalid API keys, rate limit exceedances, or malformed requests. Check the HTTP status codes and the JSON error messages in the response.
• Explore other endpoints: Review the Numlookup documentation for additional API endpoints, such as reverse phone lookup if applicable, or more advanced validation options.
• Integrate into your application: Incorporate the API calls into your preferred programming language and framework. Many languages offer robust HTTP client libraries that simplify making requests and parsing JSON responses.
• Monitor usage: Keep track of your API call usage through your Numlookup dashboard to ensure you stay within your plan limits.
• Secure your API key: Ensure your API key is stored securely and not hardcoded directly into your application's source code, especially in production environments. Consider using environment variables or a secrets management service.

Troubleshooting the first call

If your first API call doesn't return the expected results, consider the following common issues and troubleshooting steps:

• Invalid API Key: Double-check that you have copied your API key correctly from your Numlookup dashboard. An incorrect key will typically result in an authentication error (e.g., HTTP 401 Unauthorized).
• Incorrect Phone Number Format: Ensure the phone number includes the correct international dialing code (e.g., +1 for the United States, +44 for the United Kingdom). Missing the plus sign or the country code can lead to validation failures or incorrect results.
• Network Connectivity: Verify that your development environment has a stable internet connection and can reach the Numlookup API endpoint.
• Typos in URL or Parameters: Review the API endpoint URL and parameter names (number, apikey) for any typographical errors. Even a small mistake can prevent the request from being processed correctly.
• Rate Limits: If you are making many requests in quick succession, you might hit a rate limit. Check your Numlookup developer documentation for information on rate limits and how to handle them (e.g., with exponential backoff).
• HTTP Status Codes: Pay attention to the HTTP status code returned in the response. Common error codes include:
• 400 Bad Request: Often indicates an issue with the request parameters (e.g., malformed phone number).
• 401 Unauthorized: Typically means an invalid or missing API key.
• 403 Forbidden: May indicate insufficient permissions or a blocked IP address.
• 429 Too Many Requests: You have exceeded the API rate limits.
• 5xx Server Error: Indicates an issue on the Numlookup server side.
• Check Documentation: Refer to the official Numlookup API documentation for the most up-to-date information on endpoints, parameters, and error codes.