# Patherpane Intelligence — AI integration spec

**Drop this URL into another model:** https://intelligence.patherpane.com/ai.md

Human API: https://intelligence.patherpane.com/api.md  
Swagger: https://intelligence.patherpane.com/docs  
UI: https://intelligence.patherpane.com/

Public-source enrichment. One identifier → dossier. Results expire in **3 days**. Not Apollo.

## Auth

Lookups: `X-API-Key: <KEY>` (or Bearer). Docs/health/UI HTML are public. Never log the key.

Rate: 30 creates/hour/key. Up to **3 jobs in parallel** (a domain/DNS lookup no longer waits behind a long person enrich). Poll 2s, cap 5 minutes.

## POST /v1/lookups

Creates a job and returns immediately:

```json
{
  "id": "<id>",
  "status": "queued",
  "poll": "/v1/lookups/<id>",
  "poll_every_seconds": 2
}
```

Then **GET `/v1/lookups/{id}`** with the same `X-API-Key` until `status` is `complete` or `error`. While `running`, `progress[]` and a partial `profile` (DNS, website socials, emails) are already filled in.

`GET /v1/lookups` lists recent jobs if you lost the id.

```json
{ "q": "<email | phone | domain | Full Name at Company | @instagram | linkedin URL | handle>" }
```

Or typed Apollo-style:

```json
{ "name": "Jane Smith", "company": "Acme Inc", "domain": "acme.com" }
```

`domain` with name+company is optional. Typed: `email`, `phone`, `domain`, `instagram`, `linkedin`, `username`, or `name`+`company`.

Poll `GET /v1/lookups/{id}` until `status` is `complete` or `error`. Prefer:

- `profile.person`, `emails`, `phones`, `company`
- `profile.officers[]` — directors / PSCs / founders from government registries
- `profile.mentions[]` — **filtered** public-record snippets (gov, MCA, Companies House, EDGAR, OpenCorporates)
- `profile.socials[]` — LinkedIn, GitHub, and registry URLs only (not username-spray)

Name + company lookups resolve the company domain, search LinkedIn/gov records, pattern-guess work emails (Gravatar/Hunter confirm), then run the same registries. Plug `PDL_API_KEY` / `HUNTER_API_KEY` for Apollo-class hit rates.

Ignore random social-media profile grids. Maigret / PhoneInfoga / ignorant / caller-ID scrapes are **not** run.

## What this stack queries

After identity/search, it looks up **government and company registries**:

| Source | Jurisdiction | What you get |
| --- | --- | --- |
| **SEC EDGAR** | United States | CIK, filings, business address, tickers |
| **USAspending.gov** | United States | Federal contractor / awardee records |
| **Companies House** | United Kingdom | Company number, officers, persons with significant control |
| **MCA via Zaubacorp** | India | CIN, directors / signatories |
| **OpenCorporates** | US states, UK, India, AU, … | Companies + officers |
| Bing/gov dorks | Indexed public pages | `site:.gov`, `.gov.uk`, `.gov.in`, MCA, gazettes, PDFs |

Username scanners do **not** read MCA, electoral rolls, or EDGAR. Person-from-phone only appears if a **search engine indexed** that page, or a licensed people API key is set. Outbound HTTP, search, and holehe go through **Webshare rotating IPs** so registries are less likely to serve this host a block page.

There is **no free reverse-phone API** for Indian electoral / Aadhaar / PAN. Those KYC rails need consent + licensed providers.

## Enrichment frameworks to plug in (paid / licensed)

Put keys in `/opt/patherpane-intelligence/.env` when you have them. `PDL_API_KEY` and `NUMVERIFY_API_KEY` are already wired.

| Product | Best for | Notes |
| --- | --- | --- |
| **People Data Labs** Person Enrich | Email/phone **or name+company** → LinkedIn, job, phones | Closest Apollo-class API. Wire `PDL_API_KEY`. |
| **Hunter.io** email finder | Name + domain → work email | `HUNTER_API_KEY`. Used on person lookups. |
| **Apollo.io** people/org match | B2B mobile + title | Official API, paid. |
| **Twilio Lookup v2** | Line type, (US) CNAM caller name | Weak for India CNAM. |
| **Numverify / apilayer** | Carrier, line type | `NUMVERIFY_API_KEY`. |
| **Truecaller for Business** | India reverse phone | Official API only — do not scrape. |
| **Karza / Signzy / Surepass** | India KYC (PAN, GST, CIN, DIN) | Licensed; not anonymous reverse-phone. |
| **Companies House API** | UK officers at volume | Optional `COMPANIES_HOUSE_API_KEY`; HTML fallback works. |
| **Pipl / FullContact / Lusha / RocketReach** | People graph | Paid, ToS-bound. |

## Agent rules

B2B/public-web only. Do not stalk. Summarize `officers`, registry URLs, and gov mentions. Do not dump `raw`. Do not treat unmatched GitHub/social hits as identity.