Phone Number Lookup API

Through this API, you can query the status of mobile phone numbers globally, obtaining detailed information such as number validity, attribution Operator, roaming, and Mobile number porting (MNP) status. This API offers two service levels: Basic and Premium.

Basic: Provides fundamental data (such as Country Code, original attribution Operator, and number format validation). Please note that Basic only returns the original Operator information before the number undergoes Mobile number porting (MNP); if you need to obtain the current Operator information after the number has been ported, please upgrade to Premium.
Premium: On top of Basic, it can further retrieve information such as the current Operator, reachability, roaming status, and Mobile number porting (MNP) status. However, this part of the data relies on the destination country/region's telecommunications regulations and user privacy protection policies, so complete data cannot be guaranteed for all countries and all Operators.

1. Invocation Method

Invocation Method

HTTP Method: GET
Endpoint: https://api.paasoo.com/lookup

2. Request Examples

Basic:

cURL
curl -X GET "https://api.paasoo.com/lookup?key=API_KEY&secret=API_SECRET&number=12025550188"

Premium:

cURL
curl -X GET "https://api.paasoo.com/lookup?key=API_KEY&secret=API_SECRET&number=12025550188&service=premium"

Note

Authentication Parameters: Authenticate via key and secret.
Default Service Level: If service is not specified, it defaults to basic.

3. Request Parameters

Parameter	Type	Required	Description	Example
key	string	Yes	API Key (composed of 8 alphanumeric characters), used to uniquely identify your account. Can be obtained in the PaaSoo dashboard.	Abcdefgh
secret	string	Yes	API Secret (composed of 8 alphanumeric characters), used in conjunction with `key` for authentication. Can be obtained in the PaaSoo dashboard.	Abc123EF
number	string	Yes	The mobile phone number to query. It is recommended to use the full international format (e.g., 12025550188). There is no need to add other leading characters before the Country Code or number.	12025550188
service	string	No	Specifies the query service level: `basic` or `premium`. Defaults to `basic` if not provided.	premium

4. Response Description

Basic: Only provides the initial (pre-ported) Operator information of the number, cannot return real-time Mobile number porting (MNP) information.
Premium: Provides current Operator information, roaming, Mobile number porting (MNP), and other statuses on a best-effort basis. However, complete or up-to-date data may not be available in all regions, subject to local telecommunications regulations and privacy protection requirements.

4.1 Response Parameters

Parameter	Type	Service	Description
requestId	string	basic / premium	The unique ID of the query request, which can be used for log tracking.
number	string	basic / premium	The originally passed phone number to be queried.
format	integer	basic / premium	Validity of the number format: 0 - Invalid number 1 - Correct format
errorCode	string	basic / premium	Request error code: `00 - Successful`: Invocation successful `01 - Insufficient balance`: Arrears or insufficient balance `02 - Wrong credentials`: Incorrect username or password `03 - Missing parameters`: Missing or incorrect parameters `07 - IP limit`: IP Whitelist restriction `08 - No allow hlr`: HLR query permission not activated `13 - Daliy quota exceeded`: Daily verification limit for basic version reached `99 - Other error`: System error
errorDesc	string	basic / premium	Description corresponding to `errorCode`.
cc	string	basic / premium	The Country Code corresponding to the queried number, such as 1.
countryIso	string	basic / premium	The Country Name abbreviation, such as US.
operator	string	basic / premium	The name of the Operator the number belongs to. In the Basic version, this only returns the Operator information when the number was in its original network (unported); to get the current network Operator information, please use Premium.
mccmnc	string	premium	The Operator network code (MCC+MNC), such as 310410; if it cannot be queried, it may not be returned.
reachable	string	premium	Number reachability: `reachable` `unreachable` `unknown` May not be accurately retrieved due to local telecommunications regulations or user privacy restrictions.
ported	string	premium	Mobile number porting (MNP) status: `ported` `not ported` `unknown` If it cannot be queried, it defaults to `unknown`.
portedFrom	string	premium	The network name and network code information before porting, for example, AT&T 310410; If it cannot be retrieved or the number is not ported, it will be empty or `unknown`.
imsi	string	premium	IMSI code information; if it cannot be retrieved, returns `unknown`.

4.2 Basic (Default) Response Example

{
    "requestId": "900249-0c1a64-d000",
    "number": "12025550188",
    "format": 1,
    "errorCode": "00",
    "errorDesc": "Successful",
    "cc": "1",
    "countryIso": "US"
}

4.3 Premium Response Example

{
    "requestId": "900249-0c0aba-2000",
    "number": "12025550188",
    "format": 1,
    "errorCode": "00",
    "errorDesc": "Successful",
    "cc": "1",
    "countryIso": "US",
    "mccmnc": "310410",
    "operator": "AT&T",
    "reachable": "reachable",
    "ported": "not ported",
    "portedFrom": "",
    "imsi": "unknown"
}

5. Error Codes and FAQs

00 - Successful: Invocation successful.
01 - Insufficient balance: Current remaining Balance is insufficient; you need to prepay/recharge or upgrade your account.
02 - Wrong credentials: Incorrect account or password, please check your key and secret.
03 - Missing parameters: Parameters are missing or invalid, please check the request examples.
07 - IP limit: Your request source IP is not in the IP Whitelist.
08 - No allow hlr: The current user account is not subscribed to the Premium version of the HLR query service.
13 - Daliy quota exceeded: The daily query limit for the Basic version has been exhausted.
99 - Other error: System busy or other unknown errors.

6. Best Practices and Precautions

Service Selection:
- Basic: Can only obtain the original Operator information of the number. If you need dynamic information such as the Operator after Mobile number porting (MNP), please use Premium.
- Premium: Obtains current Operator, roaming, and Mobile number porting (MNP) information on a best-effort basis; this feature may be limited by local telecommunications regulations and user privacy protection rules in some countries or regions, resulting in certain information being unretrievable.
Number Format: It is recommended to pass in the full international format number, removing any leading characters like + or 0.
Security: It is strongly recommended to use the HTTPS protocol, combined with an IP Whitelist or other technical means to protect your API Key and Secret.
Account Balance: Ensure there is a sufficient Balance before calling. If a higher quota or a higher-level service is needed, please contact PaaSoo for support.
Request Frequency: If calling frequently, please control concurrency or set reasonable delays to avoid exceeding service limits.
Transmission Delay: Premium queries can provide real-time number status, but attention should still be paid to network latency and the response time of the target Operator.

Support

If you encounter any technical issues or have business inquiries during the API integration, please do not hesitate to contact our Support team at support@paasoo.com. We are always here to assist you.

1. Invocation Method​

2. Request Examples​

Basic:​

Premium:​

3. Request Parameters​

4. Response Description​

4.1 Response Parameters​

4.2 Basic (Default) Response Example​

4.3 Premium Response Example​

5. Error Codes and FAQs​

6. Best Practices and Precautions​