Lookup API

The Lookup API helps you gather and verify phone number information, such as checking if a number is valid, roaming, or part of the "Do Not Call" list. Below is a summary of what the API can do, broken down in simple terms.

What Does the API Do?

• Token Info: Find out how many credits you have left and the cost of different lookup services.
• Look Up Numbers (Sync & Async Requests): Perform either single (sync) or batch (async) lookups to get information about phone numbers, like whether they’re valid or if they’ve been ported to another network.
• Get Results: Retrieve results from previous lookups and download them if needed.
• Search Results: Search for specific information based on lookup jobs you’ve already run.

How to Use the API

1. Check Your Account Info (Token Info)

• What It Does: Tells you how many credits you have left and the cost of different types of lookups.
• How To Use: Send a GET request to /info.
• Example:
  JSON

  {
    "credits": 23.4,
    "types": {
      "hlr": 1.8,
      "validate": 0
    }
  }
  

2. Look Up a Phone Number (Sync Request)

• What It Does: Checks phone number details, such as if it’s roaming, has been ported, or is on the "Do Not Call" list. This happens in real-time.
• How To Use: Send a GET request to /sync/{request_type}/{request_key}, where request_type is what you're checking (e.g., "hlr" for network info) and request_key is the phone number.
• Example:
  JSON

  {
    "cost": 1.2,
    "hlr": {
      "country_name": "United States",
      "is_roaming": false,
      "network_name": "Verizon"
    }
  }
  

3. Batch Phone Lookups (Async Request)

• What It Does: Allows you to look up many phone numbers at once and get the results later.
• How To Use: Send a POST request to /async/{req_type} with the phone numbers in the request body. You’ll get a task ID, and later, you can check the results.
• Example: You’ll get a task ID like task_12345, and later, use that ID to get the results.

4. Upload a File for Bulk Lookups (Async Upload)

• What It Does: You can upload a file containing phone numbers to check in bulk.
• How To Use: Send a POST request to /async_upload/{request_type} with a file containing the phone numbers.

5. Retrieve Your Results

• What It Does: Once you’ve done a lookup (either single or batch), you can get the results.
• How To Use: Send a GET request to /result/{job_id} or /download/{job_id}.

6. Search Through Your Results

• What It Does: Allows you to filter and search through previous results.
• How To Use: Send a POST request to /search_results with search criteria like specific job IDs or country codes.

Key Points to Remember:

• Synchronous (Sync) requests give you immediate results for a phone number.
• Asynchronous (Async) requests let you process large batches of numbers and fetch the results later.
• Always provide your API key in the request header to authenticate your requests.