Overview

The Lookup API checks phone numbers before you call or message them. An HLR lookup shows whether a mobile number is active, which network it is on, and whether it is roaming or ported. A validation lookup checks whether a number is valid. You can look up one number in real time or many numbers in an asynchronous task.

Send requests to https://api.commpeak.com/lookup with your Portal API key in the Authorization header. The key needs Full access (all services). For your first request, see Getting Started with CommPeak APIs.

Token

Get your token balance and rates to see your remaining lookup credits and the cost of each lookup type. For example:

{
  "credits": 465.28,
  "types": {
    "hlr": 0.003,
    "validate": 0
  }
}

Single lookups

Look up a single number in real time with GET /sync/{request_type}/{request_key}, where request_type is hlr or validate and request_key is the phone number. The result comes back in the same response.

Bulk lookups

To check many numbers, create an asynchronous task and collect the results later:

• Create a task for several phone numbers with POST /async/{req_type}, sending the numbers in the request body. Each number can carry a uid that is returned with its result.
• Create a task from a file with POST /async_upload/{request_type}, uploading the numbers as a file.

Both return a task_id. You can also pass a respond_url to get a webhook when the task is complete.

Task results

Get the task details to check whether a task is complete, with its counts and cost. Once it is, get the results per number or download them as a file.

Search

Search lookup results across past tasks by phone number, task ID, date range, lookup type, validation outcome, number type, or country.