TruecallerPy 1.0.3

Install the truecallerpy package using pip to access both the CLI and the Python API.

pip install truecallerpy

Both search_phonenumber and bulk_search return a dictionary with a consistent structure to handle both successful lookups and HTTP errors:

On Success:

• status_code: The HTTP status code (e.g., 200).
• data: The JSON payload returned by the Truecaller API.

On HTTP Error:

• status_code: The HTTP status code returned by the server (if available).
• error: The string "HTTP Error".
• message: A descriptive error message starting with "An HTTP error occurred: ".

The login function initiates a login request for a phone number in international format. It is an asynchronous function and returns a dictionary containing request details needed for OTP verification.

import asyncio
from truecallerpy import login

phone_number = "+1234567890"
response = asyncio.run(login(phone_number))
print(response)

Perform a bulk search for multiple phone numbers using the Truecaller API. This function is asynchronous.

import asyncio
from truecallerpy import bulk_search

phone_numbers = "+1234567890,9876543210"
country_code = "US"
installation_id = "Installation ID"

response = asyncio.run(bulk_search(phone_numbers, country_code, installation_id))
print(response)

The verify_otp function verifies the mobile number using the OTP received. It requires the phone number, the JSON response dictionary obtained from the login function, and the OTP string.

import asyncio
from truecallerpy import verify_otp

phone_number = "+1234567890"
json_data = {
   # JSON response from the login function
}
otp = "123456"

response = asyncio.run(verify_otp(phone_number, json_data, otp))
print(response)

Search for a specific phone number using the Truecaller API. This function is asynchronous.

import asyncio
from truecallerpy import search_phonenumber

phone_number = "+1234567890"
country_code = "US"
installation_id = "Your installation ID"

response = asyncio.run(search_phonenumber(phone_number, country_code, installation_id))
print(response)

To get your InstallationId, use the --installationid flag. You can use the -i and -r flags to print only the raw InstallationId.

truecallerpy --installationid
# Or to print only the ID:
truecallerpy -i -r

Search for a single phone number using the -s flag.

Available flags:

• -s [number]: The phone number to search.
• -r: Returns the raw JSON output instead of formatted text.
• --name: Returns only the name associated with the number.
• --email: Returns only the email associated with the number.

truecallerpy -s 1234567890
# Raw JSON output:
truecallerpy -s 1234567890 -r
# Only name:
truecallerpy -s 1234567890 --name

Perform a bulk search for multiple numbers by using the --bs flag followed by a comma-separated list of numbers.

truecallerpy --bs 9912345678,+14051234567,+919987654321

Use the search_phonenumber asynchronous function to look up details for a specific phone number. It requires the phone number, a country code (e.g., 'US', 'IN'), and a valid installationId obtained via the login process. The function uses phonenumbers to parse the input and returns a dictionary containing the HTTP status code and the search data.

import asyncio
from truecallerpy.search import search_phonenumber

async def main():
    result = await search_phonenumber(
        phoneNumber="919876543210",
        countryCode="IN",
        installationId="YOUR_INSTALLATION_ID"
    )
    print(result)

asyncio.run(main())

The login function initiates the Truecaller authentication process by requesting an OTP (One-Time Password) for a specified phone number. It requires the phone number to be in international format.

Returns: A dictionary containing the HTTP status_code and the response data. The data object typically contains a requestId which is required for the subsequent OTP verification step.

from truecallerpy import login

# phone_number must be in international format
response = await login("+1234567890")

if response['status_code'] == 200:
    request_id = response['data']['requestId']
    print(f"OTP requested. Request ID: {request_id}")
else:
    print(f"Login failed: {response.get('message')}")