# Truecaller API Reference

## Death of Guest Registration

As of mid-2025, all guest/install endpoints return 404:
- `api4.truecaller.com/v1/sessions/install` → 404
- `app-tr.truecaller.com/v1/sessions/install` → NXDOMAIN / 404
- `search5-noneu.truecaller.com/v1/sessions/install` → 404

No known bypass or hardcoded install token works. Old tokens from GitHub return "Account suspended" (401).

## Current OTP Flow

### Step 1: Send OTP

```
POST https://account-asia-south1.truecaller.com/v2/sendOnboardingOtp
```

Headers:
```
content-type: application/json; charset=UTF-8
accept-encoding: gzip
user-agent: Truecaller/11.75.5 (Android;10)
clientsecret: lvc22mp3l1sfv6ujg83rd17btt
```

Body:
```json
{
  "countryCode": "US",
  "dialingCode": 1,
  "installationDetails": {
    "app": {"buildVersion": 5, "majorVersion": 11, "minorVersion": 7, "store": "GOOGLE_PLAY"},
    "device": {
      "deviceId": "<16-char random>",
      "language": "en",
      "manufacturer": "Google",
      "model": "Pixel 8",
      "osName": "Android",
      "osVersion": "14",
      "mobileServices": ["GMS"]
    },
    "language": "en"
  },
  "phoneNumber": "<national digits>",
  "region": "region-2",
  "sequenceNo": 2
}
```

Response (200):
```json
{"status": 20003, "message": "Verification failed", "domain": "noneu", "requestId": "<uuid>"}
```

Note: "Verification failed" is misleading — the SMS is still sent.

### Step 2: Verify OTP

```
POST https://account-asia-south1.truecaller.com/v1/verifyOnboardingOtp
```

Body:
```json
{
  "phoneNumber": "<national digits>",
  "requestId": "<uuid from step 1>",
  "otp": "<6-digit code>"
}
```

Response: Returns `installationId` used as Bearer token.

### Step 3: Search

```
GET https://search5-noneu.truecaller.com/v2/search?q=<digits>&countryCode=US&type=4&locAddr=&encoding=json
```

Headers:
```
authorization: Bearer <installationId>
accept: application/json
user-agent: Truecaller/14.40.7 (Android;11)
```

Requires HTTP/2 (`httpx[http2]`). Returns full profile: name, score, spamInfo, phones[], addresses[], internetAddresses[], image.

## TruecallerPy Integration

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

# Login (sends OTP)
result = asyncio.run(login('+1XX****XXXX'))
# result['data']['requestId']

# Verify OTP
verify_result = asyncio.run(verify_otp('+1XX****XXXX', result['data'], '123456'))
# verify_result['installationId']

# Search
result = asyncio.run(search_phonenumber(
    phoneNumber='123****890',  # national digits
    countryCode='US',
    installationId='<token>'
))
```

## Token Storage

Store in `config.json`:
```json
{"truecaller_token": "<installationId>", "truecaller_device_id": "<deviceId>"}
```

Token lifetime: ~24-48 hours. Re-run login when expired.