# Truecaller Lookup API

Authenticated JSON API that looks up phone numbers via a real, logged-in
Truecaller app driven over ADB.

## Authentication
Send your API key on every `/action` request, either header works:

    Authorization: Bearer <API_KEY>
    X-API-Key: <API_KEY>

## Endpoints

### `GET /health`
Service + device status (no auth).

    curl -s https://truecaller.uptimemonitor.live/health

### `POST /action`
Look up a number (or search a name).

| field    | type   | notes                                              |
|----------|--------|----------------------------------------------------|
| number   | string | phone number; add country code for non-Indian      |
| type     | string | `lookup` (default) or `search`                     |
| detail   | bool   | `true` = open the full profile page (~3s slower)   |

#### Look up a number
    curl -s -X POST https://truecaller.uptimemonitor.live/action \
      -H "Authorization: Bearer <API_KEY>" \
      -H "Content-Type: application/json" \
      -d '{"number":"8104515596"}'

#### With full profile (carrier / location / call history)
    curl -s -X POST https://truecaller.uptimemonitor.live/action \
      -H "Authorization: Bearer <API_KEY>" \
      -H "Content-Type: application/json" \
      -d '{"number":"8104515596","detail":true}'

#### Search by name
    curl -s -X POST https://truecaller.uptimemonitor.live/action \
      -H "Authorization: Bearer <API_KEY>" \
      -H "Content-Type: application/json" \
      -d '{"type":"search","number":"Jane Doe"}'

## Response shape
    {
      "ok": true,
      "type": "lookup",
      "result": {
        "query": "...",
        "found": true,
        "identities": [ { "name": "...", "subtitle": "...", "looks_like_number": true } ],
        "screen_text": [ "..." ],
        "detail_screen_text": [ "..." ]   // only when detail=true
      }
    }

## Errors
| code | meaning                         |
|------|---------------------------------|
| 401  | missing / invalid API key       |
| 403  | origin not in the allowlist     |
| 422  | bad input (missing/invalid arg) |
| 503  | phone locked / not connected    |
| 502  | lookup automation failed        |

_~6s per lookup. Requires the phone connected and Truecaller logged in._