TruecallerPy

https://github.com/sumithemmadi/truecallerpy
Admin
TruecallerPy is a Python package that enables phone number search, user authentication, and OTP...
Tokens:4,560
Snippets:41
Trust Score:7.7
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Truecallerpy

Source: https://github.com/sumithemmadi/truecallerpy/blob/main/README.md

Install the package via pip.

```bash
pip install truecallerpy
```

--------------------------------

### Installation

Source: https://github.com/sumithemmadi/truecallerpy/blob/main/README.md

Install the TruecallerPy package using pip.

```APIDOC
## Installation

You can install the TruecallerPy package using pip:

```bash
pip install truecallerpy
```
```

--------------------------------

### TruecallerPy CLI commands

Source: https://context7.com/sumithemmadi/truecallerpy/llms.txt

Terminal commands for authentication, retrieving installation IDs, and performing lookups.

```bash
# Login to Truecaller (interactive prompt for phone number and OTP)
truecallerpy login

# Get your installation ID
truecallerpy --installationid
truecallerpy -i -r  # Raw output (ID only)

# Search for a phone number
truecallerpy -s 1234567890
truecallerpy -s +1234567890 -r  # Raw JSON output

# Extract specific information
truecallerpy -s 1234567890 --name      # Print only the name
truecallerpy -s 1234567890 --email     # Print only the email
truecallerpy -s 1234567890 --name -r   # Raw name output

# Bulk search multiple numbers
truecallerpy --bs 9912345678,+14051234567,+919987654321
truecallerpy --bs 9912345678,+14051234567 -r  # Raw JSON output
```

--------------------------------

### Search for a phone number using Python

Source: https://context7.com/sumithemmadi/truecallerpy/llms.txt

Retrieves contact details like name, email, and phone metadata for a single number. Requires a valid installation ID.

```python
import asyncio
import json
from truecallerpy import search_phonenumber

async def search_number():
    phone_number = "+1234567890"
    country_code = "US"
    installation_id = "your_installation_id_here"

    result = await search_phonenumber(phone_number, country_code, installation_id)

    if result.get("status_code") == 200:
        data = result["data"]

        # Extract contact information
        if "data" in data and len(data["data"]) > 0:
            contact = data["data"][0]

            # Get name
            name = contact.get("name", "Unknown")
            print(f"Name: {name}")

            # Get phone details
            phones = contact.get("phones", [])
            for phone in phones:
                print(f"Phone: {phone.get('e164Format')}")
                print(f"Number Type: {phone.get('numberType')}")
                print(f"Carrier: {phone.get('carrier')}")

            # Get email addresses
            internet_addresses = contact.get("internetAddresses", [])
            for addr in internet_addresses:
                print(f"Email: {addr.get('id')}")

            # Get address
            addresses = contact.get("addresses", [])
            for addr in addresses:
                print(f"City: {addr.get('city')}")
                print(f"Country: {addr.get('countryCode')}")

        # Print full JSON response
        print("\nFull Response:")
        print(json.dumps(data, indent=2))
    else:
        print(f"Search failed: {result.get('message')}")

asyncio.run(search_number())
```

--------------------------------

### Verify OTP with TruecallerPy

Source: https://context7.com/sumithemmadi/truecallerpy/llms.txt

Verifies the OTP received on the phone number and returns an installation ID upon successful verification. This function requires the phone number, login response data, and the OTP. It checks for successful verification, invalid OTP, or suspended accounts.

```python
import asyncio
from truecallerpy import login, verify_otp

async def complete_verification():
    phone_number = "+1234567890"

    # Step 1: Initiate login
    login_response = await login(phone_number)

    if login_response.get("status_code") != 200:
        print("Login initiation failed")
        return None

    login_data = login_response["data"]

    # Step 2: Verify OTP (replace with actual OTP received)
    otp = "123456"
    verify_response = await verify_otp(phone_number, login_data, otp)

    if verify_response.get("status_code") == 200:
        data = verify_response["data"]
        if data.get("status") == 2 and not data.get("suspended"):
            print(f"Installation ID: {data.get('installationId')}")
            print(f"User ID: {data.get('userId')}")
            print(f"TTL: {data.get('ttl')} seconds")
            print(f"Phones: {data.get('phones')}")
            # Store installationId for future searches
            return data["installationId"]
        elif data.get("status") == 11:
            print("Invalid OTP")
        elif data.get("suspended"):
            print("Account suspended")
    else:
        print(f"Verification error: {verify_response.get('message')}")

    return None

# Run the async function
installation_id = asyncio.run(complete_verification())

# Expected output on success:
# Installation ID: a]--XXXXXXXXXXXX...
# User ID: 123456789
# TTL: 86400 seconds
# Phones: [{'phoneNumber': '1234567890', 'countryCode': 'US', 'priority': 1}]
```

--------------------------------

### Search Phone Number with TruecallerPy

Source: https://github.com/sumithemmadi/truecallerpy/blob/main/README.md

Performs a lookup for a specific phone number using the search_phonenumber function. Requires a valid installation ID.

```python
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)
```

--------------------------------

### Login via CLI

Source: https://github.com/sumithemmadi/truecallerpy/blob/main/README.md

Initiate the login process for your Truecaller account.

```bash
truecallerpy login
```

--------------------------------

### Complete Authentication and Search Flow in Python

Source: https://context7.com/sumithemmadi/truecallerpy/llms.txt

This Python script demonstrates the full authentication process, including requesting and verifying OTP, followed by single and bulk phone number searches. It requires an active asyncio event loop and the truecallerpy library. Ensure you replace placeholder phone numbers and OTPs with valid credentials.

```python
import asyncio
import json
from truecallerpy import login, verify_otp, search_phonenumber, bulk_search

class TruecallerClient:
    def __init__(self):
        self.installation_id = None
        self.country_code = None

    async def authenticate(self, phone_number: str, otp: str) -> bool:
        """Complete authentication flow."""
        # Step 1: Request OTP
        print(f"Requesting OTP for {phone_number}...")
        login_response = await login(phone_number)

        if login_response.get("status_code") != 200:
            print(f"Login failed: {login_response.get('message')}")
            return False

        login_data = login_response["data"]
        if login_data.get("status") not in [1, 9] and login_data.get("message") != "Sent":
            print(f"OTP request failed: {login_data.get('message')}")
            return False

        print("OTP sent successfully!")

        # Step 2: Verify OTP
        print(f"Verifying OTP...")
        verify_response = await verify_otp(phone_number, login_data, otp)

        if verify_response.get("status_code") != 200:
            print(f"Verification failed: {verify_response.get('message')}")
            return False

        verify_data = verify_response["data"]
        if verify_data.get("status") == 2 and not verify_data.get("suspended"):
            self.installation_id = verify_data["installationId"]
            self.country_code = verify_data["phones"][0]["countryCode"]
            print(f"Authentication successful!")
            print(f"Installation ID: {self.installation_id}")
            return True

        print(f"Verification failed: {verify_data.get('message', 'Unknown error')}")
        return False

    async def search(self, phone_number: str) -> dict:
        """Search for a single phone number."""
        if not self.installation_id:
            raise ValueError("Not authenticated. Call authenticate() first.")

        result = await search_phonenumber(
            phone_number,
            self.country_code,
            self.installation_id
        )
        return result

    async def bulk(self, phone_numbers: list) -> dict:
        """Search for multiple phone numbers."""
        if not self.installation_id:
            raise ValueError("Not authenticated. Call authenticate() first.")

        numbers_str = ",".join(phone_numbers)
        result = await bulk_search(
            numbers_str,
            self.country_code,
            self.installation_id
        )
        return result

async def main():
    client = TruecallerClient()

    # Authenticate (replace with actual phone and OTP)
    authenticated = await client.authenticate("+1234567890", "123456")

    if authenticated:
        # Single search
        result = await client.search("+9876543210")
        print("\nSingle Search Result:")
        print(json.dumps(result, indent=2))

        # Bulk search
        numbers = ["+1111111111", "+2222222222", "+3333333333"]
        bulk_result = await client.bulk(numbers)
        print("\nBulk Search Result:")
        print(json.dumps(bulk_result, indent=2))

asyncio.run(main())

```

--------------------------------

### Command Line Usage - Login

Source: https://github.com/sumithemmadi/truecallerpy/blob/main/README.md

Log in to your Truecaller account via the command line.

```APIDOC
## Login

To log in to your Truecaller account, use the following command:

```bash
truecallerpy login
```

If you encounter any errors, try running the command with administrative privilege (e.g., `sudo truecallerpy login` on Linux or running the command prompt as administrator on Windows).
```

--------------------------------

### Retrieve InstallationId via CLI

Source: https://github.com/sumithemmadi/truecallerpy/blob/main/README.md

Commands to fetch the Truecaller InstallationId.

```bash
truecallerpy --installationid
```

```bash
truecallerpy -i -r
```

--------------------------------

### Command Line Usage - InstallationId

Source: https://github.com/sumithemmadi/truecallerpy/blob/main/README.md

Retrieve your Truecaller InstallationId using the command line.

```APIDOC
## InstallationId

To retrieve your Truecaller InstallationId, use the following command:

```bash
truecallerpy --installationid
```

You can also specify the `-i` flag to print only the InstallationId:

```bash
truecallerpy -i -r
```
```

--------------------------------

### Basic Usage - Login Function

Source: https://github.com/sumithemmadi/truecallerpy/blob/main/README.md

Use the `login` function in Python to log in to Truecaller.

```APIDOC
## Login Function

The `login` function is used to log in to the Truecaller service. It takes a phone number in international format as a parameter and returns a dictionary containing the login response details.

```python
import asyncio
from truecallerpy import login

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

The `login` function returns a dictionary with the following keys:

- `status_code` (int): The status code of the request.
- `status` (int): The status code of the truecaller login request.
- `message` (str): A message indicating the status of the login request.
- `domain` (str): The domain associated with the phone number.
- `parsedPhoneNumber` (int): The phone number without the country code.
- `parsedCountryCode` (str): The country code associated with the phone number.
- `requestId` (str): The unique identifier for the login request.
- `method` (str): The method used for sending the OTP.
- `tokenTtl` (int): The time-to-live (TTL) value for the OTP token in seconds.
```

--------------------------------

### Initiate Login with TruecallerPy

Source: https://context7.com/sumithemmadi/truecallerpy/llms.txt

Initiates the Truecaller login process by sending an OTP to the specified phone number. Requires the phone number in international format. The response contains status, message, request ID, method, and token TTL.

```python
import asyncio
from truecallerpy import login

async def initiate_login():
    phone_number = "+1234567890"
    response = await login(phone_number)

    if response.get("status_code") == 200:
        data = response["data"]
        print(f"Status: {data.get('status')}")
        print(f"Message: {data.get('message')}")
        print(f"Request ID: {data.get('requestId')}")
        print(f"Method: {data.get('method')}")
        print(f"Token TTL: {data.get('tokenTtl')} seconds")
        # Store response data for OTP verification
        return data
    else:
        print(f"Error: {response.get('message')}")
        return None

# Run the async function
login_data = asyncio.run(initiate_login())

# Expected output:
# Status: 1
# Message: Sent
# Request ID: abc123xyz...
# Method: sms
# Token TTL: 300 seconds
```

--------------------------------

### Bulk Search via CLI

Source: https://github.com/sumithemmadi/truecallerpy/blob/main/README.md

Perform a bulk search for multiple phone numbers separated by commas.

```bash
truecallerpy --bs 9912345678,+14051234567,+919987654321
```

--------------------------------

### Search Phone Numbers via CLI

Source: https://github.com/sumithemmadi/truecallerpy/blob/main/README.md

Search for phone numbers using various CLI flags for output formatting.

```bash
truecallerpy -s [number]
```

```bash
truecallerpy -s 1234567890
```

```bash
truecallerpy -s 1234567890 -r
```

```bash
truecallerpy -s 1234567890 --name
```

--------------------------------

### Login Function in Python

Source: https://github.com/sumithemmadi/truecallerpy/blob/main/README.md

Use the login function to authenticate with a phone number in international format.

```python
import asyncio
from truecallerpy import login

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

--------------------------------

### Command Line Usage - Searching a Number

Source: https://github.com/sumithemmadi/truecallerpy/blob/main/README.md

Search for a phone number using the Truecaller CLI.

```APIDOC
## Searching a Number

To search for a phone number using Truecaller, use the following command:

```bash
truecallerpy -s [number]
```

For example:

```bash
truecallerpy -s 1234567890
```

The command will return a JSON response containing information about the phone number.

You can use the `-r` flag to get the raw output (JSON) instead of the formatted output. For example:

```bash
truecallerpy -s 1234567890 -r
```

You can also use additional flags to extract specific information. For example, to print only the name associated with the phone number, use the `--name` flag:

```bash
truecallerpy -s 1234567890 --name
```

Similarly, you can use the `--email` flag to print only the email associated with the phone number.
```

--------------------------------

### Command Line Usage - Bulk Phone Number Search

Source: https://github.com/sumithemmadi/truecallerpy/blob/main/README.md

Perform a bulk search for multiple phone numbers using the Truecaller CLI.

```APIDOC
## Bulk Phone Number Search with cli

To perform a bulk search for multiple phone numbers, use the `--bs` flag followed by the numbers separated by commas. For example:

```bash
truecallerpy --bs 9912345678,+14051234567,+919987654321
```
```

--------------------------------

### Verify OTP with TruecallerPy

Source: https://github.com/sumithemmadi/truecallerpy/blob/main/README.md

Uses the verify_otp function to validate a mobile number with a received OTP. Requires the JSON response from a previous login function call.

```python
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)
```

--------------------------------

### OTP Verification

Source: https://github.com/sumithemmadi/truecallerpy/blob/main/README.md

Verifies a mobile number using an OTP received from Truecaller.

```APIDOC
## OTP Verification

### Description
The verify_otp function is used to verify the mobile number with the OTP (One-Time Password) received.

### Parameters
#### Request Body
- **phone_number** (str) - Required - The phone number to verify.
- **json_data** (dict) - Required - The JSON response from the login function.
- **otp** (str) - Required - The OTP received.

### Response
#### Success Response (200)
- **status_code** (int) - The status code of the request.
- **status** (int) - The status code of the truecaller OTP verification.
- **message** (str) - A message indicating the result of the OTP verification.
- **installationId** (str) - The installation ID associated with the verified number.
- **ttl** (int) - The time-to-live (TTL) value for the verification result in seconds.
- **userId** (int) - The user ID associated with the verified number.
- **suspended** (bool) - Indicates whether the account is suspended.
- **phones** (list) - List of phone numbers associated with the user.
```

--------------------------------

### Perform Bulk Phone Number Search

Source: https://github.com/sumithemmadi/truecallerpy/blob/main/README.md

Uses the bulk_search function to query multiple phone numbers simultaneously. Phone numbers should be provided as a comma-separated string.

```python
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)
```

--------------------------------

### Bulk Phone Number Search

Source: https://github.com/sumithemmadi/truecallerpy/blob/main/README.md

Performs a bulk search for a list of phone numbers.

```APIDOC
## Bulk Phone Number Search

### Description
The bulk_search function allows you to perform a bulk search for a list of phone numbers using the Truecaller API.

### Parameters
#### Request Body
- **phone_numbers** (str) - Required - A comma-separated string of phone numbers.
- **country_code** (str) - Required - The country code for the phone numbers.
- **installation_id** (str) - Required - The installation ID.
```

--------------------------------

### Phone Number Search

Source: https://github.com/sumithemmadi/truecallerpy/blob/main/README.md

Searches for information about a specific phone number.

```APIDOC
## Phone Number Search

### Description
The search_phonenumber function allows you to search for a phone number using the Truecaller API.

### Parameters
#### Request Body
- **phone_number** (str) - Required - The phone number to search.
- **country_code** (str) - Required - The country code for the phone number.
- **installation_id** (str) - Required - The installation ID.
```
Tokens:
Raw